Type: Package
Title: Calculate Antecedent Discharge Conditions
Version: 1.0.0
Maintainer: Michael Schramm <mpschramm@gmail.com>
Description: Calculates some antecedent discharge conditions useful in water quality modeling. Includes methods for calculating flow anomalies, base flow, and smooth discounted flows from daily flow measurements. Antecedent discharge algorithms are described and reviewed in Zhang and Ball (2017) <doi:10.1016/j.jhydrol.2016.12.052>.
License: GPL (≥ 3)
URL: https://github.com/TxWRI/adc, https://txwri.github.io/adc/
BugReports: https://github.com/TxWRI/adc/issues
Depends: R (≥ 2.10)
Imports: runner, stats
Suggests: covr, testthat (≥ 3.0.0)
Config/Needs/website: TxWRI/twriTemplates
Config/testthat/edition: 3
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.2.2
NeedsCompilation: no
Packaged: 2023-02-16 19:27:34 UTC; michael.schramm
Author: Michael Schramm ORCID iD [aut, cre, cph], Nick Bond [ctb] (Author of the hydrostats::baseflow function)
Repository: CRAN
Date/Publication: 2023-02-17 10:10:02 UTC

Baseflow Seperation

Description

Implements the Lyne and Hollick filter for baseflow seperation. This function utilizes the approach in Ladson et al. (2013).

Usage

bf_sep_lh(discharge, a = 0.98, n = 3, reflect = 30)

Arguments

discharge

numeric vector of daily discharge values

a

alpha, numeric values between [0-1].

n

number of passes for the filter. Must be a numeric value, defaults to 3.

reflect

the number of values to reflect at the start and end of discharge to reduce "warm-up" and "cool-down" issues with the recursive filter. Must be less than or equal to the length of discharge. For long discharge records this value does not matter much, for short records the reflection should approach the length of discharge. The default is 30 as implemented in Ladson et al. (2013).

Details

This function implements the Lyne-Hollick filter (Lyne and Hollick, 1979) using the approach detailed in Ladson et al. (2013). The filter is:

Y_{k} = \alpha \times Y_{k-1} + \frac{1+\alpha}{2} \times (Q_k - Q_{k-1}),

where Y_k is the filtered quick response at the k^{th} sample. Q_k if the original streamflow and \alpha is the filter parameter between [0-1].

Ladson et al. (2013) suggest a standardized approach for applying the filter by: (1) reflecting streamflow at the start and end of the series to address warm-up and cool-down; (2) specify the initial value of each pass as the measured flow; and (3) using three passes for the filter (forward, backward, forward); Ladson et al. (2013) also provide additional suggestions for handling missing values and appropriate alpha parameter values that are not covered here.

Value

vector of numeric values representing estimated baseflow.

Note

This function an updated and modified version of the baseflows() function in the hydrostats package by Nick Bond. The hydrostats version returns additional summary measures and utilizes different starting values. Outputs between the two packages will slightly vary.

Author(s)

Nick Bond n.bond@latrobe.edu.au modified by Michael Schramm

References

Lyne, V., & Hollick, M. (1979, September). Stochastic time-variable rainfall-runoff modelling. In Institute of Engineers Australia National Conference (Vol. 79, No. 10, pp. 89-93). Barton, Australia: Institute of Engineers Australia.

Ladson, A. R., Brown, R., Neal, B., & Nathan, R. (2013). A standard approach to baseflow separation using the Lyne and Hollick filter. Australian Journal of Water Resources, 17(1), 25-34, doi:10.7158/W12-028.2013.17.1.

Examples


bf <- bf_sep_lh(lavaca$Flow, a = 0.975)
head(bf)

Clean Flow Record

Description

Function to replace zeros in the flow record with specified value and replace negative discharge values with NA.

Usage

clean_flows(discharge, replace_0 = 0.001, replace_neg = NA)

Arguments

discharge

numeric vector of discharges.

replace_0

numeric value or NA to replace zeros with. Defaults to 0.001.

replace_neg

numeric value or NA to replace negative values with. Defaults to NA.

Value

numerioc vector same length as values provided in discharge.

Calculate Flow Anomalies

Description

Flow anomalies are a dimensionless term that reflects the difference in in current discharges compared to past discharges. A positive flow anomaly indicates the current time period, T_{1}, is wetter than the precedent time period, T_{2}.

Usage

fa(discharge, dates, T_1, T_2, clean_up = FALSE, transform = "log10")

Arguments

discharge

numeric vector of daily discharges

dates

vector of dates coresponding to daily discharge measurements. Must be class "Date".

T_1

size of period T_{1} preceding a given day t. Specified in the same way as the by argument in seq.POSIXt.

T_2

size of period T_{2} preceding a given day t. Specified in the same way as the by argument in seq.POSIXt. Period T_2 is expected to be longer than T_1.

clean_up

logical. runs .... prior to ....

transform

on of NA, log, log10,

Details

The FA term describes how different the antecedent discharge conditions are for a selected temporal period compared to a selected period or day of analysis. Ryberg and Vecchia (2014) and Vechia et al. (2009) describe the flow anomaly (FA) term as:

FA(t)=X_{T_1}(t) - X_{T_2}(t)

The T_1 and T_2 arguments can be specified as character strings containing one of "sec", "min", "hour", "day", "DSTday", "week", "month", "quarter", or "year". This is generally preceded by an integer and a space. Can also be followed by an "s". Additionally, T_2 accepts "period" which coresponds with the mean of the entire flow record.

Value

vector of numeric values corresponding to X_{T_1}(t) - X_{T_2}(t).

References

Ryberg, Karen R., and Aldo V. Vecchia. 2012. “WaterData—An R Package for Retrieval, Analysis, and Anomaly Calculation of Daily Hydrologic Time Series Data.” Open Filer Report 2012-1168. National Water-Quality Assessment Program. Reston, VA: USGS. https://pubs.usgs.gov/of/2012/1168/.

Vecchia, Aldo V., Robert J. Gilliom, Daniel J. Sullivan, David L. Lorenz, and Jeffrey D. Martin. 2009. “Trends in Concentrations and Use of Agricultural Herbicides for Corn Belt Rivers, 1996-2006.” Environmental Science & Technology 43 (24): 9096–9102. doi:10.1021/es902122j.

Examples

 ## examples from Ryberg & Vechia 2012
 ## Long-term Flow Anomaly LTFA
 LTFA <- fa(lavaca$Flow,
            dates = lavaca$Date,
            T_1 = "1 year",
            T_2 = "period",
            clean_up = TRUE,
            transform = "log10")

 

 ## Mid-term Flow Anomaly MTFA
 MTFA <- fa(lavaca$Flow,
            dates = lavaca$Date,
            T_1 = "1 month",
            T_2 = "1 year",
            clean_up = TRUE,
            transform = "log10")

 ## Short-term Flow Anomaly STFA
 STFA <- fa(lavaca$Flow,
            dates = lavaca$Date,
            T_1 = "1 day",
            T_2 = "1 month",
            clean_up = TRUE,
            transform = "log10")

Daily streamflows from USGS gage at Lavaca River

Description

A dataset containing dates and mean daily streamflows from USGS gage 08164000, Lavaca River in Texas.

Usage

lavaca

Format

A data frame with 9132 rows and 5 variables:

agency_cd

agency code, character

site_no

site number, character

Date

date, Date format

Flow

mean daily stream flow, numeric

Flow_cd

tag indicate data quality, character

...

Source

https://waterdata.usgs.gov/nwis/dv/?site_no=08164000&agency_cd=USGS

Lyne and Hollick Equation

Description

Filter equation.

Usage

lyne_hollick(Q, a)

Arguments

Q

numeric vector of discharge values

a

alpha value between [0-1]

Value

vector of estimated baseflow values

Approximate the Instantaneous Rate of Change

Description

Estimate the rate of change or first derivative of the raw mean daily streamflow or the smoothed cubic spline fit between time and mean daily streamflow.

Usage

rate_of_change(discharge, dates, smooth = TRUE)

Arguments

discharge

numeric vector of mean daily discharges

dates

vector of dates corresponding to daily discharge measurements. Must be class "Date".

smooth

logical indicating if the first derivative is calculated using a cubic smoothing spline function. Defaults is TRUE.

Value

Numeric vector with the estimated streamflow rate of change.

Examples

## calculate the first deriv of the smoothed function between Date and streamflow
rate <- rate_of_change(lavaca$Flow, lavaca$Date)
head(rate)

## Return the first deriv on raw measurements
rate2 <- rate_of_change(lavaca$Flow, lavaca$Date, smooth = FALSE)
head(rate2)

Iterate Lyne-Hollick Filter

Description

Simply iterates n runs of the Lyne-Hollick filter.

Usage

run_filter(Q, a, n)

Arguments

Q

vector of discharge values

a

alpha parameter

n

number of times to itterate filter.

Value

numeric vector

Smooth Discounted Flow

Description

Applies exponential smoothing to discharge data.

Usage

sdf(discharge, delta = 0.95)

Arguments

discharge

vector of discharge data (numeric).

delta

the discount factor which can be any value between (0,1), defaults to 0.95. As delta approaches one, the average discounted flow approaches mean flow. Small values of delta return values closer to the current daily flow.

Details

The smooth discounted flow (SDF) was proposed by Kuhnert et al. (2012). The premise of SDF is to incorporate the influence of historical flows on flux:

SDF(\delta) = d\kappa_{i-1} + (1-\delta)\hat{q}_{i-1},

and

\kappa_{i} = \sum_{m=1}^{i}\hat{q}_m,

for discount factor \delta, where \kappa_{i} represents cumulative flow up to the ith day.

Value

vector of values the same length as discharge.

References

Kuhnert, Petra M., Brent L. Henderson, Stephen E. Lewis, Zoe T. Bainbridge, Scott N. Wilkinson, and Jon E. Brodie. 2012. “Quantifying Total Suspended Sediment Export from the Burdekin River Catchment Using the Loads Regression Estimator Tool” Water Resources Research 48 (4). doi:10.1029/2011WR011080.

Examples

# Standard use case
ma <- sdf(lavaca$Flow, delta=0.95)
head(ma)