lmrdf2gfactor: Convert L-moment Data Frame from Asquith-Knight Discharge...

In wasquith-usgs/akqdecay: Many Distributional Statistics of USGS Daily Streamflow Hydrographs and Powerful Utilities

Description

Internally, akqdecay generates an R data.frame (actually several) having columns named L1, L2, T3, T4, T5, T6 for the first six L-moments (Asquith, 2018) of the N-day-over-day change values. This data frame is then augmented by a call to this function (lmrdf2gfactor) to compute the quantile for a given nonexceedance probability (F \in [0,1]) and distribution type as supported by the lmomco package.

Let us suppose that some 4,600 one-day-over-day of streamflow declines, expressed in units of days per base-10 logarithmic cycle (just “days”), have the following L-moments: λ_1 = 73 days (mean), λ_2 = 38 days (L-scale), and τ_3 = 0.4 dimensionless (L-skew). Let us suppose that the three-parameter generalized Pareto distribution (GPA) is applicable. The parameters of this distribution when fit to the L-moments are ξ = 2.429, α = 60.490, and κ = -0.1429. If the 90th percentile (F=0.90 nonexceedance probability) is reflective of long-term streamflow persistence (perhaps caused by sustained groundwater contributions) and is a suitable metric for Gfactor (G_f), this value thus is

G_f = x_{\mathrm{gpa}}(0.9; Θ) = 167\ \mathrm{days}\mbox{,}

where the requisite computations using the quantile function of the chosen distribution (x_{\mathrm{gpa}}) and parameters (Θ = (ξ, α, κ)) using the lmomco package are

  para <- lmomco::pargpa(lmomco::vec2lmom(c(73, 38, 0.4)))
  GF   <- lmomco::quagpa(0.9, para)
  message("# Gfactor=", round(GF, digits=1), " days (90th percentile estimate)")
  # Gfactor=167.4 days (90th percentile estimate)

Usage

lmrdf2gfactor(df, f, type="gpa", ...)

Arguments

df	An R data.frame with six named columns of L-moments: L1, L2, T3, T4, T5, and T6 for the L-moments λ_1, λ_2, τ_3, τ_4, τ_5, and τ_6, respectively;
f	Nonexceedance probability (F \in [0,1]), and the default is the 90th percentile;
type	Distribution type of the lmomco package to estimate the G_f factor for the probability f. If the type is NA, then the computation of the fitted distribution is short circuited; this is useful for speed during testing (for instance). The default is the three-parameter generalized Pareto; and
...	Additional arguments to pass to control functions lmom2par and qlmomco of the lmomco package.

Value

An R vector of quantiles from the probability distribution with a length of the number of rows in the data.frame represented by df. The first six L-moments are hardwired for computation if the sample size is sufficient for their respective computation, though in general practice a p-parameter distribution uses only the first p L-moments for parameter estimation. As a result, a three-parameter distribution, such as the generalized Pareto (GPA), requires only the first three L-moments for parameter estimation.

Note

This function is intended as a helper function for the internals of akqdecay, but it is generic enough to justify an user-level interface. The akqdecay package is intended for large data mining computations. Towards this goal, a special trap for incomplete L-moments is made for protection against failure within the lmomco package. If the L-moments do not test as valid by lmomco::are.lmom.valid() or if either L-skew (τ_3) or L-kurtosis (τ_4) is NA, then the Gfactor is computed as NA. This is mentioned because by design, it is easy to leak missing L-skew into lmomco's distribution fitting and breakage occurs there and not within akqdecay and that akqdecay does this protection for period-of-record statistics because lmrdf2gfactor is not called in that situation.

The GPA distribution is the default. The quantile function of the distribution is

x(F) = ξ + α[1-(1-F)^κ]/κ\mbox{,}

for κ \ne 0, and

x(F) = ξ - α\log(1-F)\mbox{,}

for κ = 0, where x(F) is the quantile for nonexceedance probability F, ξ is a location parameter, α (α > 0) is a scale parameter, and κ (κ > -1) is a shape parameter. The cumulative distribution function is

F(x) = 1 - \mathrm{exp}(-Y) \mbox{, and}

the probability density function is

f(x) = α^{-1} \exp[-(1-κ)Y] \mbox{,}

where Y is

Y = -κ^{-1}\log[1 - (κ(x-ξ)/α)]\mbox{,}

for κ \ne 0 and

Y = (x-ξ)/α\mbox{,}

for κ = 0. The L-moments in terms of the parameters are

λ_1 = ξ + α/(κ+1) \mbox{,}

λ_2 = α/[(κ+2)(κ+1)] \mbox{,}

τ_3 = (1-κ)/(κ+3) \mbox{, and}

τ_4 = (1-κ)(2-κ)/[(κ+4)(κ+3)] \mbox{.}

Author(s)

W.H. Asquith

References

Asquith, W.H., 2011a, Distributional analysis with L-moment statistics using the R environment for statistical computing: Ph.D. dissertation, Texas Tech University.

Asquith, W.H., 2011b, Distributional analysis with L-moment statistics using the R environment for statistical computing: CreateSpace, [print-on-demand], ISBN 978–146350841–8, https://www.amazon.com/dp/1463508417. [reprinting of Asquith (2011a) with errata]

Asquith, W.H., 2018, lmomco—L-moments, trimmed L-moments, L-comoments, censored
L-moments, and many distributions: R package version 2.3.2 at https://cran.r-project.org/package=lmomco.

See Also

akqdecay

Examples

# See Examples under akqdecay and elsewhere in this documentation.

wasquith-usgs/akqdecay documentation built on Nov. 9, 2020, 1:13 p.m.