aggs_across_years: Calculate temporal aggregations across annual values

In DrylandEcology/rSW2metrics: Calculate Ecohydrological Metrics from SOILWAT2 Simulations

Calculate temporal aggregations across annual values

Description

Calculate temporal aggregations across annual values

Usage

aggs_across_years(x, fun, list_years, id_scens = NULL, combine = TRUE)

Arguments

x	A two-dimensional object where rows represent units/cases and (at least some of the) columns represent annual (numerical) values (with column names as scX_YYYY where X is the scenario identifier 1, 2, ... and YYYY is a calendar year).
fun	A function that has x as argument, can accept na.rm as additional argument, e.g., via ... (see examples), and returns a named vector.
list_years	A list with integer vectors. Each element represents a continuous sequence of years over which aggregations are to be calculated.
id_scens	An integer vector of scenario identifiers or NULL; see details.
combine	A logical value. If TRUE, then the data columns scX_YYYY are appended to the returned object.

Details

Arguments list_years and id_scens specify two modes of aggregations:

• Both arguments, i.e., list_years and id_scens, are specified. There must be one element in list_years for each value of id_scens.

• Only list_years is provided as argument. Each element of list_years is applied to each scenario available in x.

Years requested by list_years but not available in x are silently ignored!

Notes

The package rSW2metrics offers two pathways to across-year summaries:

1. aggs_across_years() calculates across-year summaries from output of a time-series metric; this can be calculated after extractions or requested with command-line options -add_aggs_across_yrs and -ts.

2. Metrics that directly return across-year summaries, i.e., climatologies; those are internally calculated by calc_climatology().

Both pathways utilize the user-defined function fun_aggs_across_yrs() from "Project_Parameters.R.

Examples

x <- data.frame(
  site = paste0("Site_", 1:3),
  matrix(
    sample(3 * 2 * 6),
    nrow = 3,
    dimnames = list(NULL, paste0("sc", rep(1:2, each = 6), "_", 2001:2006))
  )
)

# Temporal summary for two time periods for each available scenario
# Note that requested years 2007 to 2010 are silently ignored
rSW2metrics::aggs_across_years(
  x,
  fun = rSW2metrics::mean_cv,
  list_years = list(2001:2006, 2005, 2004:2010),
  combine = FALSE
)

# Temporal summary for one time period per requested scenario
# Note that some requested years and some scenarios are not available
rSW2metrics::aggs_across_years(
  x,
  fun = rSW2metrics::mean_cv,
  list_years = list(2001:2006, 2004:2006, 1990:2010),
  id_scens = 1:3,
  combine = FALSE
)

# Count years used in temporal summaries
rSW2metrics::aggs_across_years(
  x,
  fun = function(x, ...) c(N = length(x)),
  list_years = list(2001:2006, 2004:2006, 1990:2010),
  id_scens = 1:3,
  combine = FALSE
)

DrylandEcology/rSW2metrics documentation built on May 25, 2023, 10:38 a.m.