MeteoIODoc 20240528.4cbdb3e5
mio::ACDD Class Reference

Detailed Description

This class contains and handles NetCDF Attribute Conventions Dataset Discovery attributes (see ACDD).

The final value of any acdd field is provided by three sources, any attempts stops as soon as some value has been found: 1. the INI configuration key; 2. reading the matching environment variable; 3. some hard-coded defaults (whenever it makes sense and is possible). It is therefore possible to define relevant default values system-wide by setting an environment variable of the same name as the INI configuration key and individual configuration files might still overwrite this default by explicitely setting the configuration key.

The following keys are supported to define ACDD attribues (all in the [Output] section):

  • Overview of the dataset
    • ACDD_TITLE: a short title for the data set;
    • ACDD_SUMMARY: a paragraph describing the dataset;
    • ACDD_SUMMARY_FILE: a file containing a description of the dataset, it overwrites the value of ACDD_SUMMARY if present;
    • ACDD_COMMENT: miscellaneous informartion about the dataset;
    • ACDD_ACKNOWLEDGEMENT: acknowledgement for the various types of support for the project that produced this data;
    • ACDD_KEYWORDS: a list of AGU Index Terms (default: hard-coded list);
    • ACDD_KEYWORDS_VOCABULARY: the unique name or identifier of the vocabulary from which keywords are taken (default: AGU);
  • Linking the dataset to other resources and metadata
    • ACDD_ID: an identifier for the data set, provided by and unique within its naming authority. Example: DOI, URL, text string, but without white spaces
    • ACDD_NAMING_AUTHORITY: The organization that provides the initial id (see above) for the dataset
    • ACDD_METADATA_LINK: A URL/DOI that gives more complete metadata;
    • ACDD_REFERENCES: Published or web-based references that describe the data or methods used to produce it;
    • WIGOS_ID: although this is not an ACDD key, it can be very useful in linking datasets together through their WIGOS ID.
  • Origin of the data
    • ACDD_PROJECT: the scientific project that created the data;
    • ACDD_PROGRAM: The overarching program(s) of which the dataset is a part;
    • ACDD_SOURCE: The method of production of the original data;
    • ACDD_ACTIVITY_TYPE: Activity types are used to identify the origin of the dataset. Pick one from this controlled vocabulary;
  • Contact information regarding the data set
    • ACDD_INSTITUTION: the institution providing the data set (default: domain name);
    • The following can be a list of comma-delimited values but must be kept in-sync (ie if providing two creators, then two emails must also be provided, etc):
      • ACDD_CREATOR: the name of the creator of the data set (default: login name);
      • ACDD_CREATOR_EMAIL: the email of the creator;
      • ACDD_CREATOR_INSTITUTION: the institution of the creator; should uniquely identify the creator's institution;
      • ACDD_CREATOR_URL: the URL of the creator principally responsible for creating this data;
      • ACDD_CREATOR_TYPE: either person, group, institution, or position (default: person);
    • The following can be a list of comma-delimited values but must be kept in-sync (ie if providing two publishers, then two emails must also be provided, etc):
      • ACDD_PUBLISHER: the name of the person / entity responsible for publishing the data file or product to users, with its current metadata and format;
      • ACDD_PUBLISHER_EMAIL: the email of the person / entity responsible for publishing the data file or product to users;
      • ACDD_PUBLISHER_URL: the url of the person / entity responsible for publishing the data file or product to users;
      • ACDD_PUBLISHER_TYPE: either person, group, institution, or position (default: person);
    • The following can be a list of comma-delimited values but must be kept in-sync (ie if providing two contributors, then two roles must also be provided, etc):
      • ACDD_CONTRIBUTOR: the name of the individuals, instutitions or projects that have contributed to the data set (default: login name);
      • ACDD_CONTRIBUTOR_ROLE: the role of the contributor;
  • Miscellaneous
    • ACDD_PROCESSING_LEVEL: a textual description of the processing level
    • ACDD_LICENSE: describes the license applicable to the dataset;
    • ACDD_PRODUCT_VERSION: Version identifier of the data file or product as assigned by the data creator (default: 1.0);
    • ACDD_OPERATIONAL_STATUS: The current operational status of the product. Choose from the controlled vocabulary;

This list contains all mandatory ACDD fields as listed at the Arctic Data Centre as well as most of the optional fields (please note that the geospatial and time coverage are automatically generated based on the data itself and the history is also automatically handled).

Example of ACDD configuration for a NetCDF file generated for the WMO's Global Cryosphere Watch (GCW) data portal:

[Output]
ACDD_WRITE = TRUE
ACDD_CREATOR = Mathias Bavay
ACDD_CREATOR_EMAIL = bavay@slf.ch
ACDD_CREATOR_INSTITUTION = SLF
ACDD_CREATOR_URL = https://slf.ch
ACDD_CREATOR_TYPE = person
ACDD_PUBLISHER = Mathias Bavay
ACDD_PUBLISHER_EMAIL = bavay@slf.ch
ACDD_PUBLISHER_URL = https://slf.ch
ACDD_PUBLISHER_TYPE = person
ACDD_INSTITUTION = SLF
ACDD_ID = 5LAR1_MeteoBase
ACDD_NAMING_AUTHORITY = SLF
ACDD_TITLE = Meteo station at Laret val/cal site
ACDD_SUMMARY = Meteo station at Laret val/cal site
ACDD_LICENSE = CC-BY-NC
ACDD_PROCESSING_LEVEL = raw
ACDD_ACTIVITY_TYPE = in situ land-based station
ACDD_OPERATIONAL_STATUS = scientific
@ raw
Definition: IOUtils.h:55

#include <libacdd.h>

Public Types

enum  Mode { MERGE , REPLACE , APPEND }
 
using const_iterator = std::map< std::string, acdd_attrs >::const_iterator
 

Public Member Functions

 ACDD (const bool &set_enable)
 Constructor, the argument allows the object to know if the acdd metadata should be written out or not. More...
 
const_iterator cbegin () const noexcept
 
const_iterator cend () const noexcept
 
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. Moreover, it initializes the attributes map if not already done. More...
 
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. More...
 
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. More...
 
void addAttribute (const std::string &att_name, const double &att_value, const Mode &mode=MERGE)
 
bool isEnabled () const
 Get an internal boolean as a helper for the caller to know if ACDD support should be enabled or not. More...
 
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) More...
 
void setGeometry (const mio::Grid2DObject &grid, const bool &isLatLon)
 
void setGeometry (const std::vector< std::vector< mio::MeteoData > > &vecMeteo, const bool &isLatLon)
 
void setGeometry (const mio::Coords &location, const bool &isLatLon)
 
void setGeometry (const std::vector< mio::Coords > &vecLocation, const bool &isLatLon)
 
void setTimeCoverage (const std::vector< std::vector< mio::MeteoData > > &vecMeteo)
 
void setTimeCoverage (const std::vector< mio::MeteoData > &vecMeteo)
 
void setTimeCoverage (const std::vector< std::string > &vec_timestamp, const double &TZ)
 
std::string toString () const
 

Member Typedef Documentation

◆ const_iterator

using mio::ACDD::const_iterator = std::map<std::string, acdd_attrs>::const_iterator

Member Enumeration Documentation

◆ Mode

Enumerator
MERGE 
REPLACE 
APPEND 

Constructor & Destructor Documentation

◆ ACDD()

mio::ACDD::ACDD ( const bool &  set_enable)
inline

Constructor, the argument allows the object to know if the acdd metadata should be written out or not.

Parameters
[in]set_enableenable ACDD support?

Member Function Documentation

◆ addAttribute() [1/2]

void mio::ACDD::addAttribute ( const std::string &  att_name,
const double &  att_value,
const Mode mode = MERGE 
)

◆ addAttribute() [2/2]

void mio::ACDD::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.

This allows to create or edit attributes. For the MERGE or APPEND modes, if the attribute name is not found, it will be created.

Parameters
[in]att_nameattribute name
[in]att_valueattribute value
[in]modewrite mode: MERGE (currently empty values will be replaced by the given arguments), APPEND (the value content will be expanded by what is provided in att_value, separated by ", ", REPLACE (the current attribute will be fully replaced by the provided arguments)

◆ cbegin()

const_iterator mio::ACDD::cbegin ( ) const
inlinenoexcept

◆ cend()

const_iterator mio::ACDD::cend ( ) const
inlinenoexcept

◆ getAttribute()

std::string mio::ACDD::getAttribute ( std::string &  att_name) const

Given an attribute name, return its associated value (or an empty string if it does not exists)

Parameters
[in]att_nameattribute name to get the value for
Returns
attribute value or empty string

◆ isEnabled()

bool mio::ACDD::isEnabled ( ) const
inline

Get an internal boolean as a helper for the caller to know if ACDD support should be enabled or not.

Returns
enable ACDD support from the caller side?

◆ setEnabled()

void mio::ACDD::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. Moreover, it initializes the attributes map if not already done.

Parameters
[in]i_enableenable ACDD support?

◆ setGeometry() [1/4]

void mio::ACDD::setGeometry ( const mio::Coords location,
const bool &  isLatLon 
)

◆ setGeometry() [2/4]

void mio::ACDD::setGeometry ( const mio::Grid2DObject grid,
const bool &  isLatLon 
)

◆ setGeometry() [3/4]

void mio::ACDD::setGeometry ( const std::vector< mio::Coords > &  vecLocation,
const bool &  isLatLon 
)

◆ setGeometry() [4/4]

void mio::ACDD::setGeometry ( const std::vector< std::vector< mio::MeteoData > > &  vecMeteo,
const bool &  isLatLon 
)

◆ setTimeCoverage() [1/3]

void mio::ACDD::setTimeCoverage ( const std::vector< mio::MeteoData > &  vecMeteo)

◆ setTimeCoverage() [2/3]

void mio::ACDD::setTimeCoverage ( const std::vector< std::string > &  vec_timestamp,
const double &  TZ 
)

◆ setTimeCoverage() [3/3]

void mio::ACDD::setTimeCoverage ( const std::vector< std::vector< mio::MeteoData > > &  vecMeteo)

◆ setUserConfig()

void mio::ACDD::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.

This is used as some sort of caching, only keeping the section of interest.

Parameters
[in]cfgConfig object to read the configuration keys from
[in]sectionsection to read the keys from (all keys from the section will be read at this point)
[in]allow_multi_lineshould multi-line content be supported?

◆ toString()

std::string mio::ACDD::toString ( ) const

The documentation for this class was generated from the following files: