calc_annual_flow_stats {HyMETT}

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")
)

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.

Value

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

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.]

See Also

preproc_precondition_data

Examples

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