MeteoIODoc  MeteoIODoc-2.7.0
Data input overview

The data access is handled by a system of plugins. They all offer the same interface, meaning that a plugin can transparently be replaced by another one. Since they might rely on third party libraries for accessing the data, they have been created as plugins, that is they are only compiled if requested when configuring the compilation with cmake. A plugin can therefore fail to run if it has not been compiled.

Please have a look at the support for coordinate systems.

Data sources categories

Several data sources categories have been defined that can be provided by a different plugin. Each data source category is defined by a specific key in the configuration file (usually, io.ini):

  • METEO, for meteorological time series
  • DEM, for Digital Elevation Maps
  • LANDUSE, for land cover information
  • GRID2D, for generic 2D grids (they can contain meteo fields and be recognized as such or arbitrary gridded data)
  • POI, for a list of Points Of Interest that can be used for providing extra information at some specific location (extracting time series at a few selected points, etc)

A plugin is "connected" to a given data source category simply by giving its keyword as value for the data source key:

METEO = SMET
DEM = ARC

Each plugin might have its own specific options, meaning that it might require its own keywords. Please check in each plugin documentation the supported options and keys (see links below). Moreover, a given plugin might only support a given category for read or write (for example, PNG: there is no easy and safe way to interpret a given color as a given numeric value without knowing its color scale, so reading a png has been disabled). Finally, the plugins usually don't implement all these categories (for example, ArcGIS file format only describes 2D grids, so the ARC plugin will only deal with 2D grids), so please check what a given plugin implements before connecting it to a specific data source category.

Available plugins

So far the following plugins have been implemented (by keyword for the io.ini key/value config file). Please read the documentation for each plugin in order to know the plugin-specific keywords:

Plugin keywordProvidesDescriptionExtra requirements
ALPUGmeteodata files generated by the ALPUG meteo stations
A3Dmeteo, poioriginal Alpine3D meteo files
ARCdem, landuse, grid2dESRI/ARC ascii grid files
ARPSdem, grid2d, grid3dARPS ascii formatted grids
BORMAmeteoBorma xml meteo fileslibxml++
CNRMdem, grid2d, meteoNetCDF meteorological timeseries following the CNRM schemaNetCDF-C library
COSMOXMLmeteoMeteoSwiss COSMO's postprocessing XML formatlibxml2
DBOmeteoconnects to SLF's DBO web service interfacelibcurl
GEOTOPmeteoGeoTop meteo files
GRASSdem, landuse, grid2dGrass grid files
GRIBmeteo, dem, grid2dGRIB meteo grid filesgrib-api
GSNmeteoconnects to the Global Sensor Network web service interfacelibcurl
IMISmeteoconnects to the IMIS databaseOracle's OCCI library
NETCDFdem, grid2dNetCDF gridsNetCDF-C library
OSHDmeteoOSHD generated binary Matlab fileslibmatio
PGMdem, grid2dPGM grid files
PNGdem, grid2dPNG grid fileslibpng
PSQLmeteoconnects to PostgreSQL databasePostgreSQL's libpq
SASEmeteoconnects to the SASE databaseMySQL's C API
SMETmeteo, poiSMET data files
SNOWPACKmeteooriginal SNOWPACK meteo files

In order to optimize the data retrieval, the raw data is buffered. This means that up to BUFFER_SIZE days of data will be read at once by the plugin so subsequent reads will not have to get back to the data source (this key is in the [General] section). It is usually a good idea to configure BUFFER_SIZE to the intended duration of the simulation (in days).

Raw data editing

Before any filters, resampling algorithms or data generators are applied, it is possible to edit the original data:

  1. rename certain parameters for all stations;
  2. exclude/keep certain parameters on a per station basis;
  3. merge stations together;
  4. make a copy of a certain parameter under a new parameter name for all stations;
  5. create certain parameters based on some parametrizations.
Note
Please note that the processing order is the following: the MOVE directives are processed first, then the EXCLUDE directives, then the KEEP directives, then the MERGE directives and finally the COPY directives. The CREATE directives only come after all the raw data has been edited.

1. Data renaming (MOVE)

It is possible to rename a meteorological parameter thanks to the MOVE key. This key can take multiple source names that will be processed in the order of declaration. The syntax is new_name::MOVE = {space delimited list of original names}. Original names that are not found in the current dataset will silently be ignored, so it is safe to provide a list that contain many possible names:

TA::MOVE = air_temp air_temperature temperature_air

This can be used to rename non-standard parameter names into standard ones.

2. Data exclusion (EXCLUDE/KEEP)

It is possible to exclude specific parameters from given stations (on a per station basis). This is either done by using the station ID (or the '*' wildcard) followed by "::exclude" as key with a space delimited list of meteorological parameters to exclude for the station as key. Another possibility is to provide a file containing one station ID per line followed by a space delimited list of meteorological parameters to exclude for the station (the path to the file can be a relative path and will be properly resolved).

The exact opposite can also be done, excluding ALL parameters except the ones declared with the "::keep" statement (or a file containing one station ID per line followed by a space delimited list of meteorological parameters to keep for the station).

WFJ2::EXCLUDE = HS PSUM ;inline declaration of parameters exclusion
KLO3::KEEP = TA RH VW DW ;inline declaration of parameters to keep
EXCLUDE_FILE = ../input/meteo/excludes.csv ;parameters exclusions defined in a separate file
KEEP_FILE = ../input/meteo/keeps.csv ;parameters to keep defined in a separate file

In the second example (relying on a separate file), the file "../input/meteo/excludes.csv" could look like this:

WFJ2 TA RH
KLO3 HS PSUM

Another example relying on wildcards (the kept/excluded parameters lists are additive):

*::KEEP = TA RH ;all stations will keep TA and RH and reject the other parameters
WFJ2::KEEP = HS PSUM ;WFJ2 will keep TA and RH as defined above but also HS and PSUM

3. Data merging (MERGE)

It is possible to merge different data sets together, with a syntax similar to the Exclude/Keep syntax. This merging occurs after any EXCLUDE/KEEP commands. This is useful, for example, to provide measurements from different stations that actually share the same measurement location or to build "composite" station from multiple real stations (in this case, using EXCLUDE and/or KEEP commands to fine tune how the composite station(s) is/are built). Please note that the order of declaration defines the priority (ie the first station that has a value for a given parameter has priority). Please also note that only common timestamps will be merged! (ie if the stations have different sampling rates, it might end up that no merge gets performed)

STATION1 = STB
STATION2 = WFJ2
STATION3 = WFJ1
STATION4 = DAV1
[...]
STB::EXCLUDE = ILWR PSUM
WFJ2::KEEP = PSUM ILWR RSWR
STB::MERGE = WFJ2 WFJ1
DAV1::MERGE = WFJ2

In order to avoid circular dependencies, a station can NOT receive data from a station AND contribute data to another station. Otherwise, a station can be merged into multiple other stations. Moreover, the merging strategy can be controlled by setting the MERGE_STRATEGY key in the [Input] section (by default it is "STRICT_MERGE", see MeteoData::Merge_Type).

Note
One limitation when handling "extra" parameters (ie parameters that are not in the default meteoparam) is that these extra parameters must be known from the begining. So if station2 appears later in time with extra parameters, make sure that the buffer size is large enough to reach all the way to this new station (by setting General::BUFFER_SIZE at least to the number of days from the start of the first station to the start of the second station)

4. Data copy (COPY)

It is also possible to duplicate a meteorological parameter as another meteorological parameter. This is done by specifying a COPY key, following the syntax new_name::COPY = existing_parameter. For example:

VW_avg::COPY = VW

This creates a new parameter VW_avg that starts as an exact copy of the raw data of VW, for each station. This newly created parameter is then processed as any other meteorological parameter (thus going through filtering, generic processing, spatial interpolations). This only current limitation is that the parameter providing the raw data must be defined for all stations (even if filled with nodata, this is good enough).

5. Data creation (CREATE)

Finally, it is possible to create new data based on some parametrizations. If the requested parameter does not exists, it will be created. Otherwise, any pre-existing data is kept and only missing values in the original data set are filled with the generated values, keeping the original sampling rate. As with all raw data editing, this takes place before any filtering/resampling/data generators. As the available algorithms are the same as for the data generators, they are listed in the data generators section (but the data creators must be declared in the [Input] section).

[Input]
P::create = STD_PRESS #the pressure is filled with STD_PRESS if no measured values are available
ISWR_POT::create = clearSky_SW #a new parameter "ISWR_POT" is created and filled with Clear Sky values

Virtual stations

It is possible to use spatially interpolated meteorological fields or time series of 2D grids to extract meteorological time series for a set of points. This is handled as "virtual stations" since the data will seem to originate from points where no station is present. This is described in the virtual stations page.