spti_coverage: Calculate spatio-temporal sampling coverage

In lsigut/openeddy: Post-process eddy covariance data with ease

Calculate spatio-temporal sampling coverage

Description

Yearly estimates of spatial, temporal and spatio-temporal sampling coverage based on comparison of ideal vs observed number of samples in spatial and/or temporal bins.

Usage

spti_coverage(
  df,
  TimestampCol = "TIMESTAMP_START",
  wdCol = "WD",
  targetCol = "NEE_VUT_REF",
  QcCol = "NEE_VUT_REF_QC",
  plot = FALSE,
  nInt = 8L,
  year = NULL
)

Arguments

df	A data frame.
TimestampCol	A character string. Specifies a column name in df that carries date-time information either in POSIXt or text strings of format "%Y%m%d%H%M". Date-time information is expected to represent either start or middle of the averaging period.
wdCol	A character string. Specifies a column name in df that carries the wind direction in degrees.
targetCol	A character string. Specifies a column name in df that carries the flux values for sampling coverage assessment.
QcCol	A character string or NULL. Specifies a column name in df that carries gap-filling quality flags of targetCol variable. It is assumed that df[, QcCol] == 0 identifies the measured (not gap-filled) records of targetCol variable. If NULL, all non-missing values of targetCol are used for budgeting.
plot	A logical value. If FALSE (default), a data frame with sampling coverage values for each year is returned. Otherwise a list of ggplots showing spatial and temporal sampling coverage for each year is returned.
nInt	An integer value. A number of wind sectors and time intervals for binning.
year	Either integer vector, character string "all" or NULL. If NULL (default), estimates are produced for each year available in df. If "all", estimates are produced across all years. Otherwise only specified years are processed.

Details

Arguments specifying df column names represent FLUXNET standard. To process REddyProc outputs, timestamp must be corrected to represent middle of averaging period and appropriate columns selected (see Examples).

Sampling coverage (SC) ranges from 0 (unilateral sampling) to 1 (fully balanced sampling when all bins contribute evenly), i.e. SC close to 1 is the most ideal. Note that SC = 1 - Gini, where Gini is Gini index used as a measure of statistical dispersion. The dotted line showing cumulative contribution of ranked observations in SC plots is also known as Lorenz curve.

Value

If plot = FALSE, a data frame. If plot = TRUE, a named list of ggplot objects.

References

Griebel, A., Metzen, D., Pendall, E., Burba, G., & Metzger, S. (2020). Generating spatially robust carbon budgets from flux tower observations. Geophysical Research Letters, 47, e2019GL085942. https://doi.org/10.1029/2019GL085942

See Also

Griebel20_budgets and spti_boot.

Examples

## Not run: 
library(REddyProc)

# convert timestamp
DETha98 <- fConvertTimeToPosix(Example_DETha98, 'YDH', Year = 'Year',
Day = 'DoY', Hour = 'Hour')[-(2:4)]

# generate randomly wind directions for demonstration purposes (not included)
DETha98$WD <- sample(0:359, nrow(DETha98), replace = TRUE)

# if QcCol = NULL, all non-missing values of targetCol are used for budgeting
not_filled <- DETha98
not_filled$DateTime <- not_filled$DateTime - 900

spti_coverage(not_filled, "DateTime", "WD", "LE", NULL)
spti_coverage(not_filled, "DateTime", "WD", "LE", NULL, plot = TRUE)

# gap-filling is not needed but illustrates processing of FLUXNET data
# notice that ustar filtering of NEE should be applied before budgeting
DETha98 <- filterLongRuns(DETha98, "NEE")
EProc <- sEddyProc$new('DE-Tha', DETha98,
c('NEE', 'Rg', 'Tair', 'VPD', 'Ustar'))
EProc$sMDSGapFillAfterUstar('NEE', uStarTh = 0.3, FillAll = TRUE)
filled <- cbind(DETha98, EProc$sExportResults())

# correct timestamp to represent middle of averaging period
filled$DateTime <- filled$DateTime - 900
spti_coverage(filled, "DateTime", "WD", "NEE", "NEE_uStar_fqc")
spti_coverage(filled, "DateTime", "WD", "NEE", "NEE_uStar_fqc", plot = TRUE)

## End(Not run)

lsigut/openeddy documentation built on Aug. 5, 2023, 12:25 a.m.