finish vignettes, modify plot args

Author: fawda123

R/get_scenario.R

@@ -7,7 +7,7 @@
 #'
 #' @returns a data frame with columns for id, scenario, year, SLR in meters, and SLR in feet.
 #' 
-#' @details Information from <https://sealevel.nasa.gov/task-force-scenario-tool?psmsl_id={gauge}>. Results are SLR in mm and feet for the intermediate low, intermediate, and intermediate high scenarios by default based on recommended scenarios from the Climate Science Advisory Panel.  Full options for scenarios are `'Low'`, `'IntLow'`, `'Int'`, `'IntHigh'`, and `'High'`. Values for SLR are relative change from 2020.
+#' @details Information from <https://sealevel.nasa.gov/task-force-scenario-tool?psmsl_id={gauge}>. Results are SLR in meters and feet for the intermediate low, intermediate, and intermediate high scenarios by default based on recommended scenarios from the Climate Science Advisory Panel.  Full options for scenarios are `'Low'`, `'IntLow'`, `'Int'`, `'IntHigh'`, and `'High'`. Values for SLR are relative change from 2020.
 #' 
 #' @export
 #'

R/plot_scenario.R

@@ -5,12 +5,10 @@
 #' @param units character, units for the y-axis. Default is `'ft'`. Options are `'ft'` and `'m'`.
 #' @param linewidth numeric, line width. Default is `1`.
 #' @param caption logical, add caption with source. Default is `TRUE`.
-#' @param title logical, add title. Default is `TRUE`.
-#' @param subtitle character, subtitle for the plot. Default is `'Gauge 8726520, St. Petersburg, FL'`. Use `NULL` to omit.
 #' @param xrng numeric, x-axis range. Default is `c(2020, 2100)`.
-#' @param xbrk numeric, x-axis breaks. Default is `10`.
-#' @param yrng numeric, y-axis range. Default is `c(0, 6)`.
-#' @param ybrk numeric, y-axis breaks. Default is `1`.
+#' @param xbrk numeric, number of x-axis breaks. Default is `10`.
+#' @param yrng numeric, y-axis range as two values. Default is `NULL`, which uses the range of the data..
+#' @param ybrk numeric, number of y-axis breaks. Default is `7`.
 #'
 #' @returns a ggplot object
 #' @export
@@ -19,8 +17,7 @@
 #' dat <- get_scenario()
 #' plot_scenario(dat)
 plot_scenario <- function(dat, cols = c('deepskyblue', 'orange', 'red'), units = 'ft', linewidth = 1, 
-                          caption = TRUE, title = TRUE, subtitle = 'Gauge 8726520, St. Petersburg, FL',
-                          xrng = c(2020, 2100), xbrk = 10, yrng = c(0, 6), ybrk = 1){
+                          caption = TRUE, xrng = c(2020, 2100), xbrk = 10, yrng = NULL, ybrk = 7){
 
   units <- match.arg(units, c('ft', 'm'))
 
@@ -35,18 +32,23 @@ plot_scenario <- function(dat, cols = c('deepskyblue', 'orange', 'red'), units =
   toplo <- dat |> 
     dplyr::rename(
       yvl = !!colnm
-    )  
+    ) |> 
+    dplyr::filter(
+      year >= xrng[1] & year <= xrng[2]
+    )
 
+  if(is.null(yrng))
+    yrng <- c(0, max(toplo$yvl, na.rm = TRUE))
+  
   p <- ggplot2::ggplot(toplo, ggplot2::aes(x = year, y = yvl, color = scenario, group = scenario)) +
     ggplot2::geom_line(linewidth = linewidth) +
     ggplot2::labs(
       x = NULL,
       y = ylab,
-      color = NULL,
-      subtitle = subtitle
+      color = NULL
     ) +
     ggplot2::scale_color_manual(values = colval) +
-    ggplot2::scale_y_continuous(breaks = seq(yrng[1], yrng[2], by = ybrk), limits = yrng) +
+    ggplot2::scale_y_continuous(breaks = scales::pretty_breaks(n = ybrk), limits = yrng) +
     ggplot2::scale_x_continuous(breaks = scales::pretty_breaks(n = xbrk), limits = xrng) +
     ggplot2::theme_minimal() +
     ggplot2::theme(
@@ -62,11 +64,6 @@ plot_scenario <- function(dat, cols = c('deepskyblue', 'orange', 'red'), units =
       ggplot2::labs(caption = cp) 
   }
 
-  if(title){
-    p <- p + 
-      ggplot2::labs(title = 'Relative Sea Level Change Predictions')
-  }
-  
   return(p)
 
 }

R/plot_sealevel.R

@@ -4,18 +4,18 @@
 #' @param col character, color for the line. Default is `'deepskyblue'`.
 #' @param units character, units for the y-axis. Default is `'ft'`. Options are `'ft'` and `'m'`.
 #' @param caption logical, add caption with source. Default is `TRUE`.
-#' @param xrng Date, x-axis range. Default is `NULL`, which uses the range of the data.
-#' @param xbrk numeric, x-axis breaks. Default is `10`.
-#' @param yrng numeric, y-axis range. Default is `c(-1, 1)`.
-#' @param ybrk numeric, y-axis breaks. Default is `0.5`.
+#' @param xrng Date, x-axis range as two values. Default is `NULL`, which uses the range of the data.
+#' @param xbrk numeric, number of x-axis breaks. Default is `10`.
+#' @param yrng numeric, y-axis range as two values. Default is `NULL`, which uses the range of the data.
+#' @param ybrk numeric, number of y-axis breaks. Default is `3`.
 #'
 #' @returns a ggplot object
 #' @export
 #'
 #' @examples
 #' dat <- get_sealevel()
 #' plot_sealevel(dat)
-plot_sealevel <- function(dat, col = 'deepskyblue', units = 'ft', caption = TRUE, xrng = NULL, xbrk = 10, yrng = c(-1, 1), ybrk = 0.5) {
+plot_sealevel <- function(dat, col = 'deepskyblue', units = 'ft', caption = TRUE, xrng = NULL, xbrk = 10, yrng = NULL, ybrk = 3) {
 
   units <- match.arg(units, c('ft', 'm'))
 
@@ -24,24 +24,29 @@ plot_sealevel <- function(dat, col = 'deepskyblue', units = 'ft', caption = TRUE
   }
   if(!is.null(xrng))
     stopifnot(inherits(xrng, 'Date'))
-  
+
   ylab <- ifelse(units == 'ft', 'Feet (MSL)', 'Meters (MSL)')
-  ybrks <- seq(yrng[1], yrng[2], by = ybrk) 
 
   colnm <- names(dat)[grepl(paste0('msl_', units), names(dat))]
 
   toplo <- dat |> 
     dplyr::rename(
       yvl = !!colnm
-    )  
+    ) |> 
+    dplyr::filter(
+      date >= xrng[1] & date <= xrng[2]
+    )
 
+  if(is.null(yrng))
+    yrng <- range(toplo$yvl, na.rm = TRUE)
+
   p <- ggplot2::ggplot(toplo, ggplot2::aes(x = date, y = yvl)) +
     ggplot2::geom_line(color = col) +
     ggplot2::labs(
       x = NULL,
       y = ylab
     ) +
-    ggplot2::scale_y_continuous(breaks = ybrks, limits = yrng) +
+    ggplot2::scale_y_continuous(breaks = scales::pretty_breaks(n = ybrk), limits = yrng) +
     ggplot2::scale_x_date(breaks = scales::pretty_breaks(n = xbrk), limits = xrng) +
     ggplot2::theme_minimal() +
     ggplot2::theme(

man/get_scenario.Rd

@@ -23,6 +23,7 @@ knitr::opts_chunk$set(
 
 ```{r setup}
 library(slrcsap)
+library(ggplot2)
 ```
 
 This vignette provides two figures that support the 2025 update of sea level rise projections for the Tampa Bay region.  The report was created by the Climate Science Advisory Panel (CSAP) to update recommendations from @tbep0519.  
@@ -31,13 +32,18 @@ The first figure shows mean monthly sea level at the St. Petersburg, FL tide gau
 
 ```{r sealevelplot, fig.width = 8, fig.height = 3, fig.cap="1947-2025 monthly mean sea level (MSL) in St. Petersburg, FL, NOAA tide gauge 8726520.  Seasonal cycle removed."}
 dat <- get_sealevel()
-plot_sealevel(dat)
+plot_sealevel(dat, yrng = c(-1, 1), ybrk = 5)
 ```
 
 The second figure shows three sea level rise scenarios for St. Petersburg, FL based on regionally corrected NOAA 2022 curves.  Download the figure [here](https://tbep-tech.github.io/slrcsap/articles/figs_files/figure-html/scenarioplot.png). 
 
 ```{r scenarioplot, fig.width = 8, fig.height = 4, fig.cap="Graphic relative sea level change (RSLC) scenarios for St. Petersburg, FL, as calculated using the regionally corrected NOAA 2022 curves."}
 dat <- get_scenario()
-plot_scenario(dat)
+plot_scenario(dat, yrng = c(0, 6)) + 
+  labs(
+    title = 'Relative Sea Level Change Predictions',
+    subtitle = 'Gauge 8726520, St. Petersburg, FL'
+  )
 ```
 
+## References

man/plot_scenario.Rd

@@ -1,3 +1,15 @@
+@techreport{sweet2022,
+  title={Global and Regional Sea Level Rise Scenarios for the {U}nited {S}tates: Updated Mean Projections and Extreme Water Level Probabilities Along {U.S.} Coastlines},
+  author={Sweet, W.V. and Hamlington, B.D. and Kopp, R.E. and Weaver, C.P. and Barnard, P.L. and Bekaert, D. and Brooks, W. and Craghan, M. and Dusek, G. and Frederikse, T. and Garner, G. and Genz, A.S. and Krasting, J.P. and Larour, E. and Marcy, D. and Marra, J.J. and Obeysekera, J. and Osler, M. and Pendleton, M. and Roman, D. and Schmied, L. and Veatch, W. and White, K.D. and Zuzak, C.},
+  year={2022},
+  institution={National Oceanic and Atmospheric Administration, National Ocean Service},
+  type={NOAA Technical Report},
+  number={NOS 01},
+  address={Silver Spring, MD},
+  pages={111},
+  url={https://oceanservice.noaa.gov/hazards/sealevelrise/noaa-nostechrpt01-global-regional-SLR-scenarios-US.pdf}
+}
+
 @techreport{tbep0519,
 	author={M. Burke and L. Carnahan and K. Hammer-Levy and G. Mitchum},
 	year={2019},

man/plot_sealevel.Rd

@@ -36,11 +36,99 @@ library(slrcsap)
 
 The package includes two core functions to download data and two core functions to plot data.  The two download functions are `get_sealevel()` and `get_scenario()` to download tidal gauge data and sea level rise scenario data, respectively.  The corresponding plot functions to view data retrieved from the download functions are `plot_sealevel()` and `plot_scenario()`. The content below demonstrates how to use each function, including the optional arguments that can be used to customize the output.
 
-Tidal gauge data is downloaded from the NOAA Tides and Currents website.  The data is available for all NOAA tide gauges, but the package is currently set up to download data for the St. Petersburg, FL gauge (NOAA ID 8726520).  The data is downloaded as a CSV file and then read into R.  The data includes monthly mean sea level (MSL) values from 1947 to the present, including a seasonal correction.
+### Sea level Data
+
+Sea level data is downloaded from the [NOAA Tides and Currents](https://tidesandcurrents.noaa.gov){target="_blank} website.  The data is 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 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, figheight = 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()
+```
+
+### 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. 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 using regionally corrected NOAA 2022 curves.  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 2100 for each scenario in meters and feet.
 
 ```{r}
-# Download tidal gauge data
-dat <- get_sealevel()
-head(dat)
+# 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.  
+
+```{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_sealevel()` 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 Predictions',
+    subtitle = 'Gauge 8726520, St. Petersburg, FL'
+  ) +
+  theme_grey() + 
+  theme(legend.position = 'bottom')
 ```
 
+## References