--- title: "Introduction to ldc" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Introduction to ldc} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} bibliography: references.bib --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ```{r setup} library(ldc) ``` The goal of ldc is to provide functions for quickly creating pollutant load duration curves (LDCs). LDCs are an extension of flow duration curves (FDCs). The FDC is essentially a cumulative distribution plot with observed streamflow values on the y-axis, and the proportion of values that exceed a given flow value on the x-axis. Specifically, the FDC displays the exceedance probability $p$ on the x-axis and the associated discharge ($Q$) on the y-axis [@vogel_flowduration_1994]. Typically, mean daily discharge is used to calculate the flow exceedance values. Using this approach, flows can be categorized into flow duration intervals such as "Flood Flows," "High Flows," "Moderate Flows," and "Low Flows." The LDC is developed by multiplying allowable pollutant concentrations by the daily streamflow volume to identify allowable pollutant loads across flow duration intervals. Measured pollutant concentrations can be added to the duration curve by multiplying the concentrations and streamflow volume to derive an instantaneous load at a given exceedance percentile. By overlaying measured values over the LDC line, we can develop some inference for what conditions pollutant concentrations and loads exceed allowable concentrations. @cleland_tmdl_2003 and @morrison_development_2008 provide additional information for LDC development and use in pollutant loading assessments. # Input Data ldc requires a dataframe with at least two columns, discharge ($Q$) and measured pollutant concentrations ($C$). It is assumed, $Q$ is mean daily discharge, any units can be used (cfs, cms, etc.) $C$ can be any measured pollutant concentration associated with the value of $Q$ on the same row. The package includes a dataset, `tres_palacios`, that demonstrates how this is formatted. ```{r importdata} ## load required packages library(dplyr) ## load example data df <- as_tibble(tres_palacios) %>% ## filter this to the last 6 years of data filter(Date >= as.Date("2014-01-01")) ## show the data filtered to paired Q and C observations df %>% filter(!is.na(Indicator_Bacteria)) ``` ldc also utilizes the [units](https://cran.r-project.org/package=units) package to handle unit conversions. Therefore, $Q$ and $C$ will need to be formatted as units objects before using any ldc functions. In the example below, we need to create a new unit, "cfu", for the Indicator_Bacteria variable and change both Flow and Indicator_Bacteria to unit objects. ```{r formatdata} ## load required packages library(units) ## make the cfu unit install_unit("cfu") ## change Q and C to unit objects with appropriate units df <- df %>% mutate(Flow = set_units(Flow, "ft^3/s"), Indicator_Bacteria = set_units(Indicator_Bacteria, "cfu/100mL")) df ``` Now the dataframe is formatted for use in ldc functions. You can see the unit objects include the appropriate units when printed. # Functions ldc is composed of three major functions: - **`calc_ldc()`** takes an input dataset of matched flow and pollutant concentrations to generate a dataframe with exceedance probabilities for allowable pollutant loads (the LDC), measured pollutant concentrations converted to loads, alongside user specified flow duration intervals. - **`summ_ldc()`** uses the output from `calc_ldc()` to generate a summary dataframe grouped by flow duration intervals. - **`draw_ldc()`** uses the output from both functions to generate an LDC figure as a ggplot object. **`calc_ldc`** The `calc_ldc()` function is the first function to run. It has six arguments: - .tbl is the dataframe formatted as described above. - Q is the variable name in .tbl for discharge or flow. - C is the variable name for measured pollutant concentration. - allowable_concentration is an object of class units specifying the allowable pollutant concentration (water quality standard). This must have the same units as C. - breaks is a numeric vector from (1 -> 0) that indicates the break points for flow duration intervals. The length of the vector should be 1 more than the number of flow duration intervals. For example, `c(1, 0.9, 0.6, 0.4, 0.1, 0)` has 6 breaks and 5 flow duration intervals. - labels is a vector with the names for each flow duration interval. For example, `c("Highest flows", "High Flows", "Moderate Flows", "Dry Conditions", "Lowest Flows")`. ```{r calcldc} ## set the allowable concentration allowable_concentration <- 126 units(allowable_concentration) <- "cfu/100mL" ## calculate the ldc df_ldc <- calc_ldc(df, Q = Flow, C = Indicator_Bacteria, allowable_concentration = allowable_concentration, breaks = c(1, 0.9, 0.6, 0.4, 0.1, 0), labels = c("Highest flows", "High Flows", "Moderate Flows", "Dry Conditions", "Lowest Flows")) ## show the result df_ldc %>% filter(!is.na(Indicator_Bacteria)) ``` **`summ_ldc`** The `summ_ldc()` function is the second function to run. It has six arguments: - .tbl is a dataframe, preferably the output from `calc_ldc()` or formatted exactly like it. - Q is the variable name in .tbl for discharge or flow. - C is the variable name in .tbl for measured pollutant concentration. - Exceedance is the variable name in .tbl for flow exceedance probabilities. This defaults to the output created by `calc_ldc()` so in most cases you can leave it alone. - groups is the variable name in .tbl with the flow interval names. This defaults to the output created by `calc_ldc()` so in most cases you can leave it alone. - method is a string describing the method desired for summarizing pollutant concentration. It can be one of `"geomean"`, `"mean"`, or `"median"`. ```{r calcsumm} df_sum <- summ_ldc(df_ldc, Q = Flow, C = Indicator_Bacteria, Exceedance = P_Exceedance, groups = Flow_Category, method = "geomean") df_sum ``` **`draw_ldc`** The final function is `draw_ldc()` which uses the output from the previous two functions to generate a plot as a ggplot object. There are many arguments in this function, I won't describe them all but details are available using `?draw_ldc`. Importantly, since the output is a ggplot object, the output can be modified using many of the available ggplot functions. ```{r draw} library(ggplot2) p1 <- draw_ldc(df_ldc, df_sum, y_lab = expression(paste(italic("E. coli"))), ldc_legend_name = "LDC at 35cfu/100mL", measurement_name = "Measured Values", summary_name = "Summarized Loads (Geometric Mean)", label_nudge_y = log10(1000)) + scale_y_log10() + annotation_logticks(sides = "l") + theme_bw() + theme(legend.title = element_blank(), legend.direction = "vertical", legend.position = "bottom") p1 ``` # References