TREXr (version 1.0.0)

tdm_dt.max: Calculate zero-flow conditions

Description

Determine zero flow conditions (\(\Delta T_{max}\); or \(\Delta V_{max}\)) according to four methods; namely, 1) predawn (pd), 2) moving-window (mw), 3) double regression (dr), and 4) environmental-dependent (ed) as applied in Peters et al. 2018. The function can provide (\(\Delta T_{max}\) values and subsequent K values for all methods. All outputs are provided in a list including the input data and calculated outputs.

Usage

tdm_dt.max(input, methods = c("pd","mw","dr","ed"),
zero.end = 8*60,
zero.start =  1*60,
interpolate = FALSE, det.pd = TRUE,
max.days = 7,
ed.window = 2*60,
vpd.input,
sr.input,
sel.max,
criteria = c(sr = 30, vpd = 0.1, cv = 0.5),
df = FALSE)

Arguments

input

An is.trex-compliant object of \(K\) values containing a timestamp and a value column.

methods

Character vector of the requested \(\Delta T_{max}\) methods. Options include <U+201C>pd<U+201D> (predawn), <U+201C>mw<U+201D> (moving-window), <U+201C>dr<U+201D> (double regression), and <U+201C>ed<U+201D> (environmental-dependent; default= c(<U+201C>pd<U+201D>, <U+201C>mw<U+201D>, <U+201C>dr<U+201D>)).

zero.end

Numeric, optionally defines the end of the predawn period. Values should be in minutes (e.g. predawn conditions until 08:00 = 8 * 60). When not provided, the algorithm will automatically analyse the cyclic behaviour of the data and define the day length.

zero.start

Numeric, optionally defines the beginning of the predawn period. Values should be in minutes (e.g., 01:00 = 1*60).

interpolate

Logical: if TRUE, detected \(\Delta T_{max}\) values are linearly interpolated. If FALSE, constant \(\Delta T_{max}\) values will be selected daily (default = FALSE).

det.pd

Logical; if TRUE and no zero.end and zero.start values are provided, predawn \(\Delta T_{max}\) will be determined based on cyclic behaviour of the entire time-series (default = TRUE).

max.days

Numeric, defines the number of days which the mw and dr methods will consider for their moving windows.

ed.window

Numeric, defines the length of the period considered for assessing the environmental conditions and stable \(\Delta T_{max}\) values.

vpd.input

An is.trex-compliant object (zoo time-series or data.frame) with a timestamp and a value column containing the vapour pressure deficit (vpd; in kPa) with the same temporal extent and time steps as the input data.

sr.input

An is.trex-compliant object (zoo time-series or data.frame) with a timestamp and a value column the solar radiation data (sr; e.g., global radiation or PAR).

sel.max

Optional zoo time-series or data.frame with the specified \(\Delta T_{max}\). This option is included to change predawn \(\Delta T_{max}\) values selected with the ed method.

criteria

Numeric vector, thresholds for the ed method. Thresholds should be provided for all environmental data included in the function (e.g. c(sr = 30, vpd = 0.1); coefficient of variation, cv = 0.5)

df

Logical; if TRUE, output is provided in a data.frame format with a timestamp and a value (\(\Delta T\) or \(\Delta V\)) column. If FALSE, output is provided as a zoo object (default = FALSE).

Value

A named list of zoo time series or data.frame objects in the appropriate format for further processing. List items include:

max.pd

\(\Delta T_{max}\) time series as determined by the pd method.

max.mw

\(\Delta T_{max}\) time series as determined by the mw method.

max.dr

\(\Delta T_{max}\) time series as determined by the dr method.

max.ed

\(\Delta T_{max}\) time series as determined by the ed method.

daily_max.pd

daily predawn \(\Delta T_{max}\) as determined by pd.

daily_max.mw

daily predawn \(\Delta T_{max}\) as determined by mw.

daily_max.dr

daily predawn \(\Delta T_{max}\) as determined by dr.

daily_max.ed

daily predawn \(\Delta T_{max}\) as determined by ed.

all.pd

exact predawn \(\Delta T_{max}\) values detected with pd.

all.ed

exact predawn \(\Delta T_{max}\) values detected with ed.

input

\(\Delta T\) input data.

ed.criteria

data.frame of the applied environmental and variability criteria used within ed.

methods

data.frame of applied methods to detect \(\Delta T_{max}\).

k.pd

\(K\) values calculated by using the pd method.

k.mw

\(K\) values calculated by using the mw method.

k.dr

\(K\) values calculated by using the dr method.

k.ed

\(K\) values calculated by using the ed method.

Details

There are a variety of methods which can be applied to determine zero-flow conditions. Zero-flow conditions are required to calculate \(K = (\Delta T_{max} - \Delta T) / \Delta T\). A detailed description on the methods is provided by Peters et al. (2018). In short, the pd method entails the selection of daily maxima occurring prior to sunrise. This method assumes that during each night zero-flow conditions are obtained. The algorithm either requires specific times within which it searches for a maximum, or it analyses the cyclic pattern within the data and defines this time window. The mw method uses these predawn \(\Delta T_{max}\) values and calculates the maximum over a multi-day moving time-window (e.g., 7 days). The dr methods is applied by calculating the mean over predawn \(\Delta T_{max}\) with a specified multi-day window, removing all values below the mean, and calculating a second mean over the same multi-day window and uses these values as \(\Delta T_{max}\). The ed method selects predawn \(\Delta T_{max}\) values based upon 2-hour averaged environmental conditions prior to the detected time for the predawn \(\Delta T_{max}\). These environmental conditions include low vapour pressure deficit (in \(kPa\)) and low solar irradiance (e.g., in W m-2). In addition, the coefficient of variation (cv) of predawn \(\Delta T_{max}\) are scanned for low values to ensure the selection of stable zero-flow conditions.

Examples

# NOT RUN {
#perform Delta Tmax calculations
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 = 6, df = FALSE)
input[which(input<0.2)]<- NA
output.max <- tdm_dt.max(input, methods = c("pd", "mw", "dr"),
                 det.pd = TRUE, interpolate = FALSE,
                 max.days = 10, df = FALSE)

str(output.max)

plot(output.max$input, ylab = expression(Delta*italic("V")))

lines(output.max$max.pd, col = "green")
lines(output.max$max.mw, col = "blue")
lines(output.max$max.dr, col = "orange")

points(output.max$all.pd, col = "green", pch = 16)

legend("bottomright", c("raw", "max.pd", "max.mw", "max.dr"),
        lty = 1, col = c("black", "green", "blue", "orange") )

# }