WSL/SLF GitLab Repository

Commit d2f5534e authored by Mathias Bavay's avatar Mathias Bavay
Browse files

The data generators have been documented (both for the end user and for the developer).

parent 4265c012
......@@ -29,8 +29,61 @@
namespace mio {
/**
*
*/ //explain how to write a new generator algorithm here
* @page dev_DataGenerator How to write a data generator
* Once the data has been read, filtered and resampled, it can be that some data points are still missing.
* These are either a few isolated periods (a sensor was not functioning) that are too large for performing
* a statistical temporal interpolation or that a meteorological parameter was not even measured. In such a case,
* we generate data, generally relying on some parametrization using other meteorological parameters. In a few
* cases, even fully arbitrary data might be helpful (replacing missing value by a given constant so a model can
* run over the data gap).
*
* @section structure_DataGenerator Structure
* The selection of which data generator to use at any given time step, for a given parameter is
* performed by the DataGenerator class. This class acts as an interface, presenting a higher level view to the
* caller. The data generators themselves derive from the GeneratorAlgorithm class that standardizes their
* public API. An object factory creates the generator during intialization (keeping all constructed generators
* in a vector during the whole life time of the DataGenerator object), based on the strings contained in the user's
* io.ini configuration file.
*
* The API also defines two public "generate" methods, taking a meteorological parameter index (see MeteoData) and either
* a set of meteo data for one station and at one point in time or a meteo time series for one station.
* These methods walk through the meteo data looking for nodata values for the requested meteo parameter index.
* If the generator could successfully generate data for <b>all</b> the nodata values it found, it returns <i>true</i>,
* <i>false</i> otherwise. If <i>false</i> was returned, the DataGenerator object that manages the process would
* call the next data generator, <b>in the order that was declared by the user</b>. For a given meteo parameter, the
* whole process stops as soon as a <i>true</i> is returned or there are no more data generators to try
* (as declared by the user in his configuration file).
*
* @section implementation_DataGenerator Implementation
* It is therefore necessary to create in GeneratorAlgorithms.cc (and declared in the .h) a new class,
* nammed after the generator that will be implemented and inheriting GeneratorAlgorithm. Three methods need
* to be implemented:
* - the constructor with (const std::vector<std::string>& vecArgs, const std::string& i_algo)
* - bool generate(const size_t& param, MeteoData& md)
* - bool generate(const size_t& param, std::vector<MeteoData>& vecMeteo)
*
* The constructor is responsible for parsing the arguments as a vector of strings and saving its own name internally, for
* error messages, warnings, etc. It should set all internal variables it sees fit according to the parsed arguments. The
* goal is <i>to not</i> do any parsing anywhere else (for performances reasons).
*
* The <i>generate(const size_t& param, MeteoData& md)</i> method compares <i>md(param)</i> with <i>IOUtils::nodata</i> and replaces
* it by its generated value if necessary. It returns <i>true</i> if no further processing is needed
* (ie. no replacement was needed or the replacement could be done) or <i>false</i> otherwise.
*
* The <i>generate(const size_t& param, std::vector<MeteoData>& vecMeteo)</i> method compares
* <i>vecMeteo[ii](param)</i> with <i>IOUtils::nodata</i> for each timestamp in the vector and tries to generate data when necessary.
* If all missing data points could be generated (or if no data point required to be generated), it returns <i>true</i>,
* and <i>false</i> otherwise.
*
* Finally, a new entry must be added in the object factory GeneratorAlgorithmFactory::getAlgorithm method at the top of file
* GeneratorAlgorithms.cc.
*
* @section doc_DataGenerator Documentation
* The newly added data generator must be added to the list of available algorithms in
* GeneratorAlgorithms.h with a proper description. Its class must be properly documented, similarly to the other data
* generators. An example can also be given in the example section of the same file.
* Please feel free to add necessary bibliographic references to the bibliographic section!
*/
/**
* @class DataGenerator
......
......@@ -54,6 +54,13 @@ namespace mio {
* - CST: constant value as provided in argument (see ConstGenerator)
* - UNSWORTH: use a Dilley clear sky model coupled with an Unsworth cloud sky model to generate ILWR from TA, RH, ISWR (see UnsworthGenerator)
*
* @section biblio Bibliography
* The data generators have been inspired by the following papers:
* - <i>"Long-wave radiation at the ground"</i>, Unsworth and Monteith, Q. J. R. Meteorolo. Soc., Vol. 101, 1975, pp 13-24
* - <i>"Estimating downward clear sky long-wave irradiance at the surface from screen temperature and precipitable water"</i>, Dilley and O'Brien, Q. J. R. Meteorolo. Soc., Vol. 124, 1998, doi:10.1002/qj.49712454903
* - <i>"Solar and terrestrial radiation dependent on the amount and type of cloud"</i>, Kasten and Czeplak, 1980, Solar energy, 24.2, pp 177-189
*
*
* @author Mathias Bavay
* @date 2013-03-20
*/
......
......@@ -80,6 +80,7 @@ namespace mio {
* -# Expanding MeteoIO
* -# How to \subpage dev_plugins "write a Plugin"
* -# How to \subpage dev_processing "write a processing element"
* -# How to \subpage dev_DataGenerator "Write a data generator"
* -# How to \subpage dev_2Dinterpol "write a spatial interpolation algorithm"
*/
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment