fdclmr: Compute the First Six L-moments of the Flow-Duration Curve...

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

Description

Compute the first six sample L-moments (\hatλ_1, \hatλ_2, \hatτ_3, \hatτ_4, \hatτ_5, and \hatτ_6; Asquith [2011a,b, 2018]) of the flow-duration curve (FDC) for each year passing a maximum number of missing days permissible. The missing days are implicitly assumed to be randomly distributed within a given year. (Most partial years in USGS databases are those on years of activation or discontinuance of a streamgage.)

The function also computes the minimum, median, and maximum in conjunction with the 7-day annual minimum flow (7-days consecutive) and the 7-day annual maximum flows. The total number of flow values and the number of zero flows (see Note) also are tracked. Finally, the function can compute on a decadal basis and when it does the quantiles of the FDC are computed too (see extended discussion in the Value section).

Usage

fdclmr(akdvtable, missing.days=7, site="", decade=FALSE,
                  minyear=NA, maxyear=NA,
                  log=FALSE, subzero=NULL, plusit=0, verbose=FALSE, ...)

Arguments

akdvtable	A USGS daily-value of streamflow table with some extensions unique to this package as returned by dvget;
missing.days	The number of permissible missing days in a given year on which to still compute the annual flow-duration curve and use that year in the trend test; The default is one week and it is advised to not exceed that count. The streamflow values are first reduced by removing NA before comparing the total number of values for a year against the value 365 minus missing.days. This argument is scaled up by 10 if decade=TRUE (computations are internal, user just needs to think about how many missing days per year might be acceptable, but internally these could be a consecutive block, for example, if a week was permitted for the decadal computations 70 missing days in a row would be permissible);
site	An optional streamgage identification number (or other character string). It is deliberate that this function does not pickup the site_no from the daily-value table akdvtable. This permits the user to potentially intercept the site number or name and replace with their own for flexibility in categorical statistical analyses in their own custom scripts;
decade	A logical to switch to decadal computations. A decade is already available in the akdvtable and see its documentation in dvget for the definition of decade for this package.
minyear	The optional minimum year of the daily-values table before any further computations are made.
maxyear	The optional maximum year of the daily-values table before any further computations are made.
log	Should base-10 logarithms of the daily streamflow be computed before L-moments computed (see also subzero and plusit);
subzero	If log=TRUE, a value for substitution for zero or less than zero values when log=TRUE. This feature is subject to change because of the non-optimality of such substitution. The subzero is used before the plusit;
plusit	If log=TRUE, a value for added to also values (not just those that are zero or less than zero);
verbose	A logical controlling a potentially helpful message that prints the site and the current year as they are looped through. This is similar to the silent in fill_lmrfdcenv, but named different here for discrete functionality between fdclmr and fill_lmrfdcenv; and
...	Additional arguments to pass.

Value

An R data.frame of mutable length but containing the following columns for decade=FALSE:

site	An echo of the site;
n	The number of days (values) entering into the L-moment computations;
nzero	The number of zero or less than zero flow days that would not enter into L-moment computations. This number has been recomputed internally if log=TRUE because the plusit and subzero are evaluated first;
pplo	The plotting position (Weibull) of the zero flow when log=FALSE. The x2xlo function is used from the lmomco package before the L-moments are computed (see internals here and documentation for x2xlo). It is critical to know that the L-moments are computed by lmoms(fdclo$in), which means that the L-moments are for the nonzero values as x2xlo has a default of leftout = 0. The defaults to x2xlo are used because it is set to zero as the threshold for truncation, which is appropriate for many potential applications in the arid and semi-arid regions of the world. Lastly, it is very important that the user of the L-moments track the value for pplo and use it in quantile function definition;
min	The minimum daily mean streamflow;
median	The median daily mean streamflow;
max	The maximum daily mean streamflow;
min7day	The minimum 7-day mean streamflow;
max7day	The maximum 7-day mean streamflow;
L1	The arithmetic mean (λ_1);
L2	L-scale (λ_2);
T3	L-skew (τ_3), third L-moment ratio;
T4	L-kurtosis (τ_4), fourth L-moment ratio;
T5	Fifth unnamed L-moment ratio (τ_5), but the term L-cinco occasionally could be used;
T6	Sixth unnamed L-moment ratio (τ_6), but the term L-seis could be used;
T7	Seventh unnamed L-moment ratio (τ_7), but the term L-siete could be used; and
T8	Eighth unnamed L-moment ratio (τ_8), but the term L-ocho could be used; and
median_nozero	The median of the nonzero flows (computation is median(fdclo$xin), see source code).

The output is the effectively the same with decade=TRUE, except year becomes decade, the median, min7day, and max7day are dropped. There are 27 columns holding quantiles of the empirical FDC are then included not counting the two for the minimum and maximum. These have column titles such as f50 (median), f0.1 (0.1 percentile), or f99.97 (99.97 percentile). These column titles are percentiles and not nonexceedance probabilities so division by 100 would be needed if the titles were parsed (leading f stripped) to dynamically compute the probabilities. These percentiles are fixed internally. Finally because 1 - 1/(10 \times 365.25+1) = 0.99972, the computed percentile extremum will match the min and max where 365.25 is the approximate average number of days and 10 represents a decade. The quantile() function with its argument type=6 (Weibull) is used internally to compute the empirical FDC.

Note

Concerning zero flows, these are used if log=FALSE. Otherwise additional adjustments are made for protection against -Inf. The germane logic for the arguments subzero and plusit is

   if(! is.null(subzero)) fdc[fdc == 0] <- subzero
   if(! is.null(plusit )) fdc <- fdc + plusit

So with this logic arrangement it is possible, though the reasoning is uncertain for both operations to be used simultaneously (a warning is issued), to substitute the zero values and add something to all the values.

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

fill_lmrfdcenv, lmrfdc_table

Examples

# See Examples under fill_lmrfdcenv and elsewhere in this documentation.


# USGS 14362000 Applegate River near Copper, Oregon
dv <- dvget("14362000", sdate="1980-01-01", edate="1999-12-12")
fdclmr(dv, decade=TRUE) # see the 1990 decade is populated but 1999 by itself
# in yearly extraction have more than one week missing and is not provided
fdclmr(dv, decade=TRUE) # because 70 days missing in the decade were okay.

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