checkShapeFunction: Test a custom shape function

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

Test a custom shape function

Description

Integrate a shape function from tau_0 to tau_n.

Usage

checkShapeFunction(
  shape,
  tau,
  tau_n,
  ...,
  MoreArgs = NULL,
  integrateArgs = list(),
  valuesOnly = F
)

Arguments

shape	A shape function or character string containing the name of the shape function.
tau_n	Upper time bound of the definite integral of interest.
...	Parameters required by <shape> over which the function will be vectorized.
MoreArgs	A names list of parameters that will be passed directly to <shape> without vectorization. Use this, e.g., if the <shape> file requires a list to prevent vectorization (and associated recyling) of the list.
valuesOnly	When T, return value will be a numeric vector of values. When F, return value will be a list of integration objects (see integrate)
tau_0	Lower time bound of the definite intergal of interest.
integrationArgs	A named list of optional parameters for integrate.

Details

To generate transient storage zone statistics, shape functions (see, e.g., powerLaw) can be integrated numerically (passed to integrate). Occasionally, depending on the units of time chosen for tau or for other reasons, integrate will fail, reporting that the shape function is "probabaly divergent" (see examples, below). checkShapeFunction provides a means to test different integration options when numerical integration fails.

The function works by passing the shape function to integrate. Using this function, you can try different units of tau (e.g., hours or days rather than seconds) or potentially manipulate the optional parameters of integrate (e.g., subdivisions, rel.tol, etc.) using the integrateArgs list. See the examples, below.

Examples

checkShapeFunction("powerLaw", 60, 3600, alpha = 1.5)
checkShapeFunction("powerLaw", 60, 3600, alpha = c(1.3, 1.5, 1.7))

# try integrating from 1 minute to 180 days:
# when units are seconds, numerical integration fails:
checkShapeFunction("powerLaw", 60, 15552000, alpha = 1.5) #FAIL
# numerical integration succeeds when units are hours
checkShapeFunction("powerLaw", 1/60, 4320, alpha = 1.5)

# passing through optional parameters to integrate() function.
# Default values for subdivisions is 100 (see help for integrate() function).
# Set subdivisions unreasonably low, and integration fails:
checkShapeFunction("powerLaw", 60, 3600, alpha = 1.5, integrationArgs = list(subdivisions = 2))
# increase subdivisions somewhat and integration succeeds.
checkShapeFunction("powerLaw", 60, 3600, alpha = 1.5, integrationArgs = list(subdivisions = 10))

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