Variable names and attributes

Variable names and attributes

Introduction

Everyone who runs a flux tower has their favourite, usually unique, home-made convention when it comes to naming variables and the syntax used for units. Sometimes, they'll even invent a different convention for each tower in a network. Sometimes, they'll get so carried away with their creativity that they'll use completely different ways of writing the same unit within the same data logger program!.

Sadly, such creativity has to be curtailed in the interests of simplicity and time saving. And such creativity has to firmly suppressed if we are to produce a homogeneous data set across multiple sites while meeting rigous convention standards such as Climate and Forecasting Metadata Conventions (CF).

To this end, PyFluxPro imposes rules on variable naming, ways of expressing units and requires some other variable attributes (e.g. long_name, standard_name and instrument) to be chosen from controlled vocabularies. This section describes these rules.

Variable naming: rules

The tables in this section give the variable name prefixes, units, long_name and standard_name attributes for variables used in PyFluxPro. PFP also reserves the use of 3 suffixes to indicate variables that are averages (_Av), standard deviations (_Sd) and variances (_Vr). The use of suffixes may be deprecated in the future now that the statistic_type variable attribute has been introduced.

Some rules:

1. Don't use a defined variable name prefix for a different quantity.
2. Don't add anything to a variable name after a reserved suffix (e.g. _Av, _Sd and _Vr).
3. Only use the defined units syntax. This syntax is UDUNITS and CF compliant.
4. Only use the defined long_name and standard_name values.

Not all quantities have defined standard names yet. Those that don't have been left empty in the table. Don't define your own! TERN will be submitting a list of proposed standard_names for these quantities to the CF Working Group.

Users must follow these rules or PyFluxPro simply will not run. This is required so that the files produced by PyFluxPro are CF compliant.

Variable attributes: units, long_name and standard_name

Table 1: Variable name prefix, units, long_name and standard_name attributes for common variables in PyFluxPro.

Name	Units	long_name	standard_name
AH	g/m^3	Absolute humidity	mass_concentration_of_water_vapor_in_air
CO2	umol/mol	CO2 concentration	mole_fraction_of_carbon_dioxide_in_air
	mg/m^3	CO2 concentration	mass_concentration_of_carbon_dioxide_in_air
EC	dS/m	Electrical conductivity (soil)
ER	umol/m^2/s	Ecosystem respiration
ET	mm	Evapotranspiration
Fa	W/m^2	Available energy
Fco2	umol/m^2/s	CO2 flux	surface_upward_mole_flux_of_carbon_dioxide
	mg/m^2/s	CO2 flux
Fe	W/m^2	Latent heat flux	surface_upward_latent_heat_flux
Fg	W/m^2	Ground heat flux	downward_heat_flux_at_ground_level_in_soil
Fh	W/m^2	Sensible heat flux	surface_upward_sensible_heat_flux
Fld	W/m^2	Down-welling longwave	surface_downwelling_longwave_flux_in_air
Flu	W/m^2	Up-welling longwave	surface_upwelling_longwave_flux_in_air
Fm	kg/m/s^2	Momentum flux	magnitude_of_surface_downward_stress
Fn	W/m^2	Net radiation	surface_net_downward_radiative_flux
Fsd	W/m^2	Down-welling shortwave	surface_downwelling_shortwave_flux_in_air
Fsu	W/m^2	Up-welling shortwave	surface_upwelling_shortwave_flux_in_air
GPP	umol/m^2/s	Gross primary productivity
H2O	mmol/mol	H2O concentration	mole_fraction_of_water_vapor_in_air
L	m	Monin-Obukhov length
NEE	umol/m^2/s	Net ecosystem exchange
NEP	umol/m^2/s	Net ecosystem productivity
PAR	umol/m^2/s	Photosynthetically active radiation	surface_downwelling_photosynthetic_photon_flux_in_air
Precip	mm	Rainfall	thickness_of_rainfall_amount
RH	percent	Relative humidity	relative_humidity
Sco2	umol/m^2/s	CO2 flux (storage)
SH	kg/kg	Specific humidity	specific_humidity
SHD	kg/kg	Specific humidity deficit
Sws	m^3/m^3	Soil water content	volume_fraction_of_condensed_water_in_soil
Ta	degC	Air temperature	air_temperature
Ts	degC	Soil temperature	soil_temperature
Tv	degC	Virtual temperature	virtual_temperature
U	m/s	Wind speed, east component	eastward_wind
V	m/s	Wind speed, north component	northward_wind
VP	kPa	Vapour pressure	water_vapor_partial_pressure_in_air
VPD	kPa	Vapour pressure deficit	water_vapor_saturation_deficit_in_air
W	m/s	Wind speed, vertical component
Wd	degrees	Wind direction	wind_from_direction
Ws	m/s	Wind speed	wind_speed
ps	kPa	Surface air pressure	surface_air_pressure
time	days since 1800-01-01 00:00:00.0	time	time
ustar	m/s	Friction velocity

The variable name, units and long_name for less common variables are given in Table 2 below.

Table 2: Variable name prefix, units, long_name and standard_name attributes for less common variables in PyFluxPro.

Name	Units	long_name
AGC_IRGA	1	IRGA automatic gain control value
Diag_IRGA	1	IRGA diagnostic value
Diag_SONIC	1	Sonic diagnostic value
Signal_CO2	1	CO2 signal strength
Signal_H2O	1	H2O signal strength
UxA	g/m^2/s	Covariance of Ux and H2O
UxC	mg/m^2/s	Covariance of Ux and CO2
UxT	m.degC/s	Covariance of Ux and T
UxUy	m^2/s^2	Covariance of Ux and Uy
UxUz	m^2/s^2	Covariance of Ux and Uz
Ux_SONIC_Av	m/s	Longitudinal wind velocity component, sonic coordinates
Ux_SONIC_Sd	m/s	Longitudinal wind velocity component, sonic coordinates, standard deviation
Ux_SONIC_Vr	m^2/s^2	Longitudinal wind velocity component, sonic coordinates, variance
UyA	g/m^2/s	Covariance of Uy and H2O
UyC	mg/m^2/s	Covariance of Uy and CO2
UyT	m.degC/s	Covariance of Uy and T
UyUz	m^2/s^2	Covariance of Uy and Uz
Uy_SONIC_Av	m/s	Lateral wind velocity component, sonic coordinates
Uy_SONIC_Sd	m/s	Lateral wind velocity component, sonic coordinates, standard deviation
Uy_SONIC_Vr	m^2/s^2	Lateral wind velocity component, sonic coordinates, variance
UzA	g/m^2/s	Covariance of Uz and H2O
UzC	mg/m^2/s	Covariance of Uz and CO2
UzT	m.degC/s	Covariance of Uz and T
Uz_SONIC_Av	m/s	Vertical wind velocity component, sonic coordinates
Uz_SONIC_Sd	m/s	Vertical wind velocity component, sonic coordinates, standard deviation
Uz_SONIC_Vr	m^2/s^2	Vertical wind velocity component, sonic coordinates, variance

Reserved suffixes are given in Table 3.

Table 3: Reserved variable name suffixes. Don't add anything to a variable name after these suffixes.

Suffix	Definition
_Av	Average
_Sd	Standard deviation
_Vr	Variance

More on the variable naming convention

The entry in the Name column of Table 1 can be the variable name or just the prefix of a variable name.

The variable naming convention used in PyFluxPro is based on the following:

1. The variable name prefix is determined by the quantity. For example, any air temperature quantity will begin with Ta, any relative humidity quantity will begin with RH, any soil moisture quantity will begin with Sws.
2. PyFluxPro will assume that the combination of variable name prefix and units e.g. Ta and degC will always indicate a sepcific quantity, in this case air temperature.
3. Quantities measured by different instruments at different locations are generally identified by appending the instrument type and the location to the variable name prefix. For example, air temperature measured by a Vaisala HMP instrument mounted at 10m would be named Ta_HMP_10m. If there is more than one measurement of air temperature from an HMP instrument at 10m then a letter is appended to the variable name e.g. Ta_HMP_10ma.
4. The convention of adding the instrument type to the variable is not always followed, for example the instrument type is often omitted for soil temperature, heat flux and moisture quantities. In these cases, ground heat flux for example is simply refered to as Fg_8cma or Fg_8cmb etc where Fg identifies the variable as ground heat flux, 8cm identifies the depth of the ground heat flux measurement and a, b, etc are appended to identify spatial replicates. However, users can include instrument type information in these variable names provided the rules for merging variables into a single name at L3, described below, are followed.
5. Users are at liberty to use almost any variable name at L1 and L2 but at L3 these must be combined into single variables, containing the best or average of the available data. For example, all ground heat flux quantities are combined at L3, using the AverageSeries instruction, into a single variable named Fg. For air temperatures, several quantities can be combined using MergeSeries e.g. merging Ta_HMP_10m, Ta_SONIC_Av and Ta_HMP_2m into a single varable called Ta. Combination of several quantities into a single variable is required for Ta, AH or RH, CO2, Ts etc is required at L3 so that PyFluxPro has a single, best possible quality variable for use at L4 to L6 processing.

Variable attributes: instrument

PyFluxPro allows the user to specify the instrument used to measure a variable. The instrument attribute is mandatory for variables associated with the sonic anemometer and the infra-red gas analyser and for these variables, the instrument attribute must come from a controlled vocabulary of instrument types known to PyFluxPro.

Table 4 lists the instrument types and models known to PyFluxPro for those variables where the instrument attribute is mandatory. Table 5 lists the variables for which the instrument attribute must come from Table 5.

Table 4: Instrument type and models known to PyFluxPro.

Instrument type	Instrument model
Sonic anemometers	CSAT3
	CSAT3A
	CSAT3B
	IRGASON
	Windmaster
	Windmaster Pro
	Windmaster RA
	Windmaster HS
	R3-50
	R3-100
	HS-50
	HS-100
Open-path IRGAs	Li-7500
	Li-7500A
	Li-7500DS
	Li-7500RS
	EC150
	IRGASON
Closed-path IRGAs	Li-7200
	Li-7200DS
	Li-7200RS
	Li-830
	Li-840
	Li-850
	EC155
	None

Table 5: Variables for which the instrument attribute must come from Table 4.

Variable name	Description	Instrument type	Examples
Fco2	CO2 flux	Sonic anemometers, open or closed-path IRGAs	CSAT3B,Li-7500RS
Fh2o	Water vapour flux	Sonic anemometers, open or closed-path IRGAs	CSAT3B,Li-7500RS
Fe	Latent heat flux	Sonic anemometers, open or closed-path IRGAs	CSAT3B,Li-7500RS
Fh	Sensible heat flux	Sonic anemometers	CSAT3B
Fm	Momentum flux	Sonic anemometers	CSAT3B
Sco2	CO2 flux (storage)	Closed-path IRGAs	Li-840
Signal_CO2	CO2 signal strength	Open or closed-path IRGAs	Li-7500RS
Signal_H2O	H2O signal strength	Open or closed-path IRGAs	Li-7500RS
UxA, UyA, UzA	Covariance of H2O and Ux, Uy and Uz	Sonic anemometers, open or closed-path IRGAs	CSAT3B,Li-7500RS
UxC, UyC, UzC	Covariance of CO2 and Ux, Uy and Uz	Sonic anemometers, open or closed-path IRGAs	CSAT3B,Li-7500RS
UxT, UyT, UzT	Covariance of Tv and Ux, Uy and Uz	Sonic anemometers	CSAT3B
UxUy, UxUz, UyUz	Covariances of Ux, Uy and Uz	Sonic anemometers	CSAT3B
Any name containing IRGA		Open or closed-path IRGAs	Li-7500RS
Any name containing SONIC		Sonic anemometers	CSAT3B

Variables such as the CO2 flux (Fco2), the latent heat flux (Fe), water vapour flux (Fh2o) and their associated covariances (UxA, UyA, UzA, UxC, UyC and UzC) use both a sonic anemometer and an IRGA. For these variables, the instrument attribute has 2 entries separated by a comma, one for the sonic and one for the IRGA e.g. CSAT3B,Li-7500RS. More examples of how to specify the instrument attribute can be found in the L1 control files for the Loxton, Calperum and Cumberland Plain example sites, see https://github.com/OzFlux/PFP_examples.git.