---
title: "Dissolved Oxygen"
csl: stylefile.csl
bibliography: refs.bib
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Dissolved Oxygen}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE, message = F, warning = F}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", message = F, warning = F, fig.align = 'center')

library(peptools)
library(ggplot2)

data(dodat)
maxyr <- max(lubridate::year(dodat$DateTime))

mptyps <- c("CartoDB.Positron", "CartoDB.DarkMatter", "OpenStreetMap", "Esri.WorldImagery", "OpenTopoMap")
```

This vignette describes summarizing and reporting dissolved oxygen (DO) data for the Peconic Estuary.  Three continuous USGS monitoring stations collect DO data at locations in the Peconic Estuary: USGS stations 01304562 in the Peconic River, 01304200 in Orient Harbor, and 01304650 in Shelter Island Sound.  Data at these stations can be downloaded using the `read_pepdo()` function.  

```{r, eval = F}
exdat <- read_pepdo(site = c('01304562', '01304200', '01304650'), 
                    nms = c('Peconic River', 'Orient Harbor', 'Shelter Island'), 
                    startDate = '2020-06-01', endDate = '2020-06-30')
```

The `dodat` data object included with the package provides DO data from 2013 to `r maxyr` at the three sites.  This takes several minutes to download using the `read_pepdo()` function, so it is included with the package for ease of use.

```{r}
head(dodat)
```

A plot of the raw data: 

```{r, fig.height = 12, fig.width = 8}
ggplot(dodat, aes(x = DateTime, y = do_mgl)) + 
  geom_point(size = 0.7) + 
  geom_hline(yintercept = 4.8, linetype = 'dashed', colour = 'red') + 
  geom_hline(yintercept = 3, linetype = 'dashed', colour = 'red') +
  facet_wrap(~site, ncol = 1) +
  theme_minimal() + 
  labs(
    y = 'Dissolved oxygen (mg/L)', 
    x = NULL, 
    title = 'Dissolved oxygen at Orient Harbor, Peconic River, and Shelter Island', 
    subtitle = 'Dashed lines are chronic and acute threhsolds (4.8, 3 mg/L)'
  )
```

Dissolved oxygen data typically show daily and seasonal variation.  Summaries of condition should account for variation at both temporal scales. Further, the impact of low dissolved oxygen concentrations on biota can vary depending on both magnitude and duration of hypoxia/anoxia.  As such, condition assessment should consider how often concentrations fall below a threshold and for how long. The assessments below speak to each of these needs. 

First, the data can be summarized from the continuous (~6 minute observations) to daily averages using the `anlz_dodlpep()` function.  A user-specified threshold can be supplied to the `thr` argument to summarize the data relative to a value of interest, the default value being the acute threshold of 3 mg/L (an alternative may be the chronic threshold of 4.8 mg/L, @USEPA00).

```{r}
# 3 mg/l is acute, 4.8 mg/l is chronic
dlysum <- anlz_dodlypep(dodat, thr = 3)
dlysum
```

The last three columns show the daily summarized data.  The `do_mgl` column shows the average DO concentration for each day, the `below` column shows a 1 (yes) or 0 (no) if the concentration was below the threshold value at any point during a day, and the `below_cumsum` column shows a cumulative tally of the number of days in each month at which dissolved oxygen fell below the threshold at any point during a day.  By default, the `anlz_dodlypep()` function will impute missing daily dissolved oxygen values to the average for the year, month, site combination.  This is often necessary to create summary values that make sense. For example, if a month has incomplete data, the maximum `below_cumsum` value will not show 30 or 31 days even if every day in the observed record is below the threshold. 

The data can also be summarized by month using the `anlz_domopep()` function.  Summarizing by month distills the information into a simple format for plotting.  Internally, the `anlz_domopep()` function uses the `anlz_dodlypep()` function to first summarize results by day, which are then summarized by month.

```{r}
mosum <- anlz_domopep(dodat, thr = 3)
mosum
```

The last three columns show the monthly summarized data, where `do_mgl` is the average of all daily DO averages across the month, `below_ave` is the proportion of days in a month when concentrations in a given day fell below the threshold (1 would mean all days had an instance of DO below the threshold, 0 would mean none), and `below_maxrun` is the maximum number of sequential days in a month when concentrations in a given day fell below the threshold (30 or 31, depending on month, would indicate all days in a month had an instance of DO below the threshold). 

The `below_ave` and `below_maxrun` columns summarize the DO data differently depending on how hypoxia/anoxia conditions can be described relative to potential impacts on biological resources. The `below_ave` column summarizes undersaturation relative to only the number of times hypoxia conditions occurred, whereas the `below_maxrun` column summarizes undersaturation relative to both the number of instances and duration of hypoxia.  In other words, biota may be stressed differently depending on the number of times hypoxia occurs vs how long it may persist. The two measures may indicate similar information, but not always depending on characteristics of the DO time series.    

The summarized monthly data for a station can be plotted with the `show_domatrix()` function. In this example, the default plot shows the proportion of days in a month when concentrations in a given day fell below a threshold of 3 mg/L for the Peconic River station. 

```{r, fig.height = 6, fig.width = 8}
show_domatrix(dodat, site = 'Peconic River', thr = 3, show = 'below_ave')
```

The maximum number of sequential days in a month when concentrations in a given day fell below the threshold can also be plotted by changing the `show` argument. 

```{r, fig.height = 6, fig.width = 8}
show_domatrix(dodat, site = 'Peconic River', thr = 3, show = 'below_maxrun')
```

The threshold can also be changed.  For example, the chronic threshold of 4.8 mg/L shows conditions relative to a more conservative threshold. 

```{r, fig.height = 6, fig.width = 8}
show_domatrix(dodat, site = 'Peconic River', thr = 4.8, show = 'below_ave')
```

Plotting the results provides insights into hypoxia patterns at the site depending on how under-saturated conditions were summarized.  Additional considerations may include:

1) Relevance of a threshold to biological indicator 
1) Spatial extent of the indicators
1) Breakpoints for management decisions