spti_coverage.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Summarizing.R
\name{spti_coverage}
\alias{spti_coverage}
\title{Calculate spatio-temporal sampling coverage}
\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{
\item{df}{A data frame.}

\item{TimestampCol}{A character string. Specifies a column name in \code{df}
that carries date-time information either in \code{POSIXt} or text strings
of format \code{"\%Y\%m\%d\%H\%M"}. Date-time information is expected to
represent either start or middle of the averaging period.}

\item{wdCol}{A character string. Specifies a column name in \code{df} that
carries the wind direction in degrees.}

\item{targetCol}{A character string. Specifies a column name in \code{df}
that carries the flux values for sampling coverage assessment.}

\item{QcCol}{A character string or \code{NULL}. Specifies a column name in
\code{df} that carries gap-filling quality flags of \code{targetCol}
variable. It is assumed that \code{df[, QcCol] == 0} identifies the
measured (not gap-filled) records of \code{targetCol} variable. If
\code{NULL}, all non-missing values of \code{targetCol} are used for
budgeting.}

\item{plot}{A logical value. If \code{FALSE} (default), a data frame with
sampling coverage values for each year is returned. Otherwise a list of
\code{ggplot}s showing spatial and temporal sampling coverage for each year
is returned.}

\item{nInt}{An integer value. A number of wind sectors and time intervals for
binning.}

\item{year}{Either integer vector, character string \code{"all"} or
\code{NULL}. If \code{NULL} (default), estimates are produced for each year
available in \code{df}. If \code{"all"}, estimates are produced across all
years. Otherwise only specified years are processed.}
}
\value{
If \code{plot = FALSE}, a data frame. If \code{plot = TRUE}, a named
  list of \code{ggplot} objects.
}
\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.
}
\details{
Arguments specifying \code{df} column names represent FLUXNET standard. To
process \code{REddyProc} outputs, timestamp must be corrected to represent
middle of averaging period and appropriate columns selected (see
\code{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 \eqn{SC = 1 - Gini}, where \eqn{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.
}
\section{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.
  \url{https://doi.org/10.1029/2019GL085942}
}

\examples{
\dontrun{
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)
}

}
\seealso{
\code{\link{Griebel20_budgets}} and \code{\link{spti_boot}}.
}