Package 'adc' reference manual

Title:	Calculate Antecedent Discharge Conditions
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>.
Authors:	Michael Schramm [aut, cre, cph] , Nick Bond [ctb] (Author of the hydrostats::baseflow function)
Maintainer:	Michael Schramm <[email protected]>
License:	GPL (>= 3)
Version:	1.0.0.9000
Built:	2024-09-30 04:35:09 UTC
Source:	https://github.com/TxWRI/adc

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)
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 [email protected] 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)

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

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

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

Smooth Discounted Flow

Description

Applies exponential smoothing to discharge data.

Usage

sdf(discharge, delta = 0.95)
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 $i$ th 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)


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

Package 'adc'

Help Index

Baseflow Seperation

Description

Usage

Arguments

Details

Value

Note

Author(s)

References

Examples

Clean Flow Record

Description

Usage

Arguments

Value

Calculate Flow Anomalies

Description

Usage

Arguments

Details

Value

References

Examples

Daily streamflows from USGS gage at Lavaca River

Description

Usage

Format

Source

Approximate the Instantaneous Rate of Change

Description

Usage

Arguments

Value

Examples

Smooth Discounted Flow

Description

Usage

Arguments

Details

Value

References

Examples