Naming Convention

Background

The following naming guidelines have been developed to harmonize the data collection, data storage at the different ecosystem monitoring sites run by the GL Group as well as to simplify further post-processing and sharing of datasets in the future. The primary site where this should be implemented first is CH-DAV – ICOS Class 1 Site and at the other GL EC Sites.

Developed by

• Thomas Baur
• Lukas Hörtnagl
• Philip Meier
• Lutz Merbold

With Contributions From:

• Nina Buchmann
• Werner Eugster
• Carmen Emmel
• Kathrin Fuchs
• Patrick Koller
• Florian Käslin

Based on

The original approach was to use the GHG-Europe Standard using a 3-figure code, which identifies univocally the location within the site. According to this standard, the name of the variable is indicated as

VAR_x1_x2_x3

whereby:
x1…position of the sensor on a 2D space
x2…approx. vertical height above the ground / depth of soil (e.g. 80 cm would be written as 1 m)
x3…replicated measurements in the same location

e.g. Ta_1_1_1 is air temperature (Ta) at location 1 (x1) at a height of 1 m (x2). Because it is the only sensor at this location and at this height, the last number x3 is also 1. A second Ta sensor at the same height would be named Ta_1_1_2. However, this convention would make the use of a complementary list explaining all variable positions mandatory at all times.

We stick to the general format, with the exception that we allow letters for x1 and x3 and that our height gives the exact height (e.g. x2: 80 cm would be 0.8).

Quick Examples

General Format

Variables

This naming convention makes it possible to clearly identify sites, variables, objects, programs, scripts and configuration files. Whenever changes are implemented at a field site or when describing a specific entity, the respective naming must be given in the grassland group Fieldbook. In all cases national characters (e.g. umlauts ä, ö, ü, Ä, Ö, Ü), Chinese characters, invalid characters etc. must not be used in variable names, site names, file names, and directory names.

VAR_H_V_R

whereby

VAR … shortcode for the measured variable
H … horizontal position index: location of the sensor on a 2D space
V … vertical position index: vertical height above the ground or depth of soil in meters
R … replicate index: replicated measurement in the same location

_H_V_R is the location suffix comprised of the three position indices. More information about the location index can be found here.

Details for each naming part are given in separate subpages. For more information please refer to the respective section.

Also keep in mind that the location is exactly defined by the last three identifiers in the respective variable name, meaning the location can exactly be defined when reading the variable from the end to the front. This is particularly important since variable labels can be extended by a prefix, suffix or identifier and this may lead to confusion – see also the examples section.

Location

The location of items (variables, objects, systems …) are identified by a three-part suffix that is added to the item ID. The suffix comprises three indices that give information about the horizontal and vertical location of an item, and about replicates at the same location.

anyItemID_H_V_R

whereby

anyItemID … any item ID that needs to be located
H … horizontal position index: location of the sensor on a 2D space
V … vertical position index: vertical height above the ground or depth of soil in meters
R … replicate index: replicated measurement in the same location

The location suffix _H_V_R refers to the sampling point of a parameter or the location of an instrument.

The location is exactly defined by the last three identifiers in the respective item name, meaning the item can be located when reading the variable from the end to the front. This is particularly important since variable labels can be extended by a prefix, suffix or identifier and this may lead to confusion.

H: Horizontal position index

Type: letters & numbers

 The horizontal position index consists of a label followed by a number and describes the sampling point of a parameter or the location of an instrument.

Important: if eddy covariance equipment is installed on a structure, we refer to it as tower, never as a mast. A mast can be installed in close proximity of the tower and normally carries additional instrumentation (e.g. phenocam or similar) that did not fit on the main tower.

If we want to describe masts and booms that are mounted on the main tower, it is necessary to combine different labels and numbers. Please see below for examples. Naming is done clockwise, starting from North. As for the work in reality, adjusted naming as in case of two rain gauges next to a tower on separate small masts is possible: e.g. instead of  PREC_RAIN_M1_1_1 and PREC_RAIN_M2_1_1 one could also name these PREC_RAIN_GF1_1_1 and PREC_RAIN_GF1_1_2. In all cases the detailed site overview in form of a scheme has to be provided.

V: Vertical position index

Type:   integer or float (0-9999)
Unit:    m

The vertical position index described the vertical position of an instrument in meters. The number describes height for sensors that are installed aboveground, and depth of soil for sensors that are installed belowground.

Height and depth are given in mDistances smaller/larger than 1m or different from absolute values should be separated with . with as many decimal places as necessary, e.g. soil temperature measured at 2cm depth is given as 0.02, air temperature measured at 150cm height is given as 1.5, air temperature at 35m height is given as 35. If a number describes height or depth can be seen from the variable name, e.g. for soil temperature V describes the depth, for air temperature the height.

Exception for Campbell Scientific Dataloggers: The programming languages for Campbell Scientific Dataloggers CRBasic and Edlog (deprecated) do not allow . in variable names. Thus, as an exception, the . is replaced by x for Campbell Dataloggers, e.g. a depth of 2cm is given as 0x02 instead of 0.02.

R: Replicate Index

Type:   number (1-9999)
Unit:    #

The replicate index is used to distinguish between instruments that measure the same quantity at the same horizontal and vertical position, i.e. H and V are the same.

Numbering starts in the North direction and goes clockwise in extending circles during a first setup/re-setup. New and additional sensors may mix this up, layered maps are therefore mandatory at all sites.

Sometimes the geographic orientation of an instrument is needed, e.g. on a single tree not only the location but also the specific orientation of a dendrometer must be clear. The orientation of the instrument is visible from the assigned number in combination with the area map.

Systems

In the context of programs and scripts, a system is an abstract term mainly referring to the instrumentation for which the program was intended. This is not meant to be the computer where it runs. But in some cases, as for example a datalogger program, the former and the latter definition overlap. In this case, the system would be the datalogger itself, say DL (data logger). Since the system is in no measurement variable, a small “i” must be added as a prefix.

SiteIdentifier_SystemID_H_V_R

The systemname should be used for e.g. Campbell logger station name, computer name …

When using the Systemname as computer name there are some restrictionsdepending of the OS. With a Linux system (and almost all others) it is not possible to use _ (underline) character in the name. Therefore use dash (-) instead.

Sites

The naming of sites follows the general structure:

Country-Site

Country is a 2-digit country code, e.g. CH for Switzerland.

Site is the 3-digit site identifier, e.g. DAV for Davos.

Scripts & Programs

Software organization using Gitlab and GIN

Self-written software for data acquisition must be stored, maintained and versioned properly. In the grassland group, we use two tools to accomplish this:

• Gitlab (storage, versioning)
• GIN (deployment documentation)

All self-written script or programs (subsequently referred to as programs only) have to be stored in a gitlab repository (gitlab how-to, internal only on glpedia). When you deploy a program on a data acquisition system (computer, datalogger, arduino, etc.), you have to create a fieldbook entry in GIN with the SW_MOD event-tag (see gin tutorial on glpedia, internal only) and an URL link pointing to the exact commit of the program repository. Similarly, if you update a configuration-file for a program, you have to create a fieldbook entry in GIN with the CONFIG event-tag and the config-file attached.

As such it is clearly documented when which version of which program was installed on which data acquisition system

To simplify this organisation, some standards have to be met, which are described in the following sections.

Naming of programs and configurations

Programs used on multiple sites

Programs that are (potentially) used on multiple sites must have a site-unspecific name, i.e. the site-name or project-name should not be present. Due to the versioning in git repositories, also version numbers in the file name are obsolete.

ProgramName.file extension

whereby

ProgramName … due to the variety of possible programs, the naming is not strictly regulated. Nevertheless, the program name must clarify what the program is doing (e.g. read, write, control, etc.) and for which instrument or system (as described in Section 2.4.1, e.g. sonic, TrHW, etc.) it was designed for. The ProgramName shall not contain information about SITE or VERSION.
file extension … if necessary

Site-specific programs

SiteID_ProgramName_Location.file extension

whereby

SiteID … as given here
ProgramName … due to the variety of possible programs, the naming is not strictly regulated. Nevertheless, the program name must clarify what the program is doing (e.g. read, write, control, check etc.) and for which instrument or system (as described here, e.g. sonic, TRHW, etc.) it was designed for.
Location … as given here
file extension … if necessary

Scripts and programs  which are specific for a special site and device and or data acquisition e.g. a logger program of a CR1000 logger that includes the (mostly) unique sensor configuration of a site and system.

Configuration files

Some programs use configuration files, mainly for these reasons:

• large number of settings that cannot be passed by command line arguments
• generalization of the program to multiple sites, where only the configuration is site-specific

SiteID_ProgramName.file extension

whereby

SiteID … as given here
ProgramName … must be the ProgramName of the program reading from it
file extension … must be .rc or .config (where possible)

Objects

Objects are named following a similar approach and can help to identify a location of technical parts, e.g. the position of tower boxes, flow modules etc.. However, since objects are clearly different from a measured variable, each object name starts with the letter i for “instrument” (see examples here).

Lists

List of variables

List of systems

List of sites

List of objects

List of location indices

Horizontal position index

The horizontal position index describes the horizontal location of items. For more information see here.

Examples

Examples: Variables

Some examples for full variable names, including the variable abbreviation follwed by the location suffix.

Examples: Objects

Examples: Location

Examples: Horizontal Position Index

Last Updated on 14 Feb 2024 12:12