akqdecay-package: Asquith-Knight Discharge Decay Analyses
In wasquith-usgs/akqdecay: Many Distributional Statistics of USGS Daily Streamflow Hydrographs and Powerful Utilities
Description
Author(s)
References
See Also
Description
The akqdecay package is a narrowly focused R package with a purpose to compute distributional statistics of the N-day-over-day declines (recession limb, decreasing day-over-day) of base-10 logarithms of daily-mean streamflow for U.S. Geological Survey (USGS) streamflow-gaging stations (streamgages). Computational alterations, however, can be made to compute N-day-over-day inclines (rising limb, increasing day-over-day). Prodigious output tables are computed.
Statistical properties of streamflow recession provide evidence of hydrologic processes such as surface water and groundwater interactions. For example, a persistent streamflow recession slope, previously studied in Alabama (Bingham, 1982) and then again in Tennessee (Bingham, 1986), was referred to as the “G_b-factor” (the “Bingham geologic factor”). Bingham sought an approach for understanding and mapping general connectivity between surface water and groundwater in those study areas. The G_b-factor has been useful for other studies involving statistical regionalization of streamflow.
The G_b-factor was derived through graphical methods on hand-selected hydrographs for various periods of time. Bingham drew hydrographs on semi-log paper (log-streamflow) and estimated a generalized decay slope. The inverse of this slope has units of days per unit log10-cycle change in streamflow and such units are attractive for interpretation as well as simple convenience. The units state the number of days until an order of magnitude or power of 10 change.
The conceptual underpinning of the akqdecay package is the study of the persistence of the recession limb of streamflow hydrographs. This is accomplished through computation of an extensive array of distributional statistics of very many one-day-over-day slopes (Ψ) computed for a streamgage. The authors (Asquith and Knight) speculate that massive-scale data processing of days having declining streamflow for a vast number of streamgages will embody hydrologic concepts similar those associated with the G_b-factor without resorting to selection of ideal long-tailed hydrographs on which to compute a decay slope. These concepts include how surface water and groundwater interact to form statistical properties of N-day-over-day declines. Asquith and Knight propose that G_b-factors implicitly are related to magnitudes of one-day-over-day decay Ψ existing well within the right-tail of the distribution. Thus, amongst the many computed statistics by the akqdecay package, both a G_f(F;Θ)-factor is computed based on a nonexceedance probability F for F \in [0,1] and probability distribution parameters Θ and an empirical (nonparametric) G_f(F; Z) for a data sample Z of size N.
The function akqdecay is the central entry-point into this package, and this function provides the computational basis for the streamflow changes. The akqdecay function generates Asquith–Knight discharge decay analyses. Such analyses are a complex R data structures and represent the core deliverables the package. These data structures contain the distributional properties of streamflow changes as imparted by the median, L-moments (succinct summary statistics), and special quantiles of both (1) a fitted distribution and (2) the empirical distribution. Special attention is made in order to make period-of-record, annual, and decadal aggregations simultaneously available.
It is useful, though a little advanced in R language syntax, to succinctly show a “comprehensive” regional study of the distributional properties of streamflow recession. Minimalist code showing a framework for batch processing seeking (1) lag one-day as well as (2) decreasing one-day-over-day streamflow (see arguments for akqdecay) for six selected USGS Tennessee streamgages on the Wolf River is shown in the snippet below:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
wolfsites <- c("07030392", "07030500", "07031650",
"07031660", "07031700", "07031740") # USGS streamgages
wolfdv <- new.env(); akwolf <- new.env() # create environments
fdwolf <- new.env() # which are very handy for large table storage
fill_dvenv(wolfsites, envir=wolfdv) # wolfdv is FILLED!
fill_akqenv( dvenv=wolfdv, envir=akwolf) # akwolf is FILLED!
fill_tfdcenv(dvenv=wolfdv, envir=fdwolf) # fdwolf is FILLED!
rmsites <- union(akq_na(wolfdv),akq_na(akwolf)) # check for degenerates
akq_rm(wolfdv, rmsites); akq_rm(akwolf, rmsites) # remove them
wolfsites <- ls(DV) # reset the master list of sites
# Though for this example, no Wolf River sites are removed.
SU <- akq_summary( akwolf); print(head(SU)) # basic summary table
GT <- akq_global( akwolf); print(head(GT)) # global statistics
CN <- akq_counts( akwolf); print(head(CN)) # table of counts
LM <- akq_lmom( akwolf); print(head(LM)) # L-moments for POR
LY <- akq_lmom_year( akwolf); print(head(LY)) # L-moments by year
LD <- akq_lmom_decade(akwolf); print(head(LD)) # L-moments by decade
ST <- akq_table( akwolf) # continuous raw table for all streamgages
akq_scibase( akwolf) # dump to plain-text files of above tables
The daily values are retrieved (internally using dvget) and stored by streamgage identification number (wolfsites) in the user-named R environment (named wolfdv for the example). Asquith–Knight discharge decay analyses are computed for each streamgage and stored in akwolf. Use of environments as a core of multi-site processing by akqdecay is intended in this introductory example to emphasize the generalization of Asquith–Knight analyses for an arbitrary number of streamgages. (Be aware that the leading zero in very many USGS streamgage identification numbers causes a headache for R [who drops the leading zero in numbers!], and as a result these must by stored as character strings or carefully use the gsid2str function.) Finally, trend analysis on the ordinates of the flow-duration curves (fdctrend) by year and by streamgage are stored in fdwolf; users are directed to the Examples of fill_tfdcenv on how to interact and visualize this analysis.
The tables so stored in akwolf are possibly not immediately apparent for many users and even those with substantial R understanding. Therefore, several utility or data-extraction functions are provided to help end users (including the authors). These are akq_summary, akq_counts, and akq_lmom (other analogs are akq_lmom_yeardecade, akq_lmom_year, and akq_lmom_decade). The extracted data are in the from of R data.frame's; these data frames can be conveniently written by the utility function akq_write to the user's file system. An ensemble of plain-text output files of the tables from these extraction functions can be produced by akq_scibase, which is named for the contemporaneous (c.2017) distribution mechanism of certain USGS datasets. The so-called “site file” information for the sites can be acquired and emplaced in a spatial data object of the sp package using the function sites_to_SpatialPointsDataFrame.
The L-moments (see package lmomco, and Asquith, 2011, 2014) succinctly capture metrics of distributional geometry. In massive-scale data processing, there might be opportunities to investigate relations between L-moments and underlying surface water and groundwater interactions contributing to the such distributional properties of streamflow hydrograph recession limbs. The akqdecay package is setup, by default, to compute on decreasing days, and these results are in variables LM (period of record, all decreasing day-over-day daily values), LY (subsetted by calendar year), and LD (subsetted by decade).
Though advanced statistical concepts are involved (Asquith, 2011a,b), the relation between L-skew (τ_3) and L-kurtosis (τ_4) by year and again by decade (e.g. “2000” decade is defined for 01/01/2000 through 12/31/2009) for the Wolf River data can be shown by the following code:
1
2
3
4
5
6
lmomco::plotlmrdia(lmomco::lmrdia(), xlim=c(-0.05, 0.7), ylim=c(-0.1,0.6),
nopoints=TRUE)
points(LY$T3, LY$T4, lwd=0.8, col=1, cex=0.8) # by year
points(LD$T3, LD$T4, lwd=1.1, col=4, pch=22, bg=8, cex=1.2) # by decade
points(LM$T3, LM$T4, lwd=1.1, col=1, pch=21, bg=5, cex=1.5) # whole record
mtext("What distributional form (type) is acceptable to these data?")
Author(s)
W.H. Asquith, wasquith@usgs.gov; R.R. Knight, rrknight@usgs.gov
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., 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.
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.
Bingham, R.H., 1982, Low-flow characteristics of Alabama streams, USGS Water Supply Paper 2083, 27 p., https://doi.org/10.3133/wsp2083.
Bingham, R.H., 1986, Regionalization of low-flow characteristics of Tennessee streams: U.S. Geological Survey Water-Resources Investigations Report 85–4191, 63 p., https://doi.org/10.3133/wri854191.
See Also
akqdecay, # *** The very core of this package, and it will be loved before the end. ***
akq_counts, akq_lmom,
akq_summary, akq_table,
akq_write, akq_scibase, # data extraction
dvget, fill_akqenv, fill_dvenv, fill_tfdcenv # data and batch processing functions
gfredo, lmrdf2gfactor, gsid2str # manipulation functions
fdctrend, visFDCtrend # trend in the flow-duration curve
akq_summaryfilter, akq_na, akq_rm # utilities to refine processing
sites_to_SpatialPointsDataFrame # see the sp library
wasquith-usgs/akqdecay documentation built on Nov. 9, 2020, 1:13 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Description Author(s) References See Also
Description
The akqdecay package is a narrowly focused R package with a purpose to compute distributional statistics of the N-day-over-day declines (recession limb, decreasing day-over-day) of base-10 logarithms of daily-mean streamflow for U.S. Geological Survey (USGS) streamflow-gaging stations (streamgages). Computational alterations, however, can be made to compute N-day-over-day inclines (rising limb, increasing day-over-day). Prodigious output tables are computed.
Statistical properties of streamflow recession provide evidence of hydrologic processes such as surface water and groundwater interactions. For example, a persistent streamflow recession slope, previously studied in Alabama (Bingham, 1982) and then again in Tennessee (Bingham, 1986), was referred to as the “G_b-factor” (the “Bingham geologic factor”). Bingham sought an approach for understanding and mapping general connectivity between surface water and groundwater in those study areas. The G_b-factor has been useful for other studies involving statistical regionalization of streamflow.
The G_b-factor was derived through graphical methods on hand-selected hydrographs for various periods of time. Bingham drew hydrographs on semi-log paper (log-streamflow) and estimated a generalized decay slope. The inverse of this slope has units of days per unit log10-cycle change in streamflow and such units are attractive for interpretation as well as simple convenience. The units state the number of days until an order of magnitude or power of 10 change.
The conceptual underpinning of the akqdecay package is the study of the persistence of the recession limb of streamflow hydrographs. This is accomplished through computation of an extensive array of distributional statistics of very many one-day-over-day slopes (Ψ) computed for a streamgage. The authors (Asquith and Knight) speculate that massive-scale data processing of days having declining streamflow for a vast number of streamgages will embody hydrologic concepts similar those associated with the G_b-factor without resorting to selection of ideal long-tailed hydrographs on which to compute a decay slope. These concepts include how surface water and groundwater interact to form statistical properties of N-day-over-day declines. Asquith and Knight propose that G_b-factors implicitly are related to magnitudes of one-day-over-day decay Ψ existing well within the right-tail of the distribution. Thus, amongst the many computed statistics by the akqdecay package, both a G_f(F;Θ)-factor is computed based on a nonexceedance probability F for F \in [0,1] and probability distribution parameters Θ and an empirical (nonparametric) G_f(F; Z) for a data sample Z of size N.
The function akqdecay is the central entry-point into this package, and this function provides the computational basis for the streamflow changes. The akqdecay function generates Asquith–Knight discharge decay analyses. Such analyses are a complex R data structures and represent the core deliverables the package. These data structures contain the distributional properties of streamflow changes as imparted by the median, L-moments (succinct summary statistics), and special quantiles of both (1) a fitted distribution and (2) the empirical distribution. Special attention is made in order to make period-of-record, annual, and decadal aggregations simultaneously available.
It is useful, though a little advanced in R language syntax, to succinctly show a “comprehensive” regional study of the distributional properties of streamflow recession. Minimalist code showing a framework for batch processing seeking (1) lag one-day as well as (2) decreasing one-day-over-day streamflow (see arguments for akqdecay) for six selected USGS Tennessee streamgages on the Wolf River is shown in the snippet below:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | wolfsites <- c("07030392", "07030500", "07031650",
"07031660", "07031700", "07031740") # USGS streamgages
wolfdv <- new.env(); akwolf <- new.env() # create environments
fdwolf <- new.env() # which are very handy for large table storage
fill_dvenv(wolfsites, envir=wolfdv) # wolfdv is FILLED!
fill_akqenv( dvenv=wolfdv, envir=akwolf) # akwolf is FILLED!
fill_tfdcenv(dvenv=wolfdv, envir=fdwolf) # fdwolf is FILLED!
rmsites <- union(akq_na(wolfdv),akq_na(akwolf)) # check for degenerates
akq_rm(wolfdv, rmsites); akq_rm(akwolf, rmsites) # remove them
wolfsites <- ls(DV) # reset the master list of sites
# Though for this example, no Wolf River sites are removed.
SU <- akq_summary( akwolf); print(head(SU)) # basic summary table
GT <- akq_global( akwolf); print(head(GT)) # global statistics
CN <- akq_counts( akwolf); print(head(CN)) # table of counts
LM <- akq_lmom( akwolf); print(head(LM)) # L-moments for POR
LY <- akq_lmom_year( akwolf); print(head(LY)) # L-moments by year
LD <- akq_lmom_decade(akwolf); print(head(LD)) # L-moments by decade
ST <- akq_table( akwolf) # continuous raw table for all streamgages
akq_scibase( akwolf) # dump to plain-text files of above tables
|
The daily values are retrieved (internally using dvget) and stored by streamgage identification number (wolfsites) in the user-named R environment (named wolfdv for the example). Asquith–Knight discharge decay analyses are computed for each streamgage and stored in akwolf. Use of environments as a core of multi-site processing by akqdecay is intended in this introductory example to emphasize the generalization of Asquith–Knight analyses for an arbitrary number of streamgages. (Be aware that the leading zero in very many USGS streamgage identification numbers causes a headache for R [who drops the leading zero in numbers!], and as a result these must by stored as character strings or carefully use the gsid2str function.) Finally, trend analysis on the ordinates of the flow-duration curves (fdctrend) by year and by streamgage are stored in fdwolf; users are directed to the Examples of fill_tfdcenv on how to interact and visualize this analysis.
The tables so stored in akwolf are possibly not immediately apparent for many users and even those with substantial R understanding. Therefore, several utility or data-extraction functions are provided to help end users (including the authors). These are akq_summary, akq_counts, and akq_lmom (other analogs are akq_lmom_yeardecade, akq_lmom_year, and akq_lmom_decade). The extracted data are in the from of R data.frame's; these data frames can be conveniently written by the utility function akq_write to the user's file system. An ensemble of plain-text output files of the tables from these extraction functions can be produced by akq_scibase, which is named for the contemporaneous (c.2017) distribution mechanism of certain USGS datasets. The so-called “site file” information for the sites can be acquired and emplaced in a spatial data object of the sp package using the function sites_to_SpatialPointsDataFrame.
The L-moments (see package lmomco, and Asquith, 2011, 2014) succinctly capture metrics of distributional geometry. In massive-scale data processing, there might be opportunities to investigate relations between L-moments and underlying surface water and groundwater interactions contributing to the such distributional properties of streamflow hydrograph recession limbs. The akqdecay package is setup, by default, to compute on decreasing days, and these results are in variables LM (period of record, all decreasing day-over-day daily values), LY (subsetted by calendar year), and LD (subsetted by decade).
Though advanced statistical concepts are involved (Asquith, 2011a,b), the relation between L-skew (τ_3) and L-kurtosis (τ_4) by year and again by decade (e.g. “2000” decade is defined for 01/01/2000 through 12/31/2009) for the Wolf River data can be shown by the following code:
1 2 3 4 5 6 | lmomco::plotlmrdia(lmomco::lmrdia(), xlim=c(-0.05, 0.7), ylim=c(-0.1,0.6),
nopoints=TRUE)
points(LY$T3, LY$T4, lwd=0.8, col=1, cex=0.8) # by year
points(LD$T3, LD$T4, lwd=1.1, col=4, pch=22, bg=8, cex=1.2) # by decade
points(LM$T3, LM$T4, lwd=1.1, col=1, pch=21, bg=5, cex=1.5) # whole record
mtext("What distributional form (type) is acceptable to these data?")
|
Author(s)
W.H. Asquith, wasquith@usgs.gov; R.R. Knight, rrknight@usgs.gov
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., 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.
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.
Bingham, R.H., 1982, Low-flow characteristics of Alabama streams, USGS Water Supply Paper 2083, 27 p., https://doi.org/10.3133/wsp2083.
Bingham, R.H., 1986, Regionalization of low-flow characteristics of Tennessee streams: U.S. Geological Survey Water-Resources Investigations Report 85–4191, 63 p., https://doi.org/10.3133/wri854191.
See Also
akqdecay, # *** The very core of this package, and it will be loved before the end. ***
akq_counts, akq_lmom,
akq_summary, akq_table,
akq_write, akq_scibase, # data extraction
dvget, fill_akqenv, fill_dvenv, fill_tfdcenv # data and batch processing functions
gfredo, lmrdf2gfactor, gsid2str # manipulation functions
fdctrend, visFDCtrend # trend in the flow-duration curve
akq_summaryfilter, akq_na, akq_rm # utilities to refine processing
sites_to_SpatialPointsDataFrame # see the sp library
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.