---
title: "Tampa Bay Benthic Index"
csl: stylefile.csl
bibliography: tbbirefs.bib
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Tampa Bay Benthic Index}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# libraries
library(tbeptools)
library(bookdown)
library(patchwork)
library(dplyr)
library(knitr)
library(mapview)
library(ggplot2)
library(sf)
library(tibble)

sf_use_s2(FALSE)
# spelling::spell_check_files("vignettes/tbbi.Rmd")
```

## Background

The Tampa Bay Benthic Index (TBBI) [@tbep0620;@tbep0106]) is an assessment method that quantifies the ecological health of the benthic community in Tampa Bay.  The index provides a complementary approach to evaluating environmental condition that is supported by other assessment methods currently available for the region (e.g., water quality report card, nekton index, etc.). The tbeptools package includes several functions described below to import data required for the index and plot the results to view trends over time.  Each of the functions are described in detail below. 

The TBBI uses data from the Tampa Bay Benthic Monitoring Program as part of the Environmental Protection Commission (EPC) of Hillsborough Country.  The data are updated annually on a public site maintained by EPC, typically in December after Summer/Fall sampling.  This is the same website that hosts water quality data used for the [water quality report card](https://tbep-tech.github.io/tbeptools/articles/intro.html).  The required data for the TBBI are more extensive than the water quality report card and the data are made available as a zipped folder of csv files, available [here](https://epcbocc.sharepoint.com/:f:/s/Share/EtOJfziTTa9FliL1oROb9OsBRZU-nO60fu_0NRC162hHjQ?e=4gUXgJ).  The process for downloading and working with the data are similar as for the other functions in tbeptools.

## Data import and included datasets

Data for calculating TBBI scores can be imported into the current R session using the `read_importbenthic()` function.  This function downloads the zipped folder of base tables used for the TBBI from the EPC site if the data have not already been downloaded to the location specified by the input arguments.  

To download the data with tbeptools, first create a character path for the location where you want to download the zipped files. If one does not exist, specify a location and name for the downloaded file. Here, we name the folder `benthic.zip` and download it on our desktop.

```{r, eval = F}
path <- '~/Desktop/benthic.zip'
benthicdata <- read_importbenthic(path)
```

Running the above code will return the following error: 

```{r, eval = F}
#> Error in read_importbenthic() : File at path does not exist, use download_latest = TRUE
```

We get an error message from the function indicating that the file is not found. This makes sense because the file does not exist yet, so we need to tell the function to download the latest file. This is done by changing the `download_latest` argument to `TRUE` (the default is `FALSE`).

```{r, eval = F}
benthicdata <- read_importbenthic(path, download_latest = T)
```
```{r, eval = F}
#> File ~/Desktop/benthic.zip does not exist, replacing with downloaded file...

#> trying URL 'https://epcbocc.sharepoint.com/:u:/s/Share/EQUCWBuwCNdGuMREYAyAD1gBKC98mYtCHMWX0FYLrbT4KA?e=nDfnnQ&download=1' length 37122877 bytes (35.4 MB)
```

Now we get an indication that the file on the server is being downloaded. When the download is complete, we’ll have the data downloaded and saved to the `benthicdata` object in the current R session.

If we try to run the function again after downloading the data, we get the following message. This check is done to make sure that the data are not unnecessarily downloaded if the current file matches the file on the server.

```{r, eval = F}
benthicdata <- read_importbenthic(path, download_latest = T)
```
```{r, eval = F}
#> File is current..
```

Every time that tbeptools is used to work with the benthic data, `read_importbenthic()` should be used to import the data. You will always receive the message `File is current...` if your local file matches the one on the server. However, data are periodically updated and posted on the server. If `download_latest = TRUE` and your local file is out of date, you will receive the following message:

```{r, eval = F}
#> Replacing local file with current...
```

## Calculating TBBI scores

After the data are imported, you can view them from the assigned object.  The data are provided as a nested tibble that includes three different datasets: station information, field sample data (salinity), and detailed taxa information.  

```{r}
benthicdata
```

The individual datasets can be viewed by extracting them from the parent object using the `deframe()` function from the tibble package. 

```{r}
# see all
deframe(benthicdata)

# get only station dat
deframe(benthicdata)[['stations']]
```

The `anlz_tbbiscr()` function uses the nested `benthicdata` to estimate the TBBI scores at each site. The TBBI scores typically range from 0 to 100 and are grouped into categories that describe the general condition of the benthic community.  Scores less than 73 are considered "degraded", scores between 73 and 87 are "intermediate", and scores greater than 87 are "healthy".  Locations that were sampled but no organisms were found are assigned a score of zero and a category of "empty sample".  The total abundance (`TotalAbundance`, organisms/m2), species richness (`SpeciesRichness`) and bottom salinity (`Salinity`, psu) are also provided.  Some metrics for the TBBI are corrected for salinity and bottom measurements taken at the time of sampling are required for accurate calculation of the TBBI.

```{r}
tbbiscr <- anlz_tbbiscr(benthicdata)
tbbiscr
```

## Plotting results

The TBBI scores can be viewed as annual averages for each bay segment using the `show_tbbimatrix()` function.  The `show_tbbimatrix()` plots the annual bay segment averages as categorical values in a conventional "stoplight" graphic. A baywide estimate is also returned, one based on all samples across all locations ("All") and another weighted by the relative surface areas of each bay segment ("All (wt)"). The input to `show_tbbimatrix()` function is the output from the `anlz_tbbiscr()` function.  

```{r, fig.height = 7, fig.width = 5}
show_tbbimatrix(tbbiscr)
```

The matrix can also be produced as a [plotly](https://plotly.com/r/) interactive plot by setting `plotly = TRUE` inside the function. 

```{r, fig.height = 7, fig.width = 5}
show_tbbimatrix(tbbiscr, plotly = T)
```

## Additional sediment data

In addition to biological data, sediment contaminant concentrations are measured at sites within Tampa Bay.  These include over 100 different constituents grouped broadly as metals, organics, physical, or other.  The concentrations of these constituents can be compared relative to Threshold Effects Levels (TEL) or Potential Effects Levels (PEL), when available, as relative indications of the likelihood that the concentrations will have toxic effects on invertebrates that inhabit the sediments. The functions in tbeptools can be used to retrieve the sediment data and provide an indication of the concentrations relative to the TEL or PEL thresholds. 

The `read_importsediment()` function will retrieve all sediment data for Tampa Bay collected annually by the Environmental Protection Commission of Hillsborough County.  The data are retrieved from the [same location](https://epcbocc.sharepoint.com/:f:/s/Share/EtOJfziTTa9FliL1oROb9OsBRZU-nO60fu_0NRC162hHjQ?e=4gUXgJ) as the biological data used to calculate the TBBI. 

```{r, eval = F}
path <- '~/Desktop/sediment.zip'
sedimentdata <- read_importsediment(path, download_latest = T)
```

After the data are imported, you can view them from the assigned object.

```{r}
sedimentdata
```

The `show_sedimentmap()` function can be used to create maps of selected parameters relative to TEL and PEL values. Green points show concentrations below the TEL, yellow points show concentrations between the TEL and PEL, and red points show concentrations above the PEL. The applicable TEL and PEL values for the parameter are indicated in the legend.  The selected stations are those that are sampled in the years within the `yrrng` argument.

```{r, out.width = '100%'}
show_sedimentmap(sedimentdata, param = 'Arsenic', yrrng = c(1993, 2022))
```

A single year of data can be shown as well.  

```{r, out.width = '100%'}
show_sedimentmap(sedimentdata, param = 'Arsenic', yrrng = 2022)
```

A map showing only the concentrations is returned if TEL and PEL values are not available for a parameter.

```{r, warning = FALSE, out.width = '100%'}
show_sedimentmap(sedimentdata, param = 'Selenium', yrrng = c(1993, 2022))
```

Maps for total contaminant values (e.g., Total DDT, Total PAH, Total PCB, Total LMW PAH, Total HMW PAH) can also be returned.  Although the totals are not included in the `sedimentdata` object, they are calculated by tbeptools using the `anlz_sedimentaddtot()` function. Simply entering the name of the total parameter in the `show_sedimentmap()` function will produce the summary map. 

```{r, out.width = '100%'}
show_sedimentmap(sedimentdata, param = 'Total DDT', yrrng = c(1993, 2022))
```

The PEL ratio can also be used to assess relative sediment quality given the measured contaminants.  The `show_sedimentpelmap()` function creates a map of average PEL ratios graded from A to F for benthic stations monitored in Tampa Bay. The PEL ratio is the contaminant concentration divided by the Potential Effects Levels (PEL) that applies to a contaminant, if available. Higher ratios and lower grades indicate sediment conditions that are likely unfavorable for invertebrates. The station average combines the PEL ratios across all contaminants measured at a station.

```{r, out.width = '100%'}
show_sedimentpelmap(sedimentdata, yrrng = c(1993, 2022))
```

The average PEL ratios and grades used to create the map can also be returned as a data frame using `anlz_sedimentpel()`.

```{r}
anlz_sedimentpel(sedimentdata, yrrng = c(1993, 2022))
```

Plots of bay segment averages of sediment concentrations for selected parameters can be created with `show_sedimentave()`.  The plot includes appropriate lines for the TEL and PEL values, as well the grand mean across all segments.  The former are omitted from the plot if unavailable for a selected parameter.

```{r, fig.height = 5, fig.width = 7}
show_sedimentave(sedimentdata, param = 'Arsenic', yrrng = c(1993, 2022))
```

The same plot can be returned as an interactive [plotly](https://plotly.com/r/) object using `plotly = T`.

```{r, fig.height = 5, fig.width = 7}
show_sedimentave(sedimentdata, param = 'Arsenic', yrrng = c(1993, 2022), plotly = T)
```

The values used in the plot can be returned with `anlz_sedimentave()`. 

```{r}
anlz_sedimentave(sedimentdata, param = 'Arsenic', yrrng = c(1993, 2022))
```

As before, the total contaminant values (e.g., Total DDT, Total PAH, Total PCB, Total LMW PAH, Total HMW PAH) can also be returned even though they are not included in the `sedimentdata` object. The `anlz_sedimentaddtot()` function is used to calculate the totals within `anlz_sedimentave()`.

```{r}
anlz_sedimentave(sedimentdata, param = 'Total DDT', yrrng = c(1993, 2022))
```

A similar plot of the bay segment averages for the average PEL ratios can be created with `show_sedimentpelave()`.  The colors indicate the grades for A (green) to F (red).

```{r, fig.height = 5, fig.width = 7}
show_sedimentpelave(sedimentdata, yrrng = c(1993, 2022))
```

The same plot can be returned as an interactive [plotly](https://plotly.com/r/) object using `plotly = T`.

```{r, fig.height = 5, fig.width = 7}
show_sedimentpelave(sedimentdata, yrrng = c(1993, 2022), plotly = T)
```

The values used in the plot can be returned with `anlz_sedimentpelave()`. 

```{r}
anlz_sedimentpelave(sedimentdata, yrrng = c(1993, 2022))
```

The `show_sedimentalratio()` function creates a plot of a selected metal parameter against Aluminum.  This plot provides information on the concentration of the parameter relative to background levels, where Aluminum is present as a common metal in the Earth's crust.  An elevated ratio of a metal parameter relative to aluminum suggests it is higher than background concentrations [@Schropp90].  The linear fit of a log-log model is shown as a solid black line, with 95% prediction intervals.  The TEL/PEL values, if available, are also shown as horizontal red lines. 

```{r, fig.height = 5, fig.width = 7}
show_sedimentalratio(sedimentdata, param = 'Zinc', bay_segment = c('HB', 'LTB'))
```

The same plot can be returned as an interactive [plotly](https://plotly.com/r/) object using `plotly = T`.

```{r, fig.height = 5, fig.width = 7}
show_sedimentalratio(sedimentdata, param = 'Zinc', bay_segment = c('HB', 'LTB'), plotly = T)
```

# References