MeteoIODoc 20261119.86f8ff36
Environmental timeseries pre-processing
Loading...
Searching...
No Matches
libacdd.h
Go to the documentation of this file.
1// SPDX-License-Identifier: LGPL-3.0-or-later
2/***********************************************************************************/
3/* Copyright 2020 WSL Institute for Snow and Avalanche Research SLF-DAVOS */
4/***********************************************************************************/
5/* This file is part of MeteoIO.
6 MeteoIO is free software: you can redistribute it and/or modify
7 it under the terms of the GNU Lesser General Public License as published by
8 the Free Software Foundation, either version 3 of the License, or
9 (at your option) any later version.
10
11 MeteoIO is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU Lesser General Public License for more details.
15
16 You should have received a copy of the GNU Lesser General Public License
17 along with MeteoIO. If not, see <http://www.gnu.org/licenses/>.
18*/
19#ifndef LIBACDD_H
20#define LIBACDD_H
21
22#include <meteoio/IOUtils.h>
23#include <meteoio/Config.h>
26
27#include <string>
28#include <vector>
29
30namespace mio {
139class ACDD {
140 public:
142 struct ACDD_ATTR; //forward declaration
143 struct VARS_ATTR; //forward declaration
144 typedef struct ACDD_ATTR acdd_attrs;
145 typedef struct VARS_ATTR vars_attr;
146
151 ACDD(const bool& set_enable);
152
153 //defining some iterators so the callers can loop over all available attributes
154 using const_iterator = std::map<std::string, acdd_attrs>::const_iterator;
155 const_iterator cbegin() const noexcept { return attributes.cbegin(); }
156 const_iterator cend() const noexcept { return attributes.cend(); }
157
163 void setEnabled(const bool& i_enable);
164
165 void setUserConfig(const mio::Config& cfg, const std::string& section, const bool& allow_multi_line=true);
166
167 void addAttribute(const std::string& att_name, const std::string& att_value, const Mode& mode=MERGE);
168 void addAttribute(const std::string& att_name, const double& att_value, const Mode& mode=MERGE);
169
174 void deleteAttribute(const std::string& att_name) {attributes.erase( att_name );}
175
180 bool isEnabled() const {return enabled;}
181
182 std::string getAttribute(std::string &att_name) const;
183
184 void setGeometry(const mio::Grid2DObject& grid, const bool& isLatLon);
185 void setGeometry(const std::vector< std::vector<mio::MeteoData> >& vecMeteo, const bool& isLatLon);
186 void setGeometry(const mio::Coords& location, const bool& isLatLon);
187 void setGeometry(const std::set< mio::Coords >& vecLocation, const bool& isLatLon);
188
194 void setStationIDs(const std::vector< std::vector<mio::MeteoData> >& vecMeteo);
195
202 void setStationID(const std::string& statID);
203
209 void setSingleFileOutput();
210
211 void setTimeCoverage(const std::vector< std::vector<mio::MeteoData> >& vecMeteo);
212 void setTimeCoverage(const std::vector<mio::MeteoData>& vecMeteo);
213 void setTimeCoverage(const std::vector<std::string>& vec_timestamp, const double& TZ);
214
215 //support for JSON metadata
222 void setEnableJson(const bool& i_enable);
223 bool enableJson() const {return enable_json;}
224 void writeJson(const std::string& data_filename) const;
225
226 void addDimension( const std::string& var_name, const std::string& var_long_name, const size_t& length);
227 void addVariable( const std::string& var_name, const std::string& var_long_name, const std::string& var_units);
228
229 std::string toString() const;
230
231 private:
232 static std::map<std::string, acdd_attrs> initAttributes();
233 static std::set< std::pair< std::string, std::set<std::string> > > initLinks();
234 static size_t countCommas(const std::string& str);
235 static std::string getFromCfgOrEnv(const mio::Config& cfg, const std::string& cfg_key, const std::string& section, const std::map<std::string, std::string>& env_values);
236 std::map<std::string, std::string> readEnvFallbacks(const mio::Config& cfg, const std::string& section) const;
237 static std::string normalizeID(const std::string& id);
238 void removeRelationshipsTo(const std::string& targetID);
239 void checkLinkedAttributes();
240
241 static bool isWigosID(const std::string& str);
242 static constexpr size_t max_siblings = 20;
243 std::map<std::string, acdd_attrs> attributes; //all the ACDD attributes with their properties
244 std::map<std::string, acdd_attrs> station_baseline;
245 std::set< std::pair< std::string, std::set<std::string> > > linked_attributes; //attribute names that are linked together, ie must have the same number of sub-elements (comma delimited)
246 std::vector< std::string > vecIDs;
247 std::set< vars_attr > dimensions, variables;
248 std::string packageID;
249 bool enabled; //helper boolean for callers to know if this object should be used or not
250 bool enable_json; //helper boolean for callers to trigger the writing of json metadata files together with the data file
251};
252
253struct ACDD::VARS_ATTR { //TODO at some point, this should be stored in MeteoData as timeseries metadata
254 VARS_ATTR(const std::string& i_name, const std::string& i_standard_name, const std::string& i_units) : name(i_name), standard_name(i_standard_name), units(i_units), length(IOUtils::npos) {}
255 VARS_ATTR(const std::string& i_name, const std::string& i_standard_name, const size_t& i_length) : name(i_name), standard_name(i_standard_name), units(), length(i_length) {}
256
257 //"units" is ignored here, since with the same name and standard_name, they would have the same units
258 bool operator<(const ACDD::VARS_ATTR& other) const {
259 return (name < other.name) ||
260 (name == other.name && standard_name < other.standard_name) ||
261 (name == other.name && standard_name == other.standard_name && length < other.length);
262 }
263
264 std::string name, standard_name, units;
265 size_t length;
266};
267
268
278 ACDD_ATTR() : name(), value(), cfg_key(), default_value(), Default(true) {}
279
280 ACDD_ATTR(const std::string& i_name, const std::string& i_cfg_key, const std::string& i_default_value="") : name(i_name), value(), cfg_key(i_cfg_key), default_value(i_default_value), Default(i_name.empty()) {}
281
282 ACDD_ATTR(const std::string& i_name, const std::string& i_value, const std::string& i_cfg_key, const std::string& i_default_value) : name(i_name), value(i_value), cfg_key(i_cfg_key), default_value(i_default_value), Default(false) {}
283
284 std::string getValue() const {return value;}
285 std::string getName() const {return name;}
286 std::string getCfgKey() const {return cfg_key;}
287 void setUserConfig(const mio::Config& cfg, const std::string& section, const bool& allow_multi_line, const std::map<std::string, std::string>& env_values);
288 void setValue(const std::string& i_value, const Mode& mode=MERGE);
289 bool isDefault() const {return Default;}
290
291private:
292 static void readFromFile(std::string& value, const mio::Config& cfg, const std::string& cfg_key, const std::string& section, const bool& allow_multi_line, const std::map<std::string, std::string>& env_values);
293
294 std::string name, value, cfg_key, default_value;
295 bool Default;
296};
297
298} //namespace
299#endif
This class contains and handles NetCDF Attribute Conventions Dataset Discovery attributes (see ACDD).
Definition libacdd.h:139
void setStationIDs(const std::vector< std::vector< mio::MeteoData > > &vecMeteo)
Provide the IDs of all the stations that will be written out as part of the current package.
Definition libacdd.cc:462
void deleteAttribute(const std::string &att_name)
Delete an attribute (this is required in some rare cases if an attribute is handled separately,...
Definition libacdd.h:174
void addDimension(const std::string &var_name, const std::string &var_long_name, const size_t &length)
Definition libacdd.cc:452
bool enableJson() const
Definition libacdd.h:223
void setUserConfig(const mio::Config &cfg, const std::string &section, const bool &allow_multi_line=true)
Read all config keys from the selected section and apply some special processing for some keys.
Definition libacdd.cc:357
void setEnableJson(const bool &i_enable)
Should a json file containing the metadata be written alongside the data file?
Definition libacdd.cc:442
std::string toString() const
Definition libacdd.cc:607
void setStationID(const std::string &statID)
Set the station that is currently being written out, so the station dependent attributes can be gener...
Definition libacdd.cc:474
void setSingleFileOutput()
Declare that all stations are written out into a single file, so the station dependent attributes can...
Definition libacdd.cc:494
void setTimeCoverage(const std::vector< std::vector< mio::MeteoData > > &vecMeteo)
Definition libacdd.cc:874
void addVariable(const std::string &var_name, const std::string &var_long_name, const std::string &var_units)
Definition libacdd.cc:457
std::map< std::string, acdd_attrs >::const_iterator const_iterator
Definition libacdd.h:154
void setEnabled(const bool &i_enable)
Set an internal boolean as a helper for the caller to know if ACDD support should be enabled or not....
Definition libacdd.cc:390
Mode
Definition libacdd.h:141
@ APPEND
Definition libacdd.h:141
@ REPLACE
Definition libacdd.h:141
@ MERGE
Definition libacdd.h:141
const_iterator cend() const noexcept
Definition libacdd.h:156
void writeJson(const std::string &data_filename) const
Definition libacdd.cc:544
void addAttribute(const std::string &att_name, const std::string &att_value, const Mode &mode=MERGE)
Add an attribute and its content to the internal list.
Definition libacdd.cc:628
std::string getAttribute(std::string &att_name) const
Given an attribute name, return its associated value (or an empty string if it does not exists)
Definition libacdd.cc:656
const_iterator cbegin() const noexcept
Definition libacdd.h:155
bool isEnabled() const
Get an internal boolean as a helper for the caller to know if ACDD support should be enabled or not.
Definition libacdd.h:180
void setGeometry(const mio::Grid2DObject &grid, const bool &isLatLon)
Definition libacdd.cc:666
A class that reads a key/value file. These files (typically named *.ini) follow the INI file format s...
Definition Config.h:86
A class to handle geographic coordinate systems. This class offers an easy way to transparently conve...
Definition Coords.h:83
A class to represent 2D Grids. Typical application as DEM or Landuse Model.
Definition Grid2DObject.h:42
Definition Config.cc:34
This structure provides low level functions to handle and store individual ACDD fields.
Definition libacdd.h:277
bool isDefault() const
Definition libacdd.h:289
void setUserConfig(const mio::Config &cfg, const std::string &section, const bool &allow_multi_line, const std::map< std::string, std::string > &env_values)
Set the value of the attribute, either from a config file key, or from an environment variable of the...
Definition libacdd.cc:311
std::string getCfgKey() const
Definition libacdd.h:286
ACDD_ATTR(const std::string &i_name, const std::string &i_cfg_key, const std::string &i_default_value="")
Definition libacdd.h:280
void setValue(const std::string &i_value, const Mode &mode=MERGE)
Set an ACDD value.
Definition libacdd.cc:336
ACDD_ATTR(const std::string &i_name, const std::string &i_value, const std::string &i_cfg_key, const std::string &i_default_value)
Definition libacdd.h:282
std::string getName() const
Definition libacdd.h:285
std::string getValue() const
Definition libacdd.h:284
ACDD_ATTR()
Definition libacdd.h:278
Definition libacdd.h:253
std::string name
Definition libacdd.h:264
VARS_ATTR(const std::string &i_name, const std::string &i_standard_name, const std::string &i_units)
Definition libacdd.h:254
size_t length
Definition libacdd.h:265
std::string units
Definition libacdd.h:264
bool operator<(const ACDD::VARS_ATTR &other) const
Definition libacdd.h:258
VARS_ATTR(const std::string &i_name, const std::string &i_standard_name, const size_t &i_length)
Definition libacdd.h:255
std::string standard_name
Definition libacdd.h:264