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

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

library(tbeptools)
library(mapview)
library(sf)

sf_use_s2(FALSE)

sf::st_crs(trnpts) <- 4326
sf::st_crs(trnlns) <- 4326

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

Each year, TBEP partners collect seagrass transect data at fixed locations in Tampa Bay.  Data have been collected since the mid 1990s and are hosted online at the [Tampa Bay Water Atlas](https://www.tampabay.wateratlas.usf.edu/) by the University of South Florida Water Institute.  Functions are available in tbeptools for downloading, analyzing, and plotting these data. 

## Data import and included datasets

There are two datasets included in tbeptools that show the actively monitored transect locations in Tampa Bay.  The `trnpts` dataset is a point object for the starting location of each transect and the `trnlns` dataset is a line object showing the approximate direction and length of each transect beginning at each point in `trnpts`.  Each dataset also includes the `MonAgency` column that indicates which monitoring agency collects the data at each transect. 

```{r}
trnpts
trnlns
```

The two datasets are `sf()` (simple features) objects and are easily mapped with `mapview()` to view their locations.

```{r, out.width = '100%'}
cols <- c("#E16A86", "#CB7F2F", "#9F9400", "#50A315", "#00AC79", "#00AAB7", "#009ADE", "#A87BE4", "#DA65C3")

mapview(trnpts, zcol = 'MonAgency', lwd = 0, legend = F, homebutton = F, col.regions = cols) + 
  mapview(trnlns, zcol = 'MonAgency', homebutton = F, layer.name = 'Monitoring Agency', lwd = 4, color = cols)
```

The transect data can be downloaded from the Water Atlas using the `read_transect()` function.  The only required argument for this function is `training`, which indicates if you want to download training data or the complete dataset, i.e., `training = TRUE` or `training = FALSE` (default).  In the former case, a small dataset is downloaded that includes only data collected during an annual training event. These are primarily used internally by TBEP staff to assess precision among different training crews. The data are downloaded as a JSON object and formatted internally using the `read_formtransect()` function.  Shoot density is reported as number of shoots per square meter and is corrected for the quadrat size entered in the raw data. Abundance is reported as a numeric value from 0 -5 for Braun-Blanquet coverage estimates and blade length is in cm.  

```{r}
# import training data
traindat <- read_transect(training = TRUE)

# view the data
traindat
```

Change the `training` argument to `FALSE` to download the entire transect database.  This may take a few seconds.

```{r}
# import entire transct dataset as JSON
transect <- read_transect(training = FALSE)

# view the data
transect
```

The columns in the complete transect database describe the crew (`Crew`), the monitoring agency (`MonitoringAgency`), sample date (`Date`), transect name (`Transect`), the meter location for the quadrat along the transect (`Site`, m), depth at the site (`Depth`, cm), Seagrass species (`Savspecies`), distance of the seagrass edge on the transect (`SeagrassEdge`, m), the seagrass variable (`var`), average value of the variable (`aveval`), and standard deviation of the variable if appropriate (`sdval`).  

If the raw, unformatted transect data are preferred, use the `raw = TRUE` argument for `read_transect()`. 

```{r}
# raw transect data
transectraw <- read_transect(training = FALSE, raw = TRUE)

# view the data
transectraw
```

## Calculating seagrass frequency occurrence

The rest of the seagrass functions in tbeptools were developed to work with the complete database.  Only the `show_complot()` function (see below) was developed for the training data.  The rest of the functions can be used to estimate and plot frequency occurrence data.  

The `anlz_transectocc()` function summarizes frequency occurrence for all transects and dates by collapsing species results across quadrats within each transect.  Abundance and frequency occurrence are estimated as in Sherwood et al. 2017, equations 1 and 2 [@tbep0917]. In short, frequency occurrence is estimated as the number of instances a species was observed along a transect divided by the number of placements along a transect and average abundance was estimated as the sum of species-specific Braun-Blanquet scores divided by the number of placements along a transect.  The estimates are obtained for all seagrass species, including Caulerpa spp. (attached macroalgae), Dapis (cyanobacteria), and Chaetomorpha (drift green algae), whereas all attached and drift algae species are aggregated. Drift or attached macroalgae and cyanobacteria (Dapis) estimates may not be accurate prior to 2021.

```{r}
transectocc <- anlz_transectocc(transect)
transectocc
```

The second function, `anlz_transectave()`, takes the results from `anlz_transectocc()` and estimates annual results across major bay segments for all seagrass species by averaging frequency occurrence across transects.  This function is used internally within the `show_transectmatrix()` function to create summary plots. The frequency occurrence estimates are also binned into categories for simple trend assessments, e.g., red < 25%, orange 25-50%, yellow 50-75%, and green > 75%.  Results for specific bay segments and annual ranges can be filtered with the `bay_segment` and `yrrng` arguments.

```{r}
transectave <- anlz_transectave(transectocc)
transectave
```

The third function, `anlz_transectavespp()`, takes the results from `anlz_transectocc()` and estimates annual averages across major bay segments as in the last function, but results are retained for individual species.  This function is used internally within the `show_transectavespp()` function to create summary plots.  All summaries are aggregated across the selected bay segments, i.e., the default is to average by species/year across all segments.  Results for an individual bay segment can be returned with the appropriate argument, e.g., by using `bay_segment = 'OTB'` to select only Old Tampa Bay.  Results can also be filtered by specific species using the `species` argument, where the default is to return all.  *Caulerpa spp.*, *Dapis spp.*, and *Chaetomorpha spp.* are also included. 

```{r}
transectavespp <- anlz_transectavespp(transectocc)
transectavespp
```

Results for individual bay segments from `anlz_transectavespp()` can be retained by setting the `by_seg` argument to `TRUE`.  Note that totals are not returned in this case. 

```{r}
transectavespp <- anlz_transectavespp(transectocc, by_seg = TRUE)
transectavespp
```

## Plotting results

There is one plotting function for the training data.  The `show_compplot()` function is used to compare training data between crews for a selected species (`species` argument) and variable (`varplo` argument). 

```{r, fig.height = 5, fig.width = 7}
show_compplot(traindat, yr = 2024, site = '2', species = 'Halodule', varplo = 'Abundance', base_size = 14)
```

The rest of the plotting functions work with the complete transect data. Data for an individual transect can be viewed with the `show_transect()` function by entering the transect (site) number, species (one to many), and variable to plot.  The plot shows relative values for the selected species and variable by distance along the transect (x-axis) and year of sampling (y-axis).  The plots provide an overall summary of temporal and spatial changes in the selected seagrass metric for an individual location.  

```{r, fig.height = 8, fig.width = 9}
show_transect(transect, site = 'S3T10', species = 'Halodule', varplo = 'Abundance')
```

The plot can also be produced as a [plotly](https://plotly.com/r/) interactive plot by setting `plotly = TRUE` inside the function. Note that the size legend is merged with the species legend, where the point size is the average abundance for the species.  The sizes can be viewed on mouseover of each point. 

```{r, fig.height = 8, fig.width = 8}
show_transect(transect, site = 'S3T10', species = 'Halodule', varplo = 'Abundance', plotly = T)
```

The `show_transect()` function can also be used to plot multiple species.  One to many species can be provided to the `species` argument. 

```{r, fig.height = 8, fig.width = 8}
show_transect(transect, site = 'S3T10', species = c('Halodule', 'Syringodium', 'Thalassia'), varplo = 'Abundance')
```

The plots can also be separated into facets for each species using `facet = TRUE`. This is useful to reduce overplotting of multiple species found at the same location.

```{r, fig.height = 8, fig.width = 8}
show_transect(transect, site = 'S3T10', species = c('Halodule', 'Syringodium', 'Thalassia'), varplo = 'Abundance', facet = TRUE)
```

The `show_transectsum()` function provides an alternative summary of data at an individual transect. This plot provides a quick visual assessment of how frequency occurrence or abundance for multiple species has changed over time at a selected transect.  Unlike `show_transect()`, the plot shows aggregated results across quadrats along the transect and uses summarized data from the `anlz_transectocc()` function as input.  

```{r, out.width = '100%'}
show_transectsum(transectocc, site = 'S3T10')
```

A summary matrix of frequency occurrence estimates across all species can be plotted with `show_transectmatrix()`.  This uses results from the `anlz_transectocc()` and `anlz_transectave()` functions to estimate annual averages by bay segment.  The continuous frequency occurrence estimates are binned into color categories described above, as in Table 1 in [@tbep0816]. 

```{r, fig.height = 7, fig.width = 4}
show_transectmatrix(transectocc)
```

The default color scheme is based on arbitrary breaks at 25, 50, and 75 percent frequency occurrence.  These don't necessarily translate to any ecological breakpoints. Use `neutral = TRUE` to use a neutral and continuous color palette.

```{r, fig.height = 7, fig.width = 4}
show_transectmatrix(transectocc, neutral = T)
```

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_transectmatrix(transectocc, plotly = T)
```

Time series plots of annual averages of frequency occurrence estimates by each species can be shown with the `show_transectavespp()` function.  By default, all estimates are averaged across all bay segments for each species.  The plot is a representation of Figure 2 in [@tbep0816].

```{r, fig.height = 6, fig.width = 7}
show_transectavespp(transectocc)
```

Results for individual segments and species can be returned with the `bay_segment` and `species` arguments.  Use the argument `total = FALSE` to omit the total frequency occurrence from the plot.

```{r, fig.height = 6, fig.width = 7}
show_transectavespp(transectocc, bay_segment = 'LTB', species = c('Syringodium', 'Thalassia'), total = FALSE)
```

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

```{r, fig.height = 6, fig.width = 7}
show_transectavespp(transectocc, bay_segment = 'LTB', species = c('Syringodium', 'Thalassia'), plotly = T)
```

As an alternative to plotting the species averages over time with `show_transectavespp()`, a table can be created by setting `asreact = TRUE`.  Filtering options that apply to the plot also apply to the table, e.g., filtering by the four major bay segments and specific year ranges.  Also note that the totals are not returned in the table. 

```{r}
show_transectavespp(transectocc, asreact = T, bay_segment = c('HB', 'OTB', 'MTB', 'LTB'), yrrng = c(2006, 2012))
```

All of the above describes methods in tbeptools for working with transect monitoring data. Seagrass coverage maps are also created approximately biennially by the Southwest Florida Water Management District, available at [https://data-swfwmd.opendata.arcgis.com/](https://data-swfwmd.opendata.arcgis.com/). The `seagrass` data object included with the package shows Tampa Bay coverage total for each year of available data, including a 1950s reference estimate.  The `show_seagrasscoverage()` function creates the flagship seagrass coverage graphic to report on changes over time from these data.  

```{r, fig.height = 4, fig.width = 6}
show_seagrasscoverage(seagrass)
```

# References