akq_lmom: L-moment Table from the Asquith-Knight Discharge Decay...

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

Description

Extract the L-moments (Asquith, 2018) from the Asquith–Knight discharge decay analyses returned by akqdecay for a sequence of USGS streamgages contained within the R environment that has been previously populated by fill_akqenv. The akq_lmom_yeardecade function is a parent function called by the functions akq_lmom_year and akq_lmom_decade in a self-evident manner. There are provisions for performing the Kendall Tau test for monotonic trend in time (Helsel and Hirsch, 2002) using the built-in R cor.test() function.

Usage

akq_lmom(           akqenv, silent=FALSE, ...)
akq_lmom_yeardecade(akqenv, which=c("year", "decade"),
                            silent=FALSE, tauenv=NULL, ...)
akq_lmom_year(      akqenv, ...) # wrapper on the above function
akq_lmom_decade(    akqenv, ...) # wrapper on the above function

Arguments

akqenv	The R environment populated by fill_akqenv. This argument can also be an R list directly from akqdecay; special accommodation is made;
silent	Suppress informative calls to message();
which	The argument controlling whether the returned L-moment summary table is on a by year or by decade basis;
tauenv	An optional R environment in which the Taus and p-values for the Kendall Tau test for monotonic trend in time are held. If NULL, then logic for the trend testing is not triggered; however, if the akqenv is not an environment and directly the R list results of akqdecay, then the Kendall Tau test is always triggered and available as attributes (attr) of the returned R data.frame. The tauenv option is not used by akq_lmom. The tauenv will not work as expected (function with crash) if the processing is being made on L-moment tables based on method="nochange" passed to akqdecay; and
...	Additional arguments to pass (see source code to ascertain flexible usage).

Value

An R data.frame containing the L-moments for each streamgage depending on which form of retrieval is requested. The first of the Examples shows extraction of the Kendall Tau test for a single streamgage in Oregon. The second example shows the L-moments for the period of record for two streamgages in Wisconsin. The third example shows extraction of the Kendall Tau test for the two Wisconsin streamgages. The fourth example shows manual extraction of sample sizes and first L-moment (arithmetic mean) and plots a pair of time series. For both styles of Kendall Tau test, the results are accessed by the tau and tau_p.value attribute or label in the environment. Thus, this function also is used for its side effects on the tauenv argument as applicable.

An attribute skipped_sites is attached to the returned data frame when akenv is an environment and contains, because most assuredly of sample size considerations, a vector of the sites that lacked an L-moment table (period-of-record, decadal, or yearly as applicable). Another attribute is which that contains the year or decade when either is triggered by the function call.

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 Independent Publishing Platform, 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.

Asquith, W.H., 2014, Parameter estimation for the 4-parameter asymmetric exponential power distribution by the method of L-moments using R: Computational Statistics and Data Analysis, v. 71, pp. 955–970, https://doi.org/10.1016/j.csda.2012.12.013.

Helsel, D.R. and Hirsch, R.M., 2002, Statistical Methods in Water Resources: U.S. Geological Survey Techniques of Water Resources Investigations, book 4, chapter A3, 522 p., https://doi.org/10.3133/twri04A3.

Hosking, J.R.M., 1990, L-moments—Analysis and estimation of distributions using linear combinations of order statistics: Journal of the Royal Statistical Society, Series B, v. 52, pp. 105–124.

See Also

akqdecay, fill_akqenv, akq_counts, akq_summary

Examples

# The Kendall Tau test is housed within the attributes of the data.frame when
# a single station is involved.
# USGS 11502500 Williamson River below Sprague River near Chiloquin, Oregon
AK <- akqdecay(dvget("11502500", sdate="1920-01-01", edate="2015-12-31"))
LY <- akq_lmom_year(AK)
taus <- attr(LY, "tau"); pvls <- attr(LY, "tau_p.value")
# Show Kendall's tau and p-value for the empirical gfactor vs year.
message("90th-percentile gfactor_emp: tau=",round(taus[5], digits=4),
                                  " [pval=",round(pvls[5], digits=4),"]")
# 90th-percentile gfactor_emp: tau=0.5691 [pval=0] #

## Not run: 
sites <- c("05403500", "05405000") # Two streamgages in Wisconsin
WisExample <- new.env(); fill_dvenv( sites,              envir=WisExample,
                                     sdate="1945-01-01", edate="2014-12-31")
WisAKQ <- new.env(); fill_akqenv(dvenv=WisExample, envir=WisAKQ)
akq_lmom(WisAKQ)
#     site yr_range_str count   median     L1L2  gfactor gfactor_emp
# 05403500   1945--2014  8829 37.98102 122.2805 134.2363    136.2484
# 05405000   1945--2014 13293 34.52598 151.0085 157.0361    170.1584
#       L1       L2        T3        T4        T5        T6
# 63.81979 32.98290 0.5122438 0.3445989 0.2373858 0.1744530
# 72.84326 44.10004 0.5655227 0.3728133 0.2536264 0.1770801

# The Kendall tau test for both Wisconsin streamgages.
TY <- new.env() # to house the Kendall tau results by year
TD <- new.env() # to house the Kendall tau results by decade
LY <- akq_lmom_year(  WisAKQ, tauenv=TY); # print(TY$tau); print(TY$tau_p.value)
LD <- akq_lmom_decade(WisAKQ, tauenv=TD); # print(TD$tau); print(TD$tau_p.value)
message("90th-percentile gfactor_emp: tau=",round(TY$tau[5], digits=4),
                                  " [pval=",round(TY$tau_p.value[5], digits=4),"]")
# 90th-percentile gfactor_emp: tau=c(0.3051, 0.6704) [pval=c(0.0016, 0)]

# See first example using the two Wisconsin streamgages.
TMP <- WisAKQ$"05405000"$lmoments$by_year
txt <- "1-day-over-day declines, in days per log10-cycle decline"
plot(TMP$year, TMP$count, xlab="Years", ylab=paste0("Number of ",txt))
mtext("USGS 05405000 BARABOO RIVER NEAR BARABOO, WI")

plot(TMP$year, TMP$L1,    xlab="Years", ylab=paste0("Mean ",     txt))
mtext("USGS 05405000 BARABOO RIVER NEAR BARABOO, WI") #
## End(Not run)

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