Add theming function (#72)

* Create first working version of new nmfs theme, for continuous palettes only

* Add functionality for nmfs theme, for discrete and non-interpolated palettes

* Add functionality for nmfs theme, for discrete and interpolated palettes; update documentation

* Update output type of display_nmfs_palette() and associated test

* Add note directing user to ggplot2's v4.0.0 release notes; update documentation

* Add new tests for theming fxn

* Update README

* Updates as suggested by @k-doering-NOAA during review

Author: sbreitbart-NOAA

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: nmfspalette
 Title: A Color Palette for NOAA Fisheries
-Version: 3.2.0.000
+Version: 3.3.0.000
 Authors@R: c(
     person("Christine", "Stawitz", , "christine.stawitz@noaa.gov", role = "aut"),
     person("Bai", "Li", , "bai.li@noaa.gov", role = "aut"),
@@ -17,8 +17,10 @@ BugReports: https://github.com/nmfs-ost/nmfspalette/issues
 Imports: 
     cli,
     ggplot2,
+    graphics,
     pals,
-    rlang
+    rlang,
+    utils
 Suggests: 
     dichromat,
     dplyr,
@@ -36,4 +38,4 @@ Config/testthat/edition: 3
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.2
+RoxygenNote: 7.3.3

NAMESPACE

@@ -6,3 +6,4 @@ export(nmfs_cols)
 export(nmfs_palette)
 export(scale_color_nmfs)
 export(scale_fill_nmfs)
+export(theme_nmfs)

R/ggplot2-scales.R

@@ -115,3 +115,115 @@ To avoid this error, use a larger palette or `interpolate = TRUE`.",
     ggplot2::scale_fill_gradientn(colours = pal(256), ...)
   }
 }
+
+
+#' Create theme for nmfs colors
+#' @inheritParams scale_color_nmfs
+#' @param base_size The base font size, as defined in the
+#'   [ggplot2::theme_gray()] function
+#' @param lab_size The axis text size
+#' @param ink The plot foreground color, as defined in the
+#'   [ggplot2::theme_gray()] function
+#' @param paper The plot background color, as defined in the
+#'   [ggplot2::theme_gray()] function
+#' @param accent The plot's accented elements' color, as defined in the
+#'   [ggplot2::theme_gray()] function
+#' @param ... Additional arguments passed to: [ggplot2::scale_fill_gradientn()]
+#' when `discrete` is TRUE; [ggplot2::discrete_scale()] when `discrete` is FALSE
+#' and `interpolate` is TRUE; and [ggplot2::scale_fill_manual()] when `discrete`
+#' is FALSE and `interpolate` is FALSE.
+#' @return A theme that applies nmfs color palettes and theme-related elements (such as label sizes, borders, axis lines, and more) to a plot. For more information about the ggplot2 advances that enabled this function, check out the [ggplot2 version 4.0.0 release notes](https://tidyverse.org/blog/2025/09/ggplot2-4-0-0/).
+#' @examples
+#' library(ggplot2)
+#' ggplot(mtcars, aes(x = mpg, y = disp, color = as.factor(cyl))) +
+#'   geom_point(size = 3) +
+#'   theme_nmfs(discrete = TRUE, interpolate = TRUE, palette = "crustacean")
+#' ggplot(mtcars, aes(x = mpg, y = disp, color = as.factor(cyl))) +
+#'   geom_point(size = 3) +
+#'   theme_nmfs(discrete = TRUE, interpolate = FALSE, palette = "crustacean")
+#' ggplot(mtcars, aes(x = mpg, y = disp, fill = hp)) +
+#' geom_point(size = 3, shape = 24) +
+#' theme_nmfs(discrete = FALSE, interpolate = TRUE, palette = "seagrass")
+#' @export
+theme_nmfs <- function(
+    palette = "oceans", 
+    discrete = TRUE,
+    reverse = FALSE,
+    interpolate = TRUE,
+    base_size = 14,
+    lab_size = 12,
+    ink = "black",
+    paper = "white",
+    accent = "#003087",
+    ...) {
+  if (utils::packageVersion("ggplot2") < "4.0.0"){
+    rlang::warn(
+      message = paste0("Your `ggplot2` version is ", utils::packageVersion("ggplot2"), ", which is older than the version required to use `theme_nmfs()` (4.0.0). Update your `ggplot2` package to use this new function!"),
+      .frequency = "once",
+      .frequency_id = "ggplot2_version_warning"
+    )    
+  }
+
+  
+  # get palette
+  pal <- nmfs_palette(palette = palette,
+                      reverse = reverse)
+  
+  pal_length <- length(nmfs_palettes[[palette]])
+  
+  base_theme1 <- ggplot2::theme_bw(
+    base_size = base_size,
+    ink = ink,
+    paper = paper,
+    accent = accent,
+    ...
+  )
+  
+  base_theme2 <- ggplot2::theme(
+    axis.line = element_line(color = "black",
+                             linewidth = 0.75),
+    axis.text.x = element_text(size = lab_size, 
+                               color = "black"),
+    axis.text.y = element_text(size = lab_size, 
+                               color = "black"),
+    panel.border = element_blank(),
+    panel.grid.major = element_blank(),
+    panel.grid.minor = element_blank(),
+    ...
+  )
+  
+  if (discrete) {
+    if (interpolate) {
+      
+      base_theme1 +
+      base_theme2 +
+      ggplot2::theme(
+         palette.colour.discrete = pal,
+         palette.fill.discrete = pal
+        )
+
+    } else {
+      cli::cli_alert_info("The {palette} palette has {pal_length} colors.")
+      rlang::warn(
+        message = "An error will occur if there are too few palette colors for your plot.
+To avoid this error, use a larger palette or `interpolate = TRUE`.",
+        .frequency = "once",
+        .frequency_id = "too_few_colors_warning_fill"
+      )
+      
+      base_theme1 +
+      base_theme2 +
+        ggplot2::theme(
+          palette.colour.discrete = nmfs_palette(palette)(pal_length),
+          palette.fill.discrete = nmfs_palette(palette)(pal_length)
+        )
+    }
+  } else {
+    base_theme1 +
+    base_theme2 +
+    ggplot2::theme(
+      palette.color.continuous = nmfs_palette(palette)(pal_length),
+      palette.fill.continuous = nmfs_palette(palette)(pal_length)
+    )
+  }
+}

R/nmfs_cols.R

@@ -356,7 +356,7 @@ nmfs_palette <- function(palette = "oceans", reverse = FALSE, ...) {
 #' @param n Number of colors in palette.
 #' @examples
 #' display_nmfs_palette("oceans", 10)
-#' @return A list object showing a specific nmfs color palette in the plot window.
+#' @return An object showing a specific nmfs color palette in the plot window.
 #' @export
 display_nmfs_palette <- function(name, n) {
   pal <- nmfs_palette(name)(n)
@@ -400,10 +400,10 @@ display_nmfs_palette <- function(name, n) {
 #' @export
 all_nmfs_palettes <- function() {
   # default setting
-  old_par <- par(mar = c(0, 6, 0, 0))
+  old_par <- graphics::par(mar = c(0, 6, 0, 0))
 
   # reset par to original setting
-  on.exit(par(old_par))
+  on.exit(graphics::par(old_par))
 
   do.call(
     pals::pal.bands,

README.Rmd

@@ -61,6 +61,20 @@ You can change the number of colors (10 shown below).
 nmfs_palette("oceans")(10)
 ```
 
+## Theme for `ggplot` objects
+
+**New feature**: With the new `theme_nmfs()` function, you can add a NMFS-colored theme to your `ggplot` objects!
+This new theme that applies NMFS color palettes and theme-related elements (such as label sizes, borders, axis lines, and more) to a plot.
+
+```{r}
+#| label: theme_example
+
+library(ggplot2)
+ggplot(mtcars, aes(x = mpg, y = disp, color = as.factor(cyl))) +
+  geom_point(size = 3) +
+  nmfspalette::theme_nmfs(discrete = TRUE, interpolate = TRUE, palette = "crustacean")
+```
+
 ## Palettes
 
 Use the `all_nmfs_palettes()` function to see all available palettes.

README.md

@@ -59,6 +59,24 @@ nmfs_palette("oceans")(10)
 #>  [8] "#002467" "#001D55" "#001743"
 ```
 
+## Theme for `ggplot` objects
+
+**New feature**: With the new `theme_nmfs()` function, you can add a
+NMFS-colored theme to your `ggplot` objects! This new theme that applies
+NMFS color palettes and theme-related elements (such as label sizes,
+borders, axis lines, and more) to a plot.
+
+``` r
+library(ggplot2)
+ggplot(mtcars, aes(x = mpg, y = disp, color = as.factor(cyl))) +
+  geom_point(size = 3) +
+  nmfspalette::theme_nmfs(discrete = TRUE, interpolate = TRUE, palette = "crustacean")
+#> Warning: This function may not work if your `ggplot2` version is below 4.0.0. Update your package version to utilize this new function!
+#> This warning is displayed once per session.
+```
+
+<img src="man/figures/README-theme_example-1.png" width="100%" />
+
 ## Palettes
 
 Use the `all_nmfs_palettes()` function to see all available palettes.