TREXr (version 1.0.0)

tdm_cal.sfd: Calculate sap flux density

Description

The acquired \(K\) values are calculated to sap flux density (\(SFD\) in \(cm^3 cm^{-2} h^{-1}\)). As many calibration curves exist (see Peters et al. 2018; Flo et al. 2019), the function provides the option to calculate \(SFD\) using calibration experiment data from the meta-analyses by Flo et al. (2019; see cal.data). Additionally, raw calibration data can be provided or parameters \(a\) and \(b\) for a specific calibration function (\(aK^b\)) can be provided. The algorithm determines for each calibration experiment dataset the calibration curve (\(SFD = aK^b\)) and calculates \(SFD\) from either the mean of all curves and the 95% confidence interval of either all curves, or bootstrapped resampled uncertainty around the raw calibration experiment data when one calibration dataset is selected.

Usage

tdm_cal.sfd(
  input,
  genus,
  species,
  study,
  wood,
  calib,
  a,
  b,
  decimals,
  make.plot = TRUE,
  df = FALSE
)

Arguments

input

An is.trex-compliant object (zoo vector, data.frame) of \(K\) values containing a timestamp and a value column.

genus

Optional, character vector specifying genus-specific calibration data that should be used (e.g., c("Picea", "Larix")). See cal.data for the specific labels (default = Use all).

species

Optional, character vector of species specific calibration data that should be used, e.g. c("Picea abies"). See cal.data for the specific labels (default = Use all).

study

Optional character vector of study specific calibration data that should be used (e.g., c("Peters et al. 2018") ). See cal.data for the specific labels (default= Use all).

wood

Optional, character vector of wood type specific calibration data that should be used (one of c("Diffuse-porous", "Ring-porous", "Coniferous")). See cal.data for the specific labels (default= Use all).

calib

Optional data.frame containing raw calibration experiment values. Required columns include: [ ,1] \(K = K\) values measured with the probe (numeric), and [,2] \(SFD =\) Gravimetrically measured sap flux density (\(cm^3 cm^{-2} h^{-1}\))) (numeric). If not provided, literature values are used.

a

Optional, numeric value for the calibration curve (\(SFD = aK^b\)). No uncertainty can be calculated when this value is provided.

b

Optional, numeric value for the calibration curve (\(SFD = aK^b\)). No uncertainty can be calculated when this value is provided.

decimals

Integer, the number of decimals of the output (default = 6).

make.plot

Logical; if TRUE, a plot is generated showing the calibration curve with \(K vs sap flux density\) (\(cm^3 cm^{-2} h^{-1}\))).

df

Logical; If TRUE, output is provided in a data.frame format with a timestamp and a value column. If FALSE, output is provided as a zoo vector object (default = FALSE).

Value

A list containing either a zoo object or data.frame in the appropriate format for other functionalities (see tdm_dt.max output specifications), as well as all \(SFD\) values for each method are provided and added to the is.trex-compliant object (e.g., [['sfd.pd']], [['sfd.mw']]) if this format was provided as an input, and, finally, a data.frame is provided with the mean and 95% confidence interval of the applied calibration functions (see [['model.ens']]). If an individual time series is provided for input with \(K\) values an alternative output is provided:

input

K values provided as input.

sfd.input

\(SFD\) values calculated for the input according to the mean of the calibration function.

model.ens

A data.frame providing the mean and 95% confidence interval of the applied calibration function.

out.param

A data.frame with the coefficients of calibration function.

Details

The function fits a calibration curve (\(SFD = aK^b\)) through all selected raw calibration data. If multiple studies are provided, multiple calibration curves are fitted. In case a single calibration dataset is provided a bootstrap resampling is applied (n = 100) to determined the mean and 95% confidence interval of the fit. When multiple calibration curves are requested the mean and 95% confidence interval is determined on the fitted functions. The mean and confidence interval are used to calculate \(SFD\) from \(K\).

References

Peters RL, Fonti P, Frank DC, Poyatos R, Pappas C, Kahmen A, Carraro V, Prendin AL, Schneider L, Baltzer JL, Baron-Gafford GA, Dietrich L, Heinrich I, Minor RL, Sonnentag O, Matheny AM, Wightman MG, Steppe K. 2018. Quantification of uncertainties in conifer sap flow measured with the thermal dissipation method. New Phytologist 219:1283-1299 <doi: 10.1111/nph.15241>

Flo V, Martinez-Vilalta J, Steppe K, Schuldt B, Poyatos, R. 2019. A synthesis of bias and uncertainty in sap flow methods. Agricultural and Forest Meteorology 271:362-374 10.1016/j.agrformet.2019.03.012

Examples

# NOT RUN {
#calculating sap flux density
# }
# NOT RUN {
raw   <-is.trex(example.data(type="doy"),
    tz="GMT",time.format="%H:%M",
    solar.time=TRUE,long.deg=7.7459,
    ref.add=FALSE)

input <-dt.steps(input=raw,start="2014-05-08 00:00",
end="2014-07-25 00:50",
     time.int=15,max.gap=60,decimals=10,df=FALSE)

input[which(input<0.2)]<-NA

input <-tdm_dt.max(input, methods=c("pd","mw","dr"),
     det.pd=TRUE,interpolate=FALSE,max.days=10,df=FALSE)

output.data<-tdm_cal.sfd(input,make.plot=TRUE,df=FALSE,
wood="Coniferous", decimals = 6)


str(output.data)
plot(output.data$sfd.pd$sfd,ylim=c(0,10))
lines(output.data$sfd.pd$q025,lty=1,col="grey")
lines(output.data$sfd.pd$q975,lty=1,col="grey")
lines(output.data$sfd.pd$sfd)

output.data$out.param
# }
# NOT RUN {
# }