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

wdt_ID Operation Tag Description Category
1 sonicreadHS program which reads serial data from a 3D sonic and concentration data from message queues Scripts & Programs (unspecific)
4 CH-DAV_readDL_FF1_0_1_20150312 version from march the 12th 2015 of the logger program that collects soil data at a forest floor plot in Davos Scripts & Programs (site-specific)
5 iFLOWMODULE_T1_35_1 FlowModule LI-7200 on Tower 1 at a height of 35 m, replicate 1 Objects
6 iBOX_PRF_H2_0_2 one of two boxes which provide instrumentation for the profile in a second hut at the site, height is not needed and set to zero, there is another similar box in the same hut Objects
21 TA_T1_35_1 air temperature measured on the main tower at 35m height Variables
9 CH-CHA Chamau Sites
10 CH-DAV Davos Sites
22 TA_T1_35_2 air temperature measured by a second sensor on the main tower at 35m height Variables
23 TA_T1_35_3 air temperature measured by a third sensor on the main tower at 35m height Variables
24 SWC_FF1_0.10_1 soil water content measured in forest floor 1 in 10cm depth Variables
25 SWC_FF1_0x10_1 soil water content measured in forest floor 1 in 10cm depth (alternative name in case dot . cannot be used in variable name) Variables
26 TS_GF2_0.50_1 soil temperature measured in grassland floor 2 in 50cm depth Variables
27 TS_FF1_0x80_1 soil temperature measured in forest floor 1 in 80cm depth (xis used instead of . because of logger specifications) Variables
28 iDL_H1_0_1 datalogger installed in a hut at the measurement site, at ground level Systems
29 iDL_T1_35_1 datalogger installed on the main tower at 35m height Systems
30 WS_PRF_T1_1_1 wind speed measured on the main tower at 1m height (wind profile) Variables
32 WS_PRF_T1_5_1 wind speed measured on the main tower at 5m height (wind profile) Variables
33 WS_PRF_T1_10_1 wind speed measured on the main tower at 10m height (wind profile) Variables
34 WS_PRF_T1_20_1 wind speed measured on the main tower at 20m height (wind profile) Variables

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

VARshortcode for the measured variable
Hhorizontal position index: location of the sensor on a 2D space
Vvertical position index: vertical height above the ground or depth of soil in meters
Rreplicate 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
Vvertical position index: vertical height above the ground or depth of soil in meters
Rreplicate 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

wdt_ID System ID System Name
1 iArduChamber Arduino controlling the chamber system
14 iChamber Automated chamber system as a whole
15 iDL Data logger (CR10X, CR1000..)
16 iDAQ Data acquisition (eg. embedded)
17 iIOCTRL Digital Input/Output Controller (e.g. Moxa ioLogik)
18 iNETDEV Network devices (e.g. switch, router, wlan acces point..)
19 iRSDEV Serial devices (e.g. RS converter, NPort, Serial to USB…)
System ID System Name

List of sites

wdt_ID Site ID Site Name
1 CH-AWS Alp Weissenstein
2 CH-CHA Chamau
3 CH-DAV Davos
4 CH-DSC Dischma
5 CH-FRU Fruebuel
6 CH-LAE Laegeren
7 CH-LAS Laegeren subcanopy
8 CH-OE2 Oensingen
9 CH-RUE Ruemlang
10 US-TOL Toolik lake
11 US-TWL Toolik wetland
12 CH-INO InnoFarm Project (multiple sites)
13 CH-PAY Payerne
14 CH-AES Aeschi
15 CH-ZRH Zurich Airport
16 CH-ROS Rotsee
17 CH-KLS Kloentalersee
18 CH-LFW ETH Dach, Gebäude LFW
19 CH-LLS Lindestock
20 CH-SEE Seebodenalp
21 CH-SOP Soppensee
22 CH-WOL Wohlensee
23 CH-ZOM Zurich Zoo, Masoala building
24 PA-ARB Panamaarbol
25 PA-VAC Panamvaca
26 PR-PDE Puerto Rico
27 CH-RUE Ruemlang
28 CH-DAE Däniken
29 CH-HON Hönggerberg
30 CH-FOR Forel
31 CH-TAN Taenikon
Site ID Site Name

List of objects

wdt_ID Object ID Object Name
1 iFLOWMODULE Flow Module
14 iBOX_PRF Profile Box
Object ID Object Name

List of location indices

Horizontal position index

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

wdt_ID H Index Horizontal Position
1 T Tower (EC system is mounted here)
2 M mast
3 TR tree
4 FF forest floor plot
5 GF grassland floor
6 WF wetland floor
7 CF cropland floor
8 H Hut
9 B boom
10 BOX box with mounted instrumentation (only if necessary, might be misleading according to Techs)

Examples

Examples: Variables

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

Item IDItem Name
TA_T1_35_1air temperature measured on the main tower at 35m height
TA_T1_35_2air temperature measured by a second sensor on the main tower at 35m height
TA_T1_35_3air temperature measured by a third sensor on the main tower at 35m height
SWC_FF1_0.10_1soil water content measured in forest floor 1 in 10cm depth
SWC_FF1_0x10_1soil water content measured in forest floor 1 in 10cm depth (alternative name in case dot . cannot be used in variable name)
TS_GF2_0.50_1soil temperature measured in grassland floor 2 in 50cm depth
TS_FF1_0x80_1soil temperature measured in forest floor 1 in 80cm depth (xis used instead of . because of logger specifications)

Examples: Objects

Object ID
Description
iFLOWMODULE_T1_35_1FlowModule LI-7200 on Tower 1 at a height of 35 m, replicate 1
iBOX_PRF_H2_0_2one of two boxes which provide instrumentation for the profile in a second hut at the site, height is not needed and set to zero, there is another similar box in the same hut

Examples: Location

Item IDItem Name
TA_T1_35_1air temperature measured on the main tower at 35m height
TA_T1_35_2air temperature measured by a second sensor on the main tower at 35m height
TA_T1_35_3air temperature measured by a third sensor on the main tower at 35m height
SWC_FF1_0.10_1soil water content measured in forest floor 1 in 10cm depth
SWC_FF1_0x10_1soil water content measured in forest floor 1 in 10cm depth (alternative name in case dot . cannot be used in variable name)
TS_GF2_0.50_1soil temperature measured in grassland floor 2 in 50cm depth
iDL_H1_0_1datalogger installed in a hut at the measurement site, at ground level
iDL_T1_35_1datalogger installed on the main tower at 35m height
WS_T1_1_1wind speed measured on the main tower at 1m height (wind profile)
WS_T1_2_1wind speed measured on the main tower at 2m height (wind profile)
WS_T1_5_1wind speed measured on the main tower at 5m height (wind profile)
WS_T1_10_1wind speed measured on the main tower at 10m height (wind profile)
WS_T1_20_1wind speed measured on the main tower at 20m height (wind profile)

Examples: Horizontal Position Index

H IndexExample
T1main tower with installed eddy covariance equipment
T1B1boom on main tower
T1B22nd boom on main tower
M1mast where radiation sensors are installed in the field
M22nd mast with e.g. precipitation bucket
M2B1boom on 2nd mast
H1hut at measurement site
BOX1Box with devices,  power supplies, etc
TREE5fifth tree with instrumentation
FF3forest floor plot 3
GF5grassland floor plot 5
WF2wetland floor plot 2
CF0cropland floor that represents the overall ecosystem area (not assigned to a specific plot)
T22nd tower with eddy equipment

Last Updated on 14 Feb 2024 12:12