Merge pull request #19 from nrennie/fix-scale-name

Remove `scale_name` and fix argument names

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: PrettyCols
 Title: Pretty Colour Palettes
-Version: 1.0.1.9001
+Version: 1.0.1.9002
 Authors@R: 
     person(given = "Nicola",
            family = "Rennie",
@@ -10,13 +10,14 @@ Description: Defines aesthetically pleasing colour palettes.
 License: CC0
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.1
 Depends: 
   R (>= 3.6)
 Imports: 
   ggplot2,
   graphics,
-  grDevices, 
+  grDevices,
+  lifecycle,
   purrr
 Suggests:
   covr,

NAMESPACE

@@ -20,3 +20,4 @@ importFrom(graphics,image)
 importFrom(graphics,par)
 importFrom(graphics,rect)
 importFrom(graphics,text)
+importFrom(lifecycle,deprecated)

NEWS.md

@@ -1,8 +1,18 @@
-## PrettyCols 1.0.1.9000+ 2023_08_29
+## PrettyCols 1.0.1.9000+ 2024_06_15
+
+### Breaking changes (1.0.1.9002+)
+
+* Argument `name` in `scale_*_*()` functions is now used to define the title of the legend, to make this consistent with other {ggplot2} `scale` functions. If you have previously used e.g. `scale_fill_manual(name = "Bright")` to say you want to use the `"Bright"` palette, this will result in an error. Please use `scale_fill_manual(palette = "Bright")` instead.
+* Argument `legend_title` in `scale_*_*()` functions is deprecated. Please use `name` instead. For now, `legend_title` still works. 
+
+### Non-breaking changes
 
 * Move Python implementation to separate repository
 * Add `scale_*_pretty_div()` diverging scale functions
-* Changes examples to mtcars data
+* Changes examples to `mtcars` data
+* Remove `scale_name` from `discrete_scale()` calls
+* Add {lifecycle} to Imports
+
 
 ## PrettyCols 1.0.1 2023_01_27
 

R/PrettyCols-package.R

@@ -0,0 +1,7 @@
+#' @keywords internal
+"_PACKAGE"
+
+## usethis namespace: start
+#' @importFrom lifecycle deprecated
+## usethis namespace: end
+NULL

R/colorblind_friendly.R

@@ -10,7 +10,9 @@
 colorblind_friendly <- function(palettes = PrettyColsPalettes) {
   cbf <- unlist(lapply(palettes, `[[`, 4))
   cbf_palettes <- palettes[unname(which(cbf == TRUE))]
-  cbf_palettes_df <- data.frame(name = names(cbf_palettes),
-                                type = unname(unlist(lapply(cbf_palettes, `[[`, 3))))
+  cbf_palettes_df <- data.frame(
+    name = names(cbf_palettes),
+    type = unname(unlist(lapply(cbf_palettes, `[[`, 3)))
+  )
   return(cbf_palettes_df)
 }

R/colourblind_friendly.R

@@ -10,7 +10,9 @@
 colourblind_friendly <- function(palettes = PrettyColsPalettes) {
   cbf <- unlist(lapply(palettes, `[[`, 4))
   cbf_palettes <- palettes[unname(which(cbf == TRUE))]
-  cbf_palettes_df <- data.frame(name = names(cbf_palettes),
-                                type = unname(unlist(lapply(cbf_palettes, `[[`, 3))))
+  cbf_palettes_df <- data.frame(
+    name = names(cbf_palettes),
+    type = unname(unlist(lapply(cbf_palettes, `[[`, 3)))
+  )
   return(cbf_palettes_df)
 }

R/prettycols.R

@@ -1,6 +1,6 @@
 #' Generates the colour palettes
 #'
-#' @param name Name of Palette. Run \code{names(PrettyColsPalettes)} to view options.
+#' @param palette Name of Palette. Run \code{names(PrettyColsPalettes)} to view options.
 #' @param n Number of desired colors. If number of requested colors is beyond the scope of the palette,
 #' colors are automatically interpolated. If n is not provided, the length of the palette is used.
 #' @param type Either "continuous" or "discrete". Use continuous if you want to automatically
@@ -11,20 +11,20 @@
 #' prettycols("Blues")
 #' @export
 
-prettycols <- function(name,
+prettycols <- function(palette,
                        n,
                        type = "discrete",
                        direction = 1) {
   `%notin%` <- Negate(`%in%`)
 
-  palette <- PrettyColsPalettes[[name]]
+  palette_choice <- PrettyColsPalettes[[palette]]
 
-  if (is.null(palette) || is.numeric(name)) {
+  if (is.null(palette_choice) || is.numeric(palette)) {
     stop("Palette name does not exist. Use names(PrettyColsPalettes) to find valid palette name.")
   }
 
   if (missing(n)) {
-    n <- length(palette[[1]])
+    n <- length(palette_choice[[1]])
   }
 
   if (direction %notin% c(1, -1)) {
@@ -35,26 +35,26 @@ prettycols <- function(name,
     stop("Invalid palette type. Must be one of 'discrete' or 'continuous'.")
   }
 
-  if (type == "discrete" && n > length(palette[[1]])) {
+  if (type == "discrete" && n > length(palette_choice[[1]])) {
     stop("Number of requested colors greater than what discrete palette can offer, use continuous instead.")
   }
 
   continuous <- if (direction == 1) {
-    grDevices::colorRampPalette(palette[[1]])(n)
+    grDevices::colorRampPalette(palette_choice[[1]])(n)
   } else {
-    grDevices::colorRampPalette(rev(palette[[1]]))(n)
+    grDevices::colorRampPalette(rev(palette_choice[[1]]))(n)
   }
 
   discrete <- if (direction == 1) {
-    palette[[1]][1:n]
+    palette_choice[[1]][1:n]
   } else {
-    rev(palette[[1]])[1:n]
+    rev(palette_choice[[1]])[1:n]
   }
 
   out <- switch(type,
     continuous = continuous,
     discrete = discrete
   )
 
-  structure(out, class = "palette", name = name)
+  structure(out, class = "palette", palette = palette)
 }

R/print_palette.R

@@ -21,7 +21,7 @@ print.palette <- function(x, ...) {
     border = "black"
   )
   graphics::text((n + 1) / 2, 1,
-    labels = attr(x, "name"),
+    labels = attr(x, "palette"),
     cex = 1.5,
     family = "sans",
     col = grDevices::rgb(1, 1, 1, 1)

R/scale_color_pretty_c.R

@@ -1,26 +1,37 @@
 #' Plotting with PrettyCols palettes for colour ggplot2
-#' @param name Name of Palette. Run \code{names(PrettyColsPalettes)} to view options.
+#' @param palette Name of Palette. Run \code{names(PrettyColsPalettes)} to view options.
 #' @param direction Sets order of colors. Default palette is 1. If direction is -1,
 #' palette color order is reversed
-#' @param legend_title Character string specifying legend title. Default `NULL`.
+#' @param legend_title `r lifecycle::badge("deprecated")` Deprecated in favour of `name`.
 #' @param ... Other arguments passed on to \code{\link[ggplot2]{scale_color_gradientn}}
 #' @return A ggproto object defining a continuous colour scale for use with ggplot2.
 #' @examples
 #' library(ggplot2)
-#' ggplot(data=mtcars, aes(x=mpg, y=disp, color=wt)) +
+#' ggplot(data = mtcars, aes(x = mpg, y = disp, color = wt)) +
 #'   geom_point() +
 #'   scale_color_pretty_c("Greens")
 #' @export
 
-scale_color_pretty_c <- function(name,
+scale_color_pretty_c <- function(palette,
                                  direction = 1,
                                  legend_title = NULL, ...) {
+  if (missing(palette)) {
+    stop("Please use the 'palette' argument to define which colour palette you want to use.")
+  }
+
+  if (!is.null(legend_title)) {
+    lifecycle::deprecate_soft(
+      when = "1.1.0",
+      what = "scale_color_pretty_c(legend_title)",
+      details = "Please use `name` to set the legend title instead."
+    )
+  }
 
   `%notin%` <- Negate(`%in%`)
 
-  palette <- PrettyColsPalettes[[name]]
+  palette_choice <- PrettyColsPalettes[[palette]]
 
-  if (is.null(palette) || is.numeric(name)) {
+  if (is.null(palette_choice) || is.numeric(palette)) {
     stop("Palette does not exist.")
   }
 
@@ -29,9 +40,13 @@ scale_color_pretty_c <- function(name,
   }
 
   if (!is.null(legend_title)) {
-    ggplot2::scale_color_gradientn(name = legend_title,
-                                   colors = prettycols(name = name, direction = direction), ...)
+    ggplot2::scale_color_gradientn(
+      name = legend_title,
+      colors = prettycols(palette = palette, direction = direction), ...
+    )
   } else {
-    ggplot2::scale_color_gradientn(colors = prettycols(name = name, direction = direction), ...)
+    ggplot2::scale_color_gradientn(
+      colors = prettycols(palette = palette, direction = direction), ...
+    )
   }
 }

R/scale_color_pretty_d.R

@@ -1,50 +1,64 @@
 #' Plotting with PrettyCols palettes for colour ggplot2
-#' @param name Name of Palette. Run \code{names(PrettyColsPalettes)} to view options.
+#' @param palette Name of Palette. Run \code{names(PrettyColsPalettes)} to view options.
 #' @param direction Sets order of colors. Default palette is 1. If direction is -1,
 #' palette color order is reversed
-#' @param legend_title Character string specifying legend title. Default `NULL`.
+#' @param legend_title `r lifecycle::badge("deprecated")` Deprecated in favour of `name`.
 #' @param ... Other arguments passed on to \code{\link[ggplot2]{discrete_scale}}
 #' @return A ggproto object defining a discrete colour scale for use with ggplot2.
 #' @examples
 #' library(ggplot2)
-#' ggplot(data=mtcars, aes(x=mpg, y=disp, color=factor(cyl))) +
+#' ggplot(data = mtcars, aes(x = mpg, y = disp, color = factor(cyl))) +
 #'   geom_point() +
 #'   scale_color_pretty_d("Bright")
 #' @export
 
-scale_color_pretty_d <- function(name,
+scale_color_pretty_d <- function(palette,
                                  direction = 1,
                                  legend_title = NULL, ...) {
-  prettycols_disc <- function(name, direction = 1) {
+  if (missing(palette)) {
+    stop("Please use the 'palette' argument to define which colour palette you want to use.")
+  }
 
+  if (!is.null(legend_title)) {
+    lifecycle::deprecate_soft(
+      when = "1.1.0",
+      what = "scale_color_pretty_d(legend_title)",
+      details = "Please use `name` to set the legend title instead."
+    )
+  }
+
+  prettycols_disc <- function(palette, direction = 1) {
     `%notin%` <- Negate(`%in%`)
 
-    palette <- PrettyColsPalettes[[name]]
+    palette_choice <- PrettyColsPalettes[[palette]]
 
-    if (is.null(palette) || is.numeric(name)) {
+    if (is.null(palette_choice) || is.numeric(palette)) {
       stop("Palette does not exist.")
     }
 
     if (direction %notin% c(1, -1)) {
       stop("Direction not valid. Please use 1 for standard palette or -1 for reversed palette.")
     }
 
-    function(n) if (direction == 1) {
-      palette[[1]][1:n]
-    } else {
-      rev(palette[[1]])[1:n]
+    function(n) {
+      if (direction == 1) {
+        palette_choice[[1]][1:n]
+      } else {
+        rev(palette_choice[[1]])[1:n]
+      }
     }
-
   }
 
   if (!is.null(legend_title)) {
-    ggplot2::discrete_scale(name = legend_title,
-                            aesthetics = "colour",
-                            scale_name = "pretty_d",
-                            palette = prettycols_disc(name = name, direction = direction), ...)
+    ggplot2::discrete_scale(
+      name = legend_title,
+      aesthetics = "colour",
+      palette = prettycols_disc(palette = palette, direction = direction), ...
+    )
   } else {
-    ggplot2::discrete_scale(aesthetics = "colour",
-                            scale_name = "pretty_d",
-                            palette = prettycols_disc(name = name, direction = direction), ...)
+    ggplot2::discrete_scale(
+      aesthetics = "colour",
+      palette = prettycols_disc(palette = palette, direction = direction), ...
+    )
   }
 }

R/scale_color_pretty_div.R

@@ -1,31 +1,41 @@
 #' Plotting with PrettyCols palettes for colour ggplot2
-#' @param name Name of Palette. Run \code{view_all_palettes(type = "div")} to view
+#' @param palette Name of Palette. Run \code{view_all_palettes(type = "div")} to view
 #' options. Must be a diverging palette name.
 #' @param direction Sets order of colors. Default palette is 1. If direction is -1,
 #' palette color order is reversed
-#' @param legend_title Character string specifying legend title. Default `NULL`.
+#' @param legend_title `r lifecycle::badge("deprecated")` Deprecated in favour of `name`.
 #' @param ... Other arguments passed on to \code{\link[ggplot2]{scale_colour_gradient2}}
 #' @return A ggproto object defining a continuous colour scale for use with ggplot2.
 #' @examples
 #' library(ggplot2)
-#' ggplot(data=mtcars, aes(x=mpg, y=disp, colour=wt)) +
+#' ggplot(data = mtcars, aes(x = mpg, y = disp, colour = wt)) +
 #'   geom_point() +
 #'   scale_color_pretty_div("PurpleYellows", midpoint = mean(mtcars$wt))
 #' @export
 
-scale_color_pretty_div <- function(name,
+scale_color_pretty_div <- function(palette,
                                    direction = 1,
                                    legend_title = NULL, ...) {
+  if (missing(palette)) {
+    stop("Please use the 'palette' argument to define which colour palette you want to use.")
+  }
 
+  if (!is.null(legend_title)) {
+    lifecycle::deprecate_soft(
+      when = "1.1.0",
+      what = "scale_color_pretty_div(legend_title)",
+      details = "Please use `name` to set the legend title instead."
+    )
+  }
   `%notin%` <- Negate(`%in%`)
 
-  palette <- PrettyColsPalettes[[name]]
+  palette_choice <- PrettyColsPalettes[[palette]]
 
-  if (is.null(palette) || is.numeric(name)) {
+  if (is.null(palette_choice) || is.numeric(palette)) {
     stop("Palette does not exist.")
   }
 
-  if (palette[[3]] != "div") {
+  if (palette_choice[[3]] != "div") {
     stop("Palette must be a diverging palette.")
   }
 
@@ -34,23 +44,27 @@ scale_color_pretty_div <- function(name,
   }
 
   if (direction == 1) {
-    low_col <- palette[[1]][1]
-    high_col <- utils::tail(palette[[1]], 1)
+    low_col <- palette_choice[[1]][1]
+    high_col <- utils::tail(palette_choice[[1]], 1)
   } else {
-    low_col <- utils::tail(palette[[1]], 1)
-    high_col <- palette[[1]][1]
+    low_col <- utils::tail(palette_choice[[1]], 1)
+    high_col <- palette_choice[[1]][1]
   }
-  mid_col <- palette[[1]][ceiling(length(palette[[1]]) / 2)]
+  mid_col <- palette_choice[[1]][ceiling(length(palette_choice[[1]]) / 2)]
 
 
   if (!is.null(legend_title)) {
-    ggplot2::scale_color_gradient2(name = legend_title,
-                                   low = low_col,
-                                   mid = mid_col,
-                                   high = high_col, ...)
+    ggplot2::scale_color_gradient2(
+      name = legend_title,
+      low = low_col,
+      mid = mid_col,
+      high = high_col, ...
+    )
   } else {
-    ggplot2::scale_color_gradient2(low = low_col,
-                                   mid = mid_col,
-                                   high = high_col, ...)
+    ggplot2::scale_color_gradient2(
+      low = low_col,
+      mid = mid_col,
+      high = high_col, ...
+    )
   }
 }