---
title: "Tidal Creek Assessment"
csl: stylefile.csl
bibliography: tidalrefs.bib
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Tidal Creek Assessment}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# libraries
library(tbeptools) 
library(bookdown)
library(dplyr)
library(knitr)
library(mapview)
library(plotly)
library(sf)

sf_use_s2(FALSE)
sf::st_crs(tidalcreeks) <- 4326

# spelling::spell_check_files("vignettes/tidalcreeks.Rmd")
```

## Background

Dashboard: https://shiny.tbep.org/tidalcreek-dash/

Tidal creeks (aka tributaries) are essential habitats in the Tampa Bay Estuary and serve as important focal points for understanding watershed inputs that affect water quality. A fundamental goal of the Tampa Bay Estuary Program is to develop effective nutrient management strategies to support the ecological function of tidal creeks. In partnership with Sarasota Bay NEP, Coastal & Heartland NEP, and local government and agency stakeholders, an open science framework has been developed for assessing the tidal creek condition based on a host of commonly collected water quality data [@tbep0216;@tbep0220;@tbep1121]. These assessments can support tracking of water quality management goals and can help refine restoration and management plans in priority tributaries, including those in need of hydrologic restoration that can support critical nursery habitats for sportfishes.

The tbeptools package includes a [simple features](https://r-spatial.github.io/sf/articles/sf1.html) spatial data object of the population of tidal creeks in southwest Florida, called `tidalcreeks()`. This includes `r nrow(tidalcreeks)` polyline features designated by a water body ID (`WBID`), creek id (`JEI`), and [FDEP class](https://floridadep.gov/dear/water-quality-standards/content/surface-water-quality-standards-classes-uses-criteria) (`class`, 1 for potable water, 2 for shellfish harvesting or propagation, and 3F/3M for freshwater/marine fish consumption, recreation, propagation and maintenance of a healthy, well-balanced population of fish and wildlife).

```{r, eval = T, cache = F}
mapview(tidalcreeks, homebutton = F, legend = F)
```

The tidal creek assessment framework was established based on data from the FDEP [Impaired Waters Rule](https://www.flrules.org/gateway/ChapterHome.asp?Chapter=62-303) database run 56 available [here](http://publicfiles.dep.state.fl.us/DEAR/IWR/) which includes data collected through January 10th 2019. However, the this framework intends to link to future IWR databases to refresh the site with new data as it becomes available.  Raw and updated data from the IWR database required for assessment is provided in the tbeptools package in the `iwrraw()` data object.  

## Assessment

The tidal creek assessment framework includes both a "report card" and "indicators" assessment which are provided as separate tabs in the dashboard. The report card provides an assessment of total nitrogen concentrations (the limiting nutrient in these creeks) based on annual geometric average concentrations relative to standards developed for contributing freshwater streams. The indicators are based a several water quality metrics derived as outcomes of our study to describe tidal creek condition and provide insights into site specific attributes of these creeks that may govern overall creek health.

# Report card

The report card is similar to the TBEP [water quality report card](https://shiny.tbep.org/wq-dash/) in that tidal creeks are assigned to categories within an assessment framework intended to serve as both a mechanism for evaluating data relative to the need for management action, and to identify stewardship goals that, if properly pursued, may preclude the need for any regulatory actions. These categories were established based principally on fish as a biological response indicator. Tidal creeks are assigned to one of five categories:

<span style="color:#ADD8E6">__No Data__</span>: Data are unavailable for evaluation.

<span style="color:#2DC938">__Monitor__</span>: Creek is at or below nitrogen concentrations that protect individual creek types within the larger population of creeks.

<span style="color:#E9C318">__Caution__</span>: Creek nutrients showing signs of elevated nutrient concentrations that may increase risk of eutrophic condition.

<span style="color:#EE7600">__Investigate__</span>: Creek nutrient concentrations above margin of safety to protect creek from potential impairment.

<span style="color:#FF4040">__Prioritize__</span>: Creek nutrient concentrations have exceeded regulatory standard for associated freshwater portion of tributary indicating that actions are needed to identify remediative measures to reduce nutrients to the creek.

Conceptually, these thresholds appear in the figure below.

```{r, echo = F, fig.cap = 'Scoring rubrik for tidal creeks based on nitrogen thresholds.', out.width = '80%'}
knitr::include_graphics('tidalcreekreport.PNG')
```

The Prioritize category was defined based on Florida's freshwater stream numeric nutrient criteria (NNC).Two different freshwater stream NNC are applicable to our region; the West Central NNC of 1.65 mg/l and  Peninsular region NNC of 1.54 mg/l. The histograms in the above figure represent a range of annual geometric mean (AGM) nitrogen concentrations associated with the Prioritize and Investigate categories which are based on the NNC. In the example above, the maximum expected distribution of AGMs not to exceed of 1.65 mg/l with a 1:3 exceedence probability (as defined in F.A.C. 62-303) was generated using monte carlo simulation and the highest observed standard deviation from data collected during the first creeks study. The Investigate category was then defined as an explicit margin of safety by adjusting the distribution to find the grand geometric average that would result in a 1:20 chance of exceeding 1.65 mg/l. Assignment of a creek into the Caution category depended on a creek length adjustment as described below to protect smaller creeks from elevated nutrient concentrations. 

The `tidaltargets()` data object included in tbeptools includes these thresholds.  Note that the "Caution" category is a function of creek length. 

```{r}
tidaltargets
```

A scoring algorithm was derived to define the final report card outcome for each creek using the entire ten year record of available data based on the following criteria. A single exceedance of the Prioritize and Investigate categories in any year of the ten year record would result in a classification of that creek into the respective category unless at least three other years of data were below the threshold level for that category. Creeks were assigned the next lower category if only one AGM for TN was above a given level while multiple other years (i.e., more than two) were below the given levels defining the cutoff points for each category. For example, a creek with at least 4 years of data and only a single exceedance of the Prioritize threshold would be assigned the Investigate category. Outcomes are exemplified below.

## Report card functions

The two primary functions for the tidal creek assessments are `anlz_tdlcrk()` to obtain the scores and `show_tdlcrk()` to view an interactive map of the results.  The `anlz_tdlcrk()` function uses the included `tidalcreeks()` and `iwrraw()` datasets to estimate the scores: 

```{r}
results <- anlz_tdlcrk(tidalcreeks, iwrraw)
results
```

The results include a unique creek identifier (`id`, based on the `wbid` and `JEI` fields), the waterbody id (`wbid`), the creek ID (`JEI`), the FDEP class (`class`), and results from the assessment in the remaining columns.  The columns `monitor`, `caution`, `investigate`, and `prioritize` indicate the number of years from 2012 to 2021 that the nitrogen values were within the ranges appropriate for the creek type as specified within `tidaltargets()`.  The `score` column indicates the overall category assigned to the creek for the period of record.  Note that many creeks are assigned a `No Data` value if sufficient data were unavailable.  A summation of the four component columns (`monitor`, `caution`, `investigate`, and `prioritize`) provides the number of years for which data were available at a creek. 

The `show_tdlcrk()` function can be used with the output of `anlz_tdlcrk()` to view an interactive map of the results. Creeks are color-coded by the exceedance categories, with "No Data" creeks shown in light blue.  

```{r, eval = T, cache = F}
show_tdlcrk(results)
```

A report card style matrix can be plotted using the `show_tdlcrkmatrix()` function that shows the overall creek score and the number of years of data that were used to estimate the overall score. The plot shows a matrix with rows for individual creeks and columns for overall creek score.  The columns show an overall creek score and the number of years in the prior ten years that nitrogen values at a creek were assigned to each of the four score categories.  Number of years is mapped to cell transparency.  By default, the plot shows creeks with a marine WBID (water body identifier) designation as `3M` or `2`.  This can be changed with the `class` argument (i.e., `class c('3M', '2', '3F', '1')` for marine and freshwater WBIDs). 

```{r, fig.height = 10, fig.width = 6}
show_tdlcrkmatrix(results)
```

## Indicator functions

Water quality Indicators were developed to provide context for interpreting the report card outcomes as described in detail in Wessel et al. 2021 and include thresholds for total nitrogen (>1.1 mg/l), chlorophyll a (>11 ug/l), dissolved oxygen (< 42 % saturation), a trophic state index score (>55), the chlorophyll/nitrogen ratio (>15) and a ratio of the nitrates in the tidal and freshwater portion of the creek (>1) (if data are available).  The results for each indicator relative to the established thresholds are calculated on an annual basis and then synthesized for the 10 year period by calculating the percentage of annual outcomes exceeding the identified threshold indicator values out of the total number of years with available data. An integrative summary for all indicators is presented using a standardized polar coordinate system and Radar Charts to provide a single multi-metric summary plot of the results across indicators.  

The `anlz_tdlcrkindic()` function generates these annual outcomes for each `wbid`/`JEI` combination.

```{r}
results <- anlz_tdlcrkindic(tidalcreeks, iwrraw)
head(results)
```

Individual creek indicators are summarized using a multivariate response plot called a "radar plot" that indicates the percentage of years where each indicator exceeded its respective threshold value. These plots are created by using the `radar = TRUE` argument with `anlz_tdlcrkindic()` function and then using those results with the `show_tdlcrkradar()` function. The radar plots only apply to the marine WBIDs of the tidal creeks (Florida DEP class 2, 3M). Indicators without data for the creek do not have a point on the plot.

```{r, fig.width = 5, fig.height = 5}
cntdat <- anlz_tdlcrkindic(tidalcreeks, iwrraw, yr = 2023, radar = T)

# get random creek id
set.seed(123)
id <- sample(unique(cntdat$id), 1)
show_tdlcrkradar(id = id, cntdat = cntdat)
```

General descriptive plots of the annual outcomes are provided with interactive [plotly](https://plot.ly/r/) graphics using the `show_tdlcrkindic()` and `show_tdlcrkindiccdf()` functions. 

The `show_tdlcrindic()` function produces bar plots of annual outcomes at the selected creek. The creek to plot is selected with the `id` argument as an integer that is used to filter results from the `anlz_tdlcrkindic()` function, where the latter is passed to the `cntdat` argument.  The `thrsel` argument plots dotted red lines based on the threshold values.  Each year has its own unique color.  

```{r}
cntdat <- anlz_tdlcrkindic(tidalcreeks, iwrraw, yr = 2023)
show_tdlcrkindic(id = id, cntdat = cntdat, thrsel = TRUE)
```

The `show_tdlcrkindiccdf()` function is similar except that empirical cumulative distribution functions (CDF) are plotted to evaluate outcomes for a specific creek relative to the entire distribution of creeks in southwest Florida. Each indicator and each year for the selected creek are plotted on the CDF curves.  Location of the points indicate both a comparison to the population and the trajectory of indicators over time (i.e., brown are older observations and blue are more recent).  Holding the mouse cursor over a point shows the year and holding the cursor over the line shows the percentile value from the CDF. 

```{r}
show_tdlcrkindiccdf(id = id, cntdat = cntdat, thrsel = TRUE)
```


# References