ExtractStats {HYPEtools}

Extract statistics from time series

Description

Calculate aggregated statistics from long-term time series, typically imported HYPE time output files.

Usage

ExtractStats(
  x,
  start.mon = 1,
  aggperiod = c("year", "season1", "season2", "month"),
  timestep = attr(x, "timestep"),
  subid = attr(x, "subid"),
  FUN,
  ...
)

Arguments

x

Data frame, with column-wise equally-spaced time series. Date-times in POSIXct format in first column. Typically an imported time output file from HYPE.

start.mon

Integer between 1 and 12, starting month of the hydrological year.

aggperiod

Character string, timestep for aggregated results. One of "year" for annual statistics, "season1" (winter/summer half-years), "season2" (4 seasons), or "month". See details.

timestep

Character string, timestep of data in x. Attribute timestep in x per default. Otherwise one of "month" (not allowed with aggperiod = "month"), "week", "day", or "nhour" (n = number of hours).

subid

Integer, a vector of HYPE subbasin IDs for data in x. Attribute subid in x per default.

FUN

A function to compute for each aggperiod in x.

...

Optional arguments to FUN.

Details

ExtractStats uses aggregate to calculate statistics for all data columns provided in x. Argument start.mon allows to define the start of the hydrological year. Hydrological seasons begin with winter (season1) or autumn (season2).

Value

ExtractStats returns a dataframe with starting dates for each aggregation period in the first column, and a descriptive aggregation period name in the second. Remaining columns contain aggregated results as ordered in x. Additional attributes subid with subbasin IDs, timestep with time step of the source data, and period with a two-element POSIXct vector containing start and end dates of the source data.

Note

If FUN returns several values per aggregation period, these are returned in nested columns in the resulting dataframe. See Value section for aggregate and example code below.

Examples

# Import example data
te1 <- ReadTimeOutput(filename = system.file("demo_model", "results",
"timeCOUT.txt", package = "HYPEtools"), dt.format = "%Y-%m")
# Extract maxima
ExtractStats(x = te1, start.mon = 1, FUN = max)
# Multiple result stats: Extract min, mean, and max in one go:
te2 <- ExtractStats(x = te1, start.mon = 1,
FUN = function(x) {c(min(x), mean(x), max(x))})
# extract mean from resulting nested dataframe:
data.frame(te2[, 1:2], sapply(te2[, -c(1:2)], function(x){x[, 2]}))