---
title: "Getting started"
output: rmarkdown::html_vignette
bibliography: refs.bib
date: "`r Sys.Date()`"
csl: stylefile.csl
vignette: >
  %\VignetteIndexEntry{Getting started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Installation

Install the package from [r-universe](http://tbep-tech.r-universe.dev/ui/#builds) as follows. The source code is available on [GitHub](https://github.com/tbep-tech/slrcsap).

```{r eval = F}
# Install slrcsap in R:
install.packages('slrcsap', repos = c('https://tbep-tech.r-universe.dev', 'https://cloud.r-project.org'))
```

Load the package in an R session after installation:

```{r}
library(slrcsap)
```

## Usage

The package includes two core workflows to download and plot data relevant to assess sea level rise risks in the Tampa Bay region.  The first workflow retrieves and plots historical sea level data and the second retrieves and plots sea level rise scenario data.  Default arguments for all functions are set for the tidal gauge at [St. Petersburg, FL](https://tidesandcurrents.noaa.gov/stationhome.html?id=8726520){target="_blank"} following recommendations from the Tampa Bay Climate Science Advisory Panel [@tbep1425]. The content below demonstrates how to use the functions in this package for each workflow.

### Sea level Data

Sea level data are downloaded from the [NOAA Tides and Currents](https://tidesandcurrents.noaa.gov){target="_blank} website.  The data are available for all NOAA tide gauges and is setup to download data for the St. Petersburg, FL gauge (NOAA ID 8726520) by default.  The data is read directly into R from the URL <https://tidesandcurrents.noaa.gov/sltrends/data/8726520_meantrend.txt>.  The data for St. Petersburg, includes monthly mean sea level (MSL) values from 1947 to the present, including a seasonal correction.

```{r}
# Download sea level data for St. Petersburg
spsealevel <- get_sealevel()
head(spsealevel)
```

Data for alternative stations can be obtained using the `gauge` argument.  

```{r}
# Download sea level data for Cedar Key
cksealevel <- get_sealevel(gauge = 8727520)
head(cksealevel)
```

The sea level data can be plotted using the `plot_sealevel()` function.  

```{r, fig.height = 3, fig.width = 8}
# Plot sea level data for St. Petersburg
plot_sealevel(spsealevel)

# Plot sea level data for Cedar Key
plot_sealevel(cksealevel)
```

Various arguments for `plot_sealevel()` can change the appearance of the plot.  Below, the color, units, and x-axis range are modified  

```{r, fig.height = 3, fig.width = 8}
# Change arguments for the plot
plot_sealevel(spsealevel, col = 'tomato1', units = 'm', 
              xrng = as.Date(c('2000-01-01', '2023-01-01')))
```

The plot is also a `ggplot()` object and can be modified with additional [ggplot2](https://ggplot2.tidyverse.org/){target="_blank"} functions.  Below, the plot is modified to add a title and change the theme.

```{r, fig.height = 3, fig.width = 8}
# Add a title and change the theme
library(ggplot2)
plot_sealevel(spsealevel) +
  ggtitle('Monthly Mean Sea Level (MSL) at St. Petersburg, FL') +
  theme_grey()
```

Lastly, the plot can also be returned as a `plotly` object using `plotly = T`. 

```{r, fig.height = 3, fig.width = 8}
# Create plotly output
plot_sealevel(spsealevel, plotly = T)
```

### Sea Level Rise Scenarios

Sea level rise scenarios can be downloaded using the `get_scenario()` function.  Data are downloaded from the [Interagency Sea Level Rise Scenario Tool](https://sealevel.nasa.gov/task-force-scenario-tool){target="_blank} website that uses regionally corrected NOAA 2022 curves. Details of the methods used in this tool are found in the technical report [@sweet2022].  The data are downloaded as an Excel sheet to from the URL <https://sealevel.nasa.gov/task-force-scenario-tool?psmsl_id=520>, set to St. Petersburg, FL by default.  Emissions scenarios of NOAA Intermediate Low, Intermediate, and Intermediate High are downloaded by default, as recommended by the Climate Science Advisory Panel.  The data show relative sea level change (RSLC) from 2020 to 2150 for each scenario in meters and feet.

```{r}
# Download sea level rise scenarios for St. Petersburg
spscenario <- get_scenario()
head(spscenario)
```

Data for alternative locations and scenarios can be obtained using the `id` and `scenario` arguments, respectively.

```{r}
# Download sea level rise scenarios for Cedar Key
ckscenario <- get_scenario(id = 428, scenario = c('Low', 'IntLow', 'Int', 'IntHigh', 'High'))
head(ckscenario)
```

The sea level rise scenarios can be plotted using the `plot_scenario()` function.  Note the default x-axis range that extends only to 2100.  

```{r, fig.height = 4, fig.width = 8}
# Plot sea level rise scenarios for St. Petersburg
plot_scenario(spscenario)

# Plot sea level rise scenarios for Cedar Key
plot_scenario(ckscenario)
```

Various arguments for `plot_scenario()` can change the appearance of the plot.  Below, the color ramp, units, and x-axis range are modified  

```{r, fig.height = 4, fig.width = 8}
# Change arguments for the plot
plot_scenario(spscenario, cols = c('green', 'blue', 'red'), units = 'm', 
              xrng = c(2020, 2150))
```

The plot is also a `ggplot()` object and can be modified with additional [ggplot2](https://ggplot2.tidyverse.org/){target="_blank"} functions.  Below, the plot is modified to add a title, subtitle, and change the theme.

```{r, fig.height = 4, fig.width = 8}
# Add a title, subtitle and change the theme
plot_scenario(spscenario) +
  labs(
    title = 'Relative Sea Level Change Projections',
    subtitle = 'Gauge 8726520, St. Petersburg, FL'
  ) +
  theme_grey() + 
  theme(legend.position = 'bottom')
```

Lastly, the plot can also be returned as a `plotly` object using `plotly = T`. 

```{r, fig.height = 3, fig.width = 8}
# Create plotly output
plot_scenario(spscenario, plotly = T)
```

## References