Users guide

Contents:

• Repository structure
• Data formats

Repository structure

Repository folder structure

• /pack
  • /pack/eddy4R.base (all commonalities should go here)
  • /pack/eddy4R.erf (time horizon 2017)
  • /pack/eddy4R.qaqc
  • /pack/eddy4R.stor
  • /pack/eddy4R.turb
  • /pack/eddy4R.zre
  • …
• /flow (all unrefined non-demo, non-vignette workflows should go here)
  • contains workflow templates for specific project, such as ERF
  • only workflow template has to be modified to run a different aircraft / site
• /tool
  • e.g. .gzip batch file for 7zip and instructions

R-package folder structure and file types

• modifications to the underlying science happen in folder /R
  • one file per function
  • function definitions def in folder /R
  • function wrappers wrap in folder /R, making it more convenient to access frequently used sequences of "function definitions"
• refined workflow files flow
  • derived function wrappers wrap in folder /R
  • derived demos or vignettes in folders /demo or /vignette

Data formats

Missing data

Missing data values must be specified as NA or NaN.

Time representation

Internally, eddy4R uses UTC time. Currently, all input time variables must be in UTC, though future improvements will perform automatic time conversion upon data ingest. Input time data must be represented as character strings using the ISO 8601 time format (e.g. 2015-06-05T17:00:01.383Z).

Units

Defining variable units

Units are defined as a character string attached as an attribute to a variable or data frame. The attribute name is unit. In the case of 1-D variables, the unit attribute is attached directly to the variable. For example, suppose the variable data is a 1-D atomic vector of integers 1 to 10 and its unit is kilograms (denoted as "kg"; unit abbreviations are covered in the next section). When its unit is appropriately attached as an attribute, calling data from the command prompt yield's the following:

> data  
 [1]  1  2  3  4  5  6  7  8  9 10  
attr(,"unit")  
[1] "kg"  

In the case of data frames containing 1 or more variables, a vector containing the units for all variables is attached as an attribute to the data frame. Ideally, the unit attribute vector is named, but this is not required. For example, suppose the data frame data contains 3 variables: var01 consists of integers 1 to 10 in meters ("m"), var02 consists of integers 11 to 20 in grams ("g"), and var03 consists of integers 21 to 30 in radians ("rad"). Querying data and its attributes from the command prompt yields the following:

> data  
   var01 var02 var03  
1      1    11    21  
2      2    12    22  
3      3    13    23  
4      4    14    24  
5      5    15    25  
6      6    16    26  
7      7    17    27  
8      8    18    28  
9      9    19    29  
10    10    20    30  

> attributes(data)  
$names  
[1] "var01" "var02" "var03"  

$row.names  
[1]  1  2  3  4  5  6  7  8  9 10  

$class  
[1] "data.frame"  

$unit  
var01  var02    var03
  "m"    "g"    "rad"  

When manipulating data provided as data frames in functions and workflows, it may be helpful to extract a variable out of the data frame and retain the units. The eddy4R.base function def.unit.extr performs this action.

Constructing unit character strings

Unit character strings are constructed and interpreted following these rules: 

1. The (case-sensitive) unit base symbol is selected from those listed in eddy4R.base package data IntlUnit$Base$Symb (e.g. the base symbol for meter is "m"). 
2. The unit base symbol can be directly preceded (no space) by one of the (case-sensitive) unit prefixes listed in eddy4R.base package data IntlUnit$Prfx (e.g. kilo = "k", thus kilometers = "km"). 
3. The unit base symbol can be directly followed (no spaces) by the suffix n, where n is an integer (...-2,-1,0,1,2...), indicating the unit (incl. prefix) is raised to the power of n (e.g. per square kilometer = "km-2"). A suffix of 1 (one) need not be specified. 
4. In the case of chemical species attached to a unit, specify the full unit (including prefix and suffix) followed immediately (no spaces) by one of the chemical species character strings in eddy4R.base package data IntlUnit$Spcs (e.g. per gram of carbon dioxide = "g-1Co2").
5. Compound units can be formed by inserting a space between each full unit specification created by rules 1-4 (e.g. milligrams carbon per meter squared per day = "mgC m-2 d-1").

All available unit base symbols, types, prefixes, and associated chemical species are stored and documented as package data IntlUnit in the eddy4R.base package. IntlUnit can be accessed directly once the eddy4R.base package is loaded, although it is recommended to use the double-colon operator (i.e. eddy4R.base::IntlUnit) to avoid masking by other packages or variables loaded in the global environment.

If a variable has no unit, use "NA" as the unit character string.

eddy4R internal units

The eddy4R family of packages uses a consistent set of units (base unit and prefix) conforming to the International System (SI) of Units. The internal unit for each unit type is documented in eddy4R.base package data IntlUnit$Intl, copied here in expanded form (unit strings in brackets):

Distance/length = meter [m]
Mass = kilogram [kg]
Time = second [s]
Temperature = kelvin [K]
Number = mole [mol]
Geometric Angle = radian [rad]
Dimensionless (Ratio) = ratio [-]
Current = ampere [A]
Electrical potential = volt [V]
Electrical resistance = ohm [ohm]
Pressure = pascal [Pa]
Power = watt [W]
Energy = joule [J]
Force = newton [N]
Frequency = Hertz [Hz]

Compound units are formed by combining these base terms, with appropriate suffixes and chemical species. Internally, gas concentrations and fluxes are always specified in number units (e.g. "molCo2 m-3", not "kgCo2 m-3"). Input data must conform to this internal unit base, and unless specified otherwise, results will be output in internal units. The section below describes tools for converting between units and to/from the internal unit base.

Unit conversion

Converting between units is aided by the eddy4R.base package function def.unit.conv. This function allows units to be converted by specifying input and output unit character strings, or by supplying polynomial conversion equation coefficients. If selected, units can be converted automatically to/from the internal unit base. See the function documentation for details.

All available conversions for base units and prefixes (used by def.unit.conv) are stored and documented in eddy4R.base package data IntlConv. IntlConv is a named list of numerical polynomial conversion coefficients, specified as n-element vectors of a0,a1,a2,... corresponding to a0 + a1x + a2x^2 + ..., where n is 1 + the polynomial degree. It can be accessed directly via eddy4R.base::IntlConv. For example, the polynomial coefficients for converting from feet to meters (Meters = 0.3048*Feet) is retrieved via:

> eddy4R.base::IntlConv$FeetMetr
[1] 0.0000 0.3048

See the documentation IntlConv for more details and a list of available conversions.

Natural Constants

Natural constants used in the eddy4R family of packages, such as the ideal gas constant, are stored and documented as a named list in eddy4R.base package data IntlNatu. IntlNatu can be accessed directly via eddy4R.base::IntlNatu. For example, Earth's gravitational constant is retrieved via:

> eddy4R.base::IntlNatu$Grav
[1] 9.81
attr(,"unit")
[1] "m s-2"

See the documentation for IntlNatu for a list of available conversions.