calc_annual_flow_stats: Calculate annual flow statistics from daily data

Description

Calculate annual flow statistics from daily data

Usage

calc_annual_flow_stats(
  data = NULL,
  Date,
  year_group,
  Q,
  Q3 = NA_real_,
  Q7 = NA_real_,
  Q30 = NA_real_,
  jd = NA_integer_,
  calc_high = FALSE,
  calc_low = FALSE,
  calc_percentiles = FALSE,
  calc_monthly = FALSE,
  calc_WSCVD = FALSE,
  longitude = NA,
  calc_ICVD = FALSE,
  zero_threshold = 33,
  quantile_type = 8,
  na.action = c("na.omit", "na.pass")
)

Value

A tibble (see tibble::tibble) with annual statistics depending on options selected. See Details.

Arguments

data: 'data.frame'. Optional data.frame input, with columns containing Date,
year_group, Q, and Q3, Q7, Q30, jd (if required). Column names are specified as strings in the corresponding parameter. Default is NULL.
Date: 'Date' or 'character' vector when data = NULL, or character' string identifying Date column name when data is specified. Date associated with each value in Q parameter.
year_group: 'numeric' vector when data = NULL, or 'character' string identifying grouping column name when data is specified. Year grouping for each daily value in Q parameter. Must be same length as Q parameter. Often year_group is water year or climate year.
Q: 'numeric' vector when data = NULL, or 'character' string identifying streamflow values column name when data is specified. Daily streamflow data. Must be same length as year_group.
Q3: 'numeric' vector when data = NULL, or 'character' string identifying Q3 column name when data is specified. 3-day moving average of daily streamflow data Q parameter, often returned from preproc_precondition_data. Default is NA_real_, required if calc_high or calc_low = TRUE. If specified, must be same length as Q parameter.
Q7: 'numeric' vector when data = NULL, or 'character' string identifying Q7 column name when data is specified. 7-day moving average of daily streamflow data Q parameter, often returned from preproc_precondition_data. Default is NA_real_, required if calc_high or calc_low = TRUE. If specified, must be same length as Q parameter.
Q30: 'numeric' vector when data = NULL, or 'character' string identifying Q30 column name when data is specified. 30-day average of daily streamflow data Q parameter, often returned from preproc_precondition_data. Default is NA_real_, required if calc_high or calc_low = TRUE. If specified, must be same length as Q parameter.
jd: 'numeric' vector when data = NULL, or 'character' string identifying jd column name when data is specified. Calendar Julian day of daily streamflow data Q parameter, often returned from preproc_precondition_data. Default is NA_integer_, required if calc_high, calc_low, calc_WSCVD or calc_ICVD = TRUE. If specified, must be same length as Q parameter.
calc_high: 'boolean' value. Calculate high flow statistics for years in year_group. Default is FALSE. See Details for more information.
calc_low: 'boolean' value. Calculate low flow statistics for years in year_group. Default is FALSE. See Details for more information.
calc_percentiles: 'boolean' value. Calculate percentiles for years in year_group. Default is FALSE. See Details for more information.
calc_monthly: 'boolean' value. Calculate monthly statistics for years in year_group. Default is FALSE. See Details for more information.
calc_WSCVD: 'boolean' value. Calculate winter-spring center volume date for years in year_group. Default is FALSE. See Details for more information.
longitude: 'numeric' value. Site longitude in North American Datum of 1983 (NAD83), required in WSCVD calculation. Default is NA. See Details for more information.
calc_ICVD: 'boolean' value. Calculate inverse center volume date for years in year_group. Default is FALSE. See Details for more information.
zero_threshold: 'numeric' value as percentage. The percentage of years of a statistic that need to be zero in order for it to be deemed a zero flow site for that statistic. For use in trend calculation. See Details on attributes. Default is 33 (33 percent) of the annual statistic values.
quantile_type: 'numeric' value. The distribution type used in the stats::quantile function. Default is 8 (median-unbiased regardless of distribution). Other types common in hydrology are 6 (Weibull) or 9 (unbiased for normal distributions).
na.action: 'character' string indicating na.action passed to stats::aggregate na.action parameter. Default is "na.omit", which removes NA values before aggregating statistics, or "na.pass", which will pass NA values and return NA in the grouped calculation if any NA values are present.

Details

year_group is commonly water year, climate year, or calendar year.

Default annual statistics returned:

annual_mean: annual mean in year_group
annual_sd: annual standard deviation in year_group
annual_sum: annual sum in year_group

If calc_high/low are selected, annual statistics returned:
1-, 3-, 7-, and 30-day high/low and Julian date (jd) of n-day high/low.

high_qn: where n = 1, 3, 7, and 30
high_qn_jd: where n = 1, 3, 7, and 30
low_qn: where n = 1, 3, 7, and 30
low_qn_jd: where n = 1, 3, 7, and 30

If calc_percentiles is selected, annual statistics returned:
1, 5, 10, 25, 50, 75, 90, 95, 99 percentile based on daily streamflow.

annual_n_percentile: where n = 1, 5, 10, 25, 50, 75, 90, 95, and 99

If calc_monthly is selected, annual statistics returned:
Monthly mean, standard deviation, max, min, percent of annual for each month in year_group.

month_mean: monthly mean, where month = month.abb
month_sd: monthly standard deviation, where month = month.abb
month_max: monthly maximum, where month = month.abb
month_min: monthly minimum, where month = month.abb
month_percent_annual: monthly percent of annual, where month = month.abb

If calc_WSCVD is selected, Julian date of annual winter-spring center volume date is returned.
Longitude (in NAD83 datum) is used to determine the ending month of spring. July for longitudes West of \(-\)95 degrees, May for longitudes east of \(-\)95 degrees. See References Dudley and others, 2017. Commonly calculated when year_group is water year.

WSCVD: Julian date of winter-spring center volume

If calc_ICVD is selected, Julian date of annual inverse center volume date is returned.
Commonly calculated when year_group is climate year.

ICVD: Julian date of inverse center volume date

Attribute: zero_flow_years
A data.frame with each annual statistic calculated, the percentage of years where the statistic = 0, a flag indicating if the percentage is over the zero_threshold parameter, and the number of years with a zero value. Columns in zero_flow_years:

annual_stat: annual statistic
percent_zeros: percentage of years with 0 statistic value
over_threshold: boolean if percentage is over threshold
number_years: number of years with 0 value statistic

The zero_flow_years attribute can be useful in trend calculation, where a trend may not be appropriate to calculate with many zero flow years.

References

Dudley, R.W., Hodgkins, G.A, McHale, M.R., Kolian, M.J., Renard, B., 2017, Trends in snowmelt-related streamflow timing in the conterminous United States: Journal of Hydrology, v. 547, p. 208-221. [Also available at https://doi.org/10.1016/j.jhydrol.2017.01.051.]

Examples

Run this code

calc_annual_flow_stats(data = example_preproc, Date = "Date", year_group = "WY", Q = "value")

Run the code above in your browser using DataLab