HMR (version 0.4.2)

HMR: Flux estimation with static chamber data

Description

HMR reads static chamber data from a semicolon- or comma-separated file, and then processes each data series by recommending a specific data analysis and performing the user selected analysis. Finally, it exports the results to a semicolon- or comma-separated file.

Usage

HMR(filename, series = NA, dec = '.', sep = ';', JPG = FALSE, PS = FALSE,
PHMR = FALSE, npred = 500, LR.always = FALSE, FollowHMR = FALSE, ngrid = 1000,
kappa.fixed = FALSE)

Arguments

filename

The name of a HMR data file. It is assumed that the data file folder has previously been set by the setwd command, e.g. setwd('C:/My HMR applications'), or through the 'File|Change dir...' menu. The required fixed format of HMR data files is described in the details section below.

series

Data series in the data file for which analysis is requested. The default series=NA requests analysis of all available data series, whereas for example series=c('k0a','k0d') only requests analysis of the series named k0a and k0d, cf. the sample data in the details section below.

dec

The decimal separator used in the data file. The options are dec='.' and dec=',', and the default is dec='.'.

sep

The column separator used in the data file. The options are sep=';' and sep=',', and the default is sep=';'.

JPG

A logical indicating whether plots of the model fits should be exported as JPG-files. A plot is exported for each analysed data series, and the files are named after the data series and located in the data file folder. The default is JPG=FALSE.

PS

A logical indicating whether plots of the model fits should be exported as postscript files. A plot is exported for each analysed data series, and the files are named after the data series and located in the data file folder. The default is PS=FALSE.

PHMR

A logical indicating whether model predicted values should be exported to a file for data series for which non-linear modeling is selected. The export file is column separated like the data file and it is located in the data file folder and named after the data file preceded by 'PHMR - '. The default is PHMR=FALSE.

npred

If PHMR=TRUE (see above), npred model predicted values are exported for each data series. The default is npred=500.

LR.always

A logical indicating whether data series should be analysed by linear regression in addition to the user selected analysis. The default is LR.always=FALSE.

FollowHMR

A logical indicating whether to select the data analysis recommended by HMR in all cases. This cancels all plotting. The default is FollowHMR=FALSE.

ngrid

The number of grid-points in the initial grid search of the minimum of the criterion function. It must be at least 100, and the default is ngrid=1000.

kappa.fixed

A logical indicating whether the curvature parameter \(\kappa\) should be considered known (kappa.fixed=TRUE) or the estimation uncertainty should be accounted for in the standard error of the estimated flux (kappa.fixed=FALSE). Option kappa.fixed=FALSE ensures consistency between the standard errors and p-values of the three available methods, as methods "LR" (\(\kappa\)=0) and "No flux" (\(\kappa\)=infinity) discard the estimation uncertainty in the chosen value of \(\kappa\). For non-linear data, however, the standard error and the the p-value will be underestimated with method "HMR". Option kappa.fixed=FALSE ensures that the standard error and the p-value are not underestimated for non-linear data with method "HMR". The difference between the two options is particularly important with nearly linear data, where kappa.fixed=FALSE may present a statistically insignificant non-linear flux and a statistically significant linear flux. The default is kappa.fixed=FALSE.

Value

A data frame with one row per analysed data series and variables:

Series

Name of the data series.

f0

The estimated flux.

f0.se

The standard error of the estimated flux.

f0.p

The p-value for the null hypothesis of zero flux.

f0.lo95

The lower end-point of the 95%-confidence interval for the flux.

f0.up95

The upper end-point of the 95%-confidence interval for the flux.

Method

The method used for estimating the flux.

Warning

A character string that contains a warning message in case of estimation problems, e.g. if linear regression estimated a negative predeployment concentration.

LR.f0

The flux estimated by linear regression. (Only present if LR.always=TRUE.)

LR.f0.se

The standard error of the flux estimated by linear regression. (Only present if LR.always=TRUE.)

LR.f0.p

The p-value for the null hypothesis of zero flux calculated by linear regression. (Only present if LR.always=TRUE.)

LR.f0.lo95

The lower end-point of the 95%-confidence interval for the flux calculated by linear regression. (Only present if LR.always=TRUE.)

LR.f0.up95

The upper end-point of the 95%-confidence interval for the flux calculated by linear regression. (Only present if LR.always=TRUE.)

LR.Warning

A character string that contains a warning message if linear regression estimated a negative predeployment concentration. (Only present if LR.always=TRUE.)

The data frame is also exported to a file named after the data file preceded by 'HMR - ' and located in the data file folder. The exported file uses the same column separator as the data file.

Details

HMR data files must be semicolon- or comma-separated files organised in five columns containing data series names, chamber volumes, chamber cross-sectional areas, observation time-points, and the observed chamber concentrations. Semicolon- and comma-separated files may be edited by text editors or spreadsheet software. The following 45 lines constitute an example of a HMR data file containing five data series of static chamber data:

Series;V;A;Time;Concentration
 k0a; 140.6250; 0.5625;   0;  13.98
 k0a; 140.6250; 0.5625;  10;  14.65
 k0a; 140.6250; 0.5625;  20;  15.15
 k0a; 140.6250; 0.5625;  30;  15.85
 k0a; 140.6250; 0.5625;  40;  16.29
 k0a; 140.6250; 0.5625;  50;  17.17
 k0a; 140.6250; 0.5625;  60;  17.45
 k0a; 140.6250; 0.5625;  70;  17.85
 k0a; 140.6250; 0.5625;  80;  17.79
 k0a; 140.6250; 0.5625;  90;  17.89
 k0a; 140.6250; 0.5625; 100;  17.63
 k0a; 140.6250; 0.5625; 110;  17.82
 k0d; 140.6250; 0.5625;   0;  15.60
 k0d; 140.6250; 0.5625;  10;  15.62
 k0d; 140.6250; 0.5625;  20;  16.53
 k0d; 140.6250; 0.5625;  30;  16.90
 k0d; 140.6250; 0.5625;  40;  17.40
 k0d; 140.6250; 0.5625;  50;  17.69
 k0d; 140.6250; 0.5625;  60;  18.64
 k0d; 140.6250; 0.5625;  70;  18.36
 k0d; 140.6250; 0.5625;  80;  19.14
 k0d; 140.6250; 0.5625; 110;  18.83
 k0d; 140.6250; 0.5625; 120;  19.27
F1T3;   2.0101; 0.0201;   0;  15.00
F1T3;   2.0101; 0.0201;  26;  39.34
F1T3;   2.0101; 0.0201;  49;  91.74
F1T3;   2.0101; 0.0201;  87; 121.66
F1T3;   2.0101; 0.0201; 117; 130.33
F1T3;   2.0101; 0.0201; 147; 132.04
F1T3;   2.0101; 0.0201; 182; 147.97
F1T3;   2.0101; 0.0201; 213; 149.78
F1T3;   2.0101; 0.0201; 262; 152.37
F2T2;   2.0101; 0.0201;   0;  10.87
F2T2;   2.0101; 0.0201;  20;  19.49
F2T2;   2.0101; 0.0201;  54;  24.99
F2T2;   2.0101; 0.0201;  85;  27.24
F2T2;   2.0101; 0.0201; 119;  33.13
F2T2;   2.0101; 0.0201; 155;  30.14
F2V2;   2.0101; 0.0201;   0;   9.94
F2V2;   2.0101; 0.0201;  28;  31.64
F2V2;   2.0101; 0.0201;  60;  48.88
F2V2;   2.0101; 0.0201;  91;  58.08
F2V2;   2.0101; 0.0201; 123;  76.16
F2V2;   2.0101; 0.0201; 162; 106.83

Apart from the (required) headline the five columns contain:

• Column 1:Text labels that identify the data series. The labels must be 100% identical within data series and different between data series. In the sample data above, the first column identifies five data series named k0a, k0d, F1T3, F2T2, and F2V2.

• Column 2:The chamber volume, \(V\). In the sample data above, \(V=140.625\) [\(L\)] for data series k0a and k0d, and \(V=2.0101\) [\(L\)] for data series F1T3, F2T2, and F2V2.

• Column 3The chamber cross-sectional area, \(A\). In the sample data above, \(A=0.5625\) [\(m^2\)] for data series k0a and k0d, and \(A=0.0201\) [\(m^2\)] for data series F1T3, F2T2, and F2V2.

• Column 4:The non-negative measurement time-points in increasing order. At least three observation time-points per data series is required. In the sample data above, the time-points are provided in minutes and cover, approximately, two-four hour periods per data series.

• Column 5:The chamber concentrations associated with the time-points in the fourth column. In the sample data above, this column contains concentrations of nitrous oxide [\(\mu g/L\)].

Missing values (NA's) are not allowed in HMR data files.

There are no requirements regarding the units of input data. The chosen units do, however, determine the unit of the estimated flux, which has the same unit as \((VC)/ (At)\), where \(t\) and \(C\) denote, respectively, time and concentration. Some examples:

• \(V\) in [\(L\)], \(A\) in [\(m^2\)], \(t\) in [\(h\)], \(C\) in [\(\mu g/L\)]: The flux unit is [\(\mu g/m^2/h\)].

• \(V\) in [\(L\)], \(A\) in [\(m^2\)], \(t\) in [\(min.\)], \(C\) in [\(ppmv=\mu L/L\)]: The flux unit is [\(\mu L/m^2/min.\)].

• \(V\) in [\(m^3\)], \(A\) in [\(km^2\)], \(t\) in [\(s\)], \(C\) in [\(kg/m^3\)]: The flux unit is [\(kg/km^2/s\)].

The HMR function analyses the data series sequentially, and starts each analysis by fitting the non-linear function (Hutchinson and Mosier, 1981) $$C_t=\varphi+f_0 e^{-\kappa t}$$ using a single-parameter (\(\kappa\)) criterion (concentrated least squares; Seber and Wild, 1989). In this equation, \(f_0\) denotes the initial flux, \(\varphi\) denotes the new chamber equilibrium concentration, and \(\kappa>0\) is an adaption rate that depends on soil, gas, and chamber characteristics. The HMR function then recommends a particular analysis, and the user is requested to confirm it or to select another data analysis. The possible choices are:

• HMR: Non-linear regression.

• LR: Linear regression.

• No flux: Abort analysis and claim zero flux.

The HMR function recommends the first choice if possible, but for linear concentration data or noisy data representing no clear trend the non-linear function will be overparameterised, and the HMR function will recommend linear regression or no flux. For linear concentration data the criterion function will not possess a unique optimum but rather continue to improve as \(\kappa\) tends to zero, and in such cases the HMR function will recommend data analysed by linear regression. For noisy concentration data with no clear trend the criterion function will also not possess a unique optimum but rather continue to improve as \(\kappa\) tends to infinity, and in such cases the HMR function will recommend data analysed by linear regression, or, if assuming a linear trend seems inappropriate, to abort analysis and claim no flux.

To assist the user in selecting a data analysis the HMR function displays plots -- organised in a 2x2 matrix -- of the criterion function and the various models fits. The upper left plot displays the criterion function over the range of numerically feasible values of \(\kappa\). Green parts of the curve represent values of \(\kappa\) for which the corresponding estimated values of \(\varphi\) and \(C_0\) are valid (positive), whereas red parts of the curve represent values of \(\kappa\) for which this is not the case. The optimal value of \(\kappa\) (minimises the criterion function over the valid values of \(\kappa\)) is indicated by a blue square. The upper right plot is a zoom into the upper left plot. The lower left plot displays the model fit of the various possible models, and the HMR recommendation for data analysis is displayed in the headline. The lower right panel contains four 'buttons' representing the four possible user selections (select by left mouse button click). Pressing the cancel button terminates the HMR function without completing the requested analyses.

References

Hutchinson, G.L. and Mosier, A.R. (1981). Improved soil cover method for field measurement of nitrous oxide fluxes. Soil Science Society of America Journal, 45, p. 311-316.

Seber, G.A.F. and Wild, C.J. (1989). Nonlinear regression. Wiley, New York.

Examples

# NOT RUN {
# Suppose the sample data above are located on a Windows machine
# in the file 'C:\My HMR applications\N2O.csv'.

# Start by setting the data file folder:
setwd('C:/My HMR applications')

# Notice that R uses '/' in folder declarations, whereas
# Windows uses '\'.

# Analyse all data series:
HMR(filename='N2O.csv')

# Produces the following output:
  Series         f0      f0.se       f0.p     f0.lo95    f0.up95 Method Warning
1    k0a 2.5968E+01 4.5356E+00 2.8500E-04  1.5708E+01 3.6229E+01    HMR    None
2    k0d 1.8720E+01 4.1881E+00 2.0842E-03  9.0617E+00 2.8377E+01    HMR    None
3   F1T3 2.1265E+02 3.6719E+01 1.1605E-03  1.2280E+02 3.0250E+02    HMR    None
4   F2T2 4.5093E+01 1.4702E+01 5.4691E-02 -1.6971E+00 9.1882E+01    HMR    None
5   F2V2 5.5853E+01 3.5905E+00 9.9703E-05  4.5884E+01 6.5822E+01     LR    None

# The output is also exported to the semicolon-separated file
# 'C:\My HMR applications\HMR - N2O.csv'.

# Analyse data series 'k0a' and 'k0d' and export model predicted
# chamber concentrations:
HMR(filename=datafile,series=c('k0a','k0d'),PHMR=TRUE)

# The model predicted concentrations are exported to the file
# 'C:\My HMR applications\PHMR - N2O.csv'.

# Analyse all data series with both linear regression and the
# user selected analysis:
HMR(filename='N2O.csv',LR.always=TRUE)

# Produces the following (slightly edited) output:
  Series         f0      f0.se       f0.p     f0.lo95    f0.up95 Method Warning...
1    k0a 2.5968E+01 4.5356E+00 2.8500E-04  1.5708E+01 3.6229E+01    HMR    None...
2    k0d 1.8720E+01 4.1881E+00 2.0842E-03  9.0617E+00 2.8377E+01    HMR    None...
3   F1T3 2.1265E+02 3.6719E+01 1.1605E-03  1.2280E+02 3.0250E+02    HMR    None...
4   F2T2 4.5093E+01 1.4702E+01 5.4691E-02 -1.6971E+00 9.1882E+01    HMR    None...
5   F2V2 5.5853E+01 3.5905E+00 9.9703E-05  4.5884E+01 6.5822E+01     LR    None...

...      LR.f0   LR.f0.se    LR.f0.p LR.f0.lo95 LR.f0.up95 LR.Warning
... 8.9948E+00 1.1729E+00 1.7021E-05 6.3813E+00 1.1608E+01       None
... 8.0045E+00 1.0199E+00 2.5776E-05 5.6974E+00 1.0312E+01       None
... 5.0291E+01 9.9206E+00 1.4481E-03 2.6833E+01 7.3750E+01       None
... 1.2259E+01 2.9792E+00 1.4675E-02 3.9872E+00 2.0531E+01       None
... 5.5853E+01 3.5905E+00 9.9703E-05 4.5884E+01 6.5822E+01       None

# The output is also exported to the semicolon-separated file
# 'C:\My HMR applications\HMR - N2O.csv'. Hence, several analyses
# of the same data file overwrites the output file, so to save a
# particular output file it has to be renamed before the next
# application of HMR to the same data file.
# }