TSZStats: Generate transient storage statistics

In FluvialLandscapeLab/hydrogeom: Calculate Hydrologic Geometry of Expansive Hyporheic Zones

Generate transient storage statistics

Description

The exchange of water among and size of multiple transient storage zones within the hyporehic zone are calculated according to the method describe in Poole et al. (In prep). Calculations are made either by utilizing solutions to various integrations of a shape function (e.g., powerLawPDF and associated fuctions) or via numerical integration of a shape fuction (e.g., powerLaw).

Usage

TSZStats(
  TSZs,
  tau_0,
  tau_n,
  storage = NULL,
  q = NULL,
  ...,
  factor = NULL,
  shape = "powerLaw",
  MoreArgs = list(),
  metric = c("s", "q"),
  integrateArgs1 = list(),
  integrateArgs2 = list(),
  forceNumeric = F,
  optimizeInterval = NULL,
  optimizeTol = .Machine$double.eps^0.25
)

hyporheicBins(
  nbins,
  factor,
  minRT,
  maxRT,
  porosity,
  hyporheicSize,
  hyporheicExchange = NULL,
  b = NULL,
  integrateArgs = list()
)

Arguments

TSZs	Either the number of transient storage zones requested, or a vector of residence times that serve as the breakpoints among transient stroage zones.
tau_0	The smallest residence time to be considered part of the hyporheic zone.
tau_n	The largest residence time to be considered part of the hyporehic zone.
storage	Amount of water stored in the hyporheic zone. Units can be length, area, or volume, but must be consistent across parameters.
q	Gross hyporheic exchange per time unit. Exchange can be unit can be length, area, or volume per unit time, but must be the same as used units used to describe storage. Time unit must be the same as units used to describe tau_0 and tau_n.
...	Additional arguments required by shape function (e.g., alpha for powerLaw). Must be named. First of these values can be passed as NULL and will be estimated if both storage and q are provided. See details.
factor	Controls the distribution of residence time for transient storage zones when TSZs is set equal to the number of transient storage zones. Value must be either 0 or >=1. See details. factor is ignored when TSZs is a vector of the residence time breakpoints between transient storage zones.
shape	A character string naming the shape file (e.g., powerLaw) to be used in the calculation of transient storage statistics.
MoreArgs	A named list of additional parameter values to be passed to the shape function – only valid when numerical integration is used; ignored when solutions to the shape function are used. When passed this way, the values will not be vectorized with tau, tau_0, tau_n, tau_b, or arguments in '...'.
metric	A character vector where the first value is either 's' or 'q'. This parameter is considered only when factor parameter is 0 (even bins are requested). If the 's' or unspecified, TSZs with even storage are returned. If 'q', TSZs with even discharge are returned.
integrateArgs1, integrateArgs2	When numerical integration is used, these parameters are a named list of optional values for the integrate function. For PDF and CCDF calculations, integrateArgs1 is used and integrateArgs2 is ignored. For the integration of the PDF, CCDF, tau*PDF or tau*CCDF, integrateArgs1 will apply to the internal call to the PDF or CCDF functions and integrateArgs2 will apply to the subsequent integration of those functions. In practise, use of these parameters is seldom required. These parameters are useful only if and unexpected error message is returned by the integrate function.
forceNumeric	When set to TRUE, uses numeric integration even when solution in available.
optimizeInterval	A vector of two numerical values passed to the optimize function describing the range of plausible values for a NULL parameter included in '...'. See description of '...' above.
optimizeTol	Another value passed to optimize when a NULL parameter is included in '...'. Default value is usually sufficient. See documentation for optimize
nbins	See "TSZs" parameter.
minRT, maxRT	See "tau_0" and "tau_n" paramters.
porosity	Porosity of the alluvial aquifer.
hyporheicSize	See "storage" paramter.
hyporheicExchange	See "q" parameter.
b	Exponent for the power law RTD (passed as a negative value)
integrateArgs	Values passed through to the integrate function.

Details

When factor == 0, transient storage zone breakpoints will be determined such that each transient storage zone has and equal amount of water storage. When factor is 1 or greater, factor is used as a mutiplier to determine the residence times associated with each TSZ such that the range of residence times contained in any TSZ is <factor> times larger than the range of residence times contained in the previous TSZ. So if factor == 2, the range of residence times in each TSZ will be 2x the range of the prior TSZ.

If passed as NULL, the value for first parameter after tau and tau_n in the formals of the function named by shape can be estimated by TSZStats, however non-NULL values for both storage and q must be provided. For instance, for the function powerLaw, a value for alpha will be estimated by TSZStats if alpha = NULL is included in the call to TSZStats along with non-NULL values for storege and q.

HyporheicBins has been depricated and is now a wrapper for TSZStats. Use TSZStats instead.

Value

A TSZ object, which is a data.frame with attributes that record the arguments (TSZs, tau_0, tau_n, storage, q, factor, and forceNumeric, along with any shape specific parameters (e.g., alpha for powerLaw)) used to calculate the values in the data.frame. Attributes also include the descrepancy between the request and calculated q and storage. Descrepancy values should be

FluvialLandscapeLab/hydrogeom documentation built on May 13, 2022, 10 p.m.