gfredo: Recompute Gfactor from the L-moment Data Frames from...

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

Description

Recompute parametric Gfactors (gfactor; G^\mathrm{type}_f) from L-moment lmoments$ data frames for por, by_year, and by_decade. Also recompute empirical Gfactors (gfactor_emp; G^\mathrm{emp}_f) from the table data frame. Specifically, the function modifies the gfactor and gfactor_emp columns in the output structure of akqdecay. The Gfactor specifically is G_f(F;Θ_\mathrm{type}) for nonexceedance probability F \in [0,1] and parameters Θ for a given type of distribution computed by the method of L-moments (Asquith, 2018). This function is a wrapper (abstraction layer) on lmrdf2gfactor and serves as a means for updating the R environment from fill_akqenv. The gfredo function can thus be used to avoid recalling fill_akqenv as a means to update the G_f estimation but avoids a huge amount of redundant computation—there is no need to recompute the L-moments, for example.

Usage

gfredo(akqenv, f=0.90, type="gpa", which=c("por", "year", "decade"),
               all=TRUE, showdiffsum=FALSE, setgfna=FALSE, silent=FALSE, ...)

Arguments

akqenv	The R environment populated by fill_akqenv. This argument can also be a direct R list from akqdecay, special accommodation is made;
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 for the probability f. If the type is NA, then the computation of the fitted distribution is short circuited. The default is the three-parameter generalized Pareto (GPA), and mathematics of the GPA are listed under lmrdf2gfactor;
which	The style or type of L-moment storage. This argument is named similarly to the which argument of the akq_lmom;
all	A logical and if set, each of the "por", "year", and "decade" are swept through regardless of the setting of which in order to update the entire L-moment structure as built by akqdecay. It is almost asured that users want to keep this as all=TRUE, and the option is mostly present for the developer;
showdiffsum	This function computes new G_f and as a result, it might be useful to review the effect of the change in G_f from old to new. This argument triggers a simple print around the built-in R summary() function;
setgfna	If set, then Gfactor (gfactor; G_f) is set to NA. This can be a useful function if the user wants to focus on empirical Gfactor (gfactor_emp) or desires rapid updating;
silent	Suppress informative calls to R message; and
...	Additional arguments to pass (see source code to ascertain flexible usage).

Value

This function is intended to be used for its side effects on the akenv. Though if that argument is an R data.frame then that after G_f modification is returned.

Author(s)

W.H. Asquith

References

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

lmrdf2gfactor

Examples

## Not run: 
# USGS 11502500 Williamson River below Sprague River near Chiloquin, Oregon
AK <- akqdecay(dvget("11502500", sdate="1920-01-01", edate="2015-12-31"))
AK <- gfredo(AK, f=0.80, type="gpa", showdiffsum=TRUE)
#   Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
#  25.65   48.81   74.29  108.30  177.40  276.20
#   Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
#  43.44   64.18   96.26  119.10  182.40  219.00
#   Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
#  132.2   132.2   132.2   132.2   132.2   132.2
#  The 132.2 is the day change from old to new for period of record. # 
## End(Not run)

## Not run: 
sites <- c("05403500", "05405000") # Two streamgages in Wisconsin
WisExample <- new.env(); fill_dvenv( sites,      envir=WisExample,
                                     sdate="1945-01-01", edate="2015-12-31")
WisAKQ <- new.env(); fill_akqenv(dvenv=WisExample, envir=WisAKQ, type="gev")
#      Note that the generalized extreme value distribution is used (gev).
gfredo(WisAKQ, f=0.95, all=FALSE, showdiffsum=TRUE) # 95th percentile
#  Recomputing gfactors for 05403500 (1/2) for por -- got'em
#    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
#  -61.48  -61.48  -61.48  -61.48  -61.48  -61.48
#  Recomputing gfactors for 05405000 (2/2) -- got'em
#    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
#  -87.71  -87.71  -87.71  -87.71  -87.71  -87.71
gfredo(WisAKQ, f=0.95, all=FALSE, which="year")   # now redo the years
gfredo(WisAKQ, f=0.95, all=FALSE, which="decade") # now redo the decades

# Better yet, let the function by default redo all three to the 89th percentile.
# but convert back to the generalized Pareto distribution.
gfredo(WisAKQ, f=0.89, all=TRUE, type="gpa", silent=TRUE) #
## End(Not run)

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