AnnualRegime: Calculate annual regimes

Description

Calculate annual regimes based on long-term time series, typically imported HYPE basin output and time output result files.

Usage

AnnualRegime(
  x,
  stat = c("mean", "sum"),
  ts.in = NULL,
  ts.out = NULL,
  start.mon = 1,
  incl.leap = FALSE,
  na.rm = TRUE,
  format = c("list", "long")
)

Value

If argument format is list, AnnualRegime returns a list with 8 elements and two additional attributes(). Each list element contains a named data frame with aggregated annual regime data: arithmetic means, medians, minima, maxima, and 5%, 25%, 75%, and 95% percentiles.

Each data frames contains, in column-wise order: reference dates in POSIXct format, date information as string, and aggregated variables found in x.

Reference dates are given as dates in either 1911, 1912, or 1913 (just because a leap day and outer weeks '00'/'53' occur during these years) and can be used for plots starting at the beginning of the hydrological year (with axis annotations set to months only). Daily and hourly time steps are given as is, weekly time steps are given as mid-week dates (Wednesday), monthly time steps as mid month dates (15th).

If argument format is long, AnnualRegime returns a four-column data frame with one value per row, and all variable information aligned with the values. Columns in the data frame: id with SUBIDs or HYPE variable IDs, month/week/day with aggregation time steps, name with short names of regime data (means, medians, minima, maxima, percentiles), and value with the variable value.

Attribute period contains a two-element POSIXct vector containing start and end dates of the source data. Attribute timestep contains a timestep keyword corresponding to function argument ts.out.

Arguments

x: Data frame, with column-wise equally-spaced time series. Date-times in POSIXct format in first column. Typically an imported basin or time output file from HYPE. See details.
stat: Character string, either "mean" or "sum". Defines the type of aggregation to be computed for output time periods, see Details. Defaults to "mean".
ts.in: Character string, timestep of x, attribute timestep in x per default. Otherwise one of "month", "week", "day", or "nhour" (n = number of hours).
ts.out: Character string, timestep for results, defaults to ts.in. This timestep must be equal to or longer than ts.in.
start.mon: Integer between 1 and 12, starting month of the hydrological year, used to order the output.
incl.leap: Logical, leap days (Feb 29) are removed from results per default, set to TRUE to keep them. Applies to daily and shorter time steps only.
na.rm: Logical, indicating if NA values should be stripped before averages are calculated.
format: Character string. Output format, list (default) or long. See Value.

Details

AnnualRegime uses aggregate to calculate long-term average regimes for all data columns provided in x, including long-term arithmetic means, medians, minima and maxima, and 5%, 25%, 75%, and 95% percentiles. With HYPE result files, AnnualRegime is particularly applicable to basin and time output files imported using ReadBasinOutput and ReadTimeOutput. The function does not check if equally spaced time steps are provided in x or if the overall time period in x covers full years so that the calculated averages are based on the same number of values.

Values within each output time period can be aggregated either by arithmetic means or by sums within each period, e.g. typically means for temperatures and sums for precipitation. Long-term aggregated values are always computed as arithmetic means.

Examples

Run this code

# Source data, HYPE basin output with a number of result variables
te <- ReadBasinOutput(filename = system.file("demo_model", "results", "0003587.txt", 
package = "HYPEtools"))
# Daily discharge regime, computed and observed, hydrologigical year from October 
AnnualRegime(te[, c("DATE", "COUT", "ROUT")], ts.in = "day", start.mon = 10)
# Id., aggregated to weekly means
AnnualRegime(te[, c("DATE", "COUT", "ROUT")], ts.in = "day", ts.out = "week", start.mon = 10)
# Long format, e.g. for subsequent plotting with ggplot
AnnualRegime(te[, c("DATE", "COUT", "ROUT")], ts.in = "day", ts.out = "week", format = "long", 
start.mon = 10)
# Precipitation regime, monthly sums
AnnualRegime(te[, c("DATE", "UPCPRC")], ts.in = "day", ts.out = "month", stat = "sum")