Rename gradient scales

NAMESPACE

@@ -524,6 +524,8 @@ export(scale_color_distiller)
 export(scale_color_fermenter)
 export(scale_color_gradient)
 export(scale_color_gradient2)
+export(scale_color_gradient_div)
+export(scale_color_gradient_seq)
 export(scale_color_gradientn)
 export(scale_color_grey)
 export(scale_color_hue)
@@ -532,6 +534,8 @@ export(scale_color_manual)
 export(scale_color_ordinal)
 export(scale_color_steps)
 export(scale_color_steps2)
+export(scale_color_steps_div)
+export(scale_color_steps_seq)
 export(scale_color_stepsn)
 export(scale_color_viridis_b)
 export(scale_color_viridis_c)
@@ -546,6 +550,8 @@ export(scale_colour_distiller)
 export(scale_colour_fermenter)
 export(scale_colour_gradient)
 export(scale_colour_gradient2)
+export(scale_colour_gradient_div)
+export(scale_colour_gradient_seq)
 export(scale_colour_gradientn)
 export(scale_colour_grey)
 export(scale_colour_hue)
@@ -554,6 +560,8 @@ export(scale_colour_manual)
 export(scale_colour_ordinal)
 export(scale_colour_steps)
 export(scale_colour_steps2)
+export(scale_colour_steps_div)
+export(scale_colour_steps_seq)
 export(scale_colour_stepsn)
 export(scale_colour_viridis_b)
 export(scale_colour_viridis_c)
@@ -571,6 +579,8 @@ export(scale_fill_distiller)
 export(scale_fill_fermenter)
 export(scale_fill_gradient)
 export(scale_fill_gradient2)
+export(scale_fill_gradient_div)
+export(scale_fill_gradient_seq)
 export(scale_fill_gradientn)
 export(scale_fill_grey)
 export(scale_fill_hue)
@@ -579,6 +589,8 @@ export(scale_fill_manual)
 export(scale_fill_ordinal)
 export(scale_fill_steps)
 export(scale_fill_steps2)
+export(scale_fill_steps_div)
+export(scale_fill_steps_seq)
 export(scale_fill_stepsn)
 export(scale_fill_viridis_b)
 export(scale_fill_viridis_c)

NEWS.md

@@ -1,6 +1,10 @@
 
 # ggplot2 (development version)
 
+* `scale_*_gradient()` has been renamed to `scale_*_gradient_seq()`. 
+  `scale_*_gradient2()` has been renamed to `scale_*_gradient_div()`. Old names
+  for these functions are kept as aliases for backward compatibility 
+  (@teunbrand, #5821).
 * When facets coerce the faceting variables to factors, the 'ordered' class
   is dropped (@teunbrand, #5666).
 * `update_geom_defaults()` and `update_stat_defaults()` have a reset mechanism

R/scale-gradient.R

@@ -1,7 +1,7 @@
 #' Gradient colour scales
 #'
-#' `scale_*_gradient` creates a two colour gradient (low-high),
-#' `scale_*_gradient2` creates a diverging colour gradient (low-mid-high),
+#' `scale_*_gradient_seq` creates a sequential, two colour gradient (low-high),
+#' `scale_*_gradient_div` creates a diverging colour gradient (low-mid-high),
 #' `scale_*_gradientn` creates a n-colour gradient. For binned variants of
 #' these scales, see the [color steps][scale_colour_steps] scales.
 #'
@@ -44,10 +44,10 @@
 #' ggplot(df, aes(x, y)) +
 #'   geom_point(aes(colour = z2))
 #'
-#' # For diverging colour scales use gradient2
+#' # For diverging colour scales use gradient_div
 #' ggplot(df, aes(x, y)) +
 #'   geom_point(aes(colour = z1)) +
-#'   scale_colour_gradient2()
+#'   scale_colour_gradient_div()
 #'
 #' # Use your own colour scale with gradientn
 #' ggplot(df, aes(x, y)) +
@@ -62,23 +62,25 @@
 #' # Adjust colour choices with low and high
 #' ggplot(df, aes(x, y)) +
 #'   geom_point(aes(colour = z2)) +
-#'   scale_colour_gradient(low = "white", high = "black")
+#'   scale_colour_gradient_seq(low = "white", high = "black")
 #' # Avoid red-green colour contrasts because ~10% of men have difficulty
 #' # seeing them
 #'
 #'# Use `na.value = NA` to hide missing values but keep the original axis range
 #' ggplot(df_na, aes(x = value, y)) +
 #'   geom_bar(aes(fill = z1), stat = "identity") +
-#'   scale_fill_gradient(low = "yellow", high = "red", na.value = NA)
+#'   scale_fill_gradient_seq(low = "yellow", high = "red", na.value = NA)
 #'
-#'  ggplot(df_na, aes(x, y)) +
-#'    geom_point(aes(colour = z1)) +
-#'    scale_colour_gradient(low = "yellow", high = "red", na.value = NA)
+#' ggplot(df_na, aes(x, y)) +
+#'   geom_point(aes(colour = z1)) +
+#'   scale_colour_gradient_seq(low = "yellow", high = "red", na.value = NA)
 #'
-scale_colour_gradient <- function(name = waiver(), ..., low = "#132B43",
-                                  high = "#56B1F7", space = "Lab",
-                                  na.value = "grey50",
-                                  guide = "colourbar", aesthetics = "colour") {
+scale_colour_gradient_seq <- function(
+    name = waiver(), ..., low = "#132B43",
+    high = "#56B1F7", space = "Lab",
+    na.value = "grey50",
+    guide = "colourbar", aesthetics = "colour") {
+
   continuous_scale(
     aesthetics, name = name,
     palette = pal_seq_gradient(low, high, space),
@@ -89,10 +91,17 @@ scale_colour_gradient <- function(name = waiver(), ..., low = "#132B43",
 
 #' @rdname scale_gradient
 #' @export
-scale_fill_gradient <- function(name = waiver(), ..., low = "#132B43",
-                                high = "#56B1F7", space = "Lab",
-                                na.value = "grey50", guide = "colourbar",
-                                aesthetics = "fill") {
+#' @usage NULL
+scale_colour_gradient <- scale_colour_gradient_seq
+
+#' @rdname scale_gradient
+#' @export
+scale_fill_gradient_seq <- function(
+    name = waiver(), ..., low = "#132B43",
+    high = "#56B1F7", space = "Lab",
+    na.value = "grey50", guide = "colourbar",
+    aesthetics = "fill") {
+
   continuous_scale(
     aesthetics, name = name,
     palette = pal_seq_gradient(low, high, space),
@@ -101,17 +110,24 @@ scale_fill_gradient <- function(name = waiver(), ..., low = "#132B43",
   )
 }
 
+#' @rdname scale_gradient
+#' @export
+#' @usage NULL
+scale_fill_gradient <- scale_fill_gradient_seq
+
 #' @inheritParams scales::pal_div_gradient
 #' @inheritParams continuous_scale
 #' @param midpoint The midpoint (in data value) of the diverging scale.
 #'   Defaults to 0.
 #' @rdname scale_gradient
 #' @export
-scale_colour_gradient2 <- function(name = waiver(), ..., low = muted("red"),
-                                   mid = "white", high = muted("blue"),
-                                   midpoint = 0, space = "Lab", na.value = "grey50",
-                                   transform = "identity", guide = "colourbar",
-                                   aesthetics = "colour") {
+scale_colour_gradient_div <- function(
+    name = waiver(), ..., low = muted("red"),
+    mid = "white", high = muted("blue"),
+    midpoint = 0, space = "Lab", na.value = "grey50",
+    transform = "identity", guide = "colourbar",
+    aesthetics = "colour") {
+
   continuous_scale(
     aesthetics, name = name,
     palette = div_gradient_pal(low, mid, high, space),
@@ -122,11 +138,18 @@ scale_colour_gradient2 <- function(name = waiver(), ..., low = muted("red"),
 
 #' @rdname scale_gradient
 #' @export
-scale_fill_gradient2 <- function(name = waiver(), ..., low = muted("red"),
-                                 mid = "white", high = muted("blue"),
-                                 midpoint = 0, space = "Lab", na.value = "grey50",
-                                 transform = "identity", guide = "colourbar",
-                                 aesthetics = "fill") {
+#' @usage NULL
+scale_colour_gradient2 <- scale_colour_gradient_div
+
+#' @rdname scale_gradient
+#' @export
+scale_fill_gradient_div <- function(
+    name = waiver(), ..., low = muted("red"),
+    mid = "white", high = muted("blue"),
+    midpoint = 0, space = "Lab", na.value = "grey50",
+    transform = "identity", guide = "colourbar",
+    aesthetics = "fill") {
+
   continuous_scale(
     aesthetics, name = name,
     palette = div_gradient_pal(low, mid, high, space),
@@ -135,6 +158,11 @@ scale_fill_gradient2 <- function(name = waiver(), ..., low = muted("red"),
   )
 }
 
+#' @rdname scale_gradient
+#' @export
+#' @usage NULL
+scale_fill_gradient2 <- scale_fill_gradient_div
+
 mid_rescaler <- function(mid, transform = "identity",
                          arg = caller_arg(mid), call = caller_env()) {
   transform <- as.trans(transform)

R/scale-steps.R

@@ -1,7 +1,7 @@
 #' Binned gradient colour scales
 #'
-#' `scale_*_steps` creates a two colour binned gradient (low-high),
-#' `scale_*_steps2` creates a diverging binned colour gradient (low-mid-high),
+#' `scale_*_steps_seq` creates a sequential, two colour binned gradient (low-high),
+#' `scale_*_steps_div` creates a diverging binned colour gradient (low-mid-high),
 #' and `scale_*_stepsn` creates a n-colour binned gradient. These scales are
 #' binned variants of the [gradient scale][scale_colour_gradient] family and
 #' works in the same way.
@@ -35,35 +35,45 @@
 #' # Use scale_colour_steps for a standard binned gradient
 #' ggplot(df, aes(x, y)) +
 #'   geom_point(aes(colour = z1)) +
-#'   scale_colour_steps()
+#'   scale_colour_steps_seq()
 #'
 #' # Get a divergent binned scale with the *2 variant
 #' ggplot(df, aes(x, y)) +
 #'   geom_point(aes(colour = z1)) +
-#'   scale_colour_steps2()
+#'   scale_colour_steps_div()
 #'
 #' # Define your own colour ramp to extract binned colours from
 #' ggplot(df, aes(x, y)) +
 #'   geom_point(aes(colour = z1)) +
 #'   scale_colour_stepsn(colours = terrain.colors(10))
 #' @rdname scale_steps
-scale_colour_steps <- function(name = waiver(), ..., low = "#132B43",
-                               high = "#56B1F7", space = "Lab",
-                               na.value = "grey50", guide = "coloursteps",
-                               aesthetics = "colour") {
+scale_colour_steps_seq <- function(
+    name = waiver(), ..., low = "#132B43",
+    high = "#56B1F7", space = "Lab",
+    na.value = "grey50", guide = "coloursteps",
+    aesthetics = "colour") {
+
   binned_scale(
     aesthetics, name = name,
     palette = pal_seq_gradient(low, high, space),
     na.value = na.value, guide = guide, ...
   )
 }
+
 #' @rdname scale_steps
 #' @export
-scale_colour_steps2 <- function(name = waiver(), ..., low = muted("red"),
-                                mid = "white", high = muted("blue"),
-                                midpoint = 0, space = "Lab", na.value = "grey50",
-                                transform = "identity", guide = "coloursteps",
-                                aesthetics = "colour") {
+#' @usage NULL
+scale_colour_steps <- scale_colour_steps_seq
+
+#' @rdname scale_steps
+#' @export
+scale_colour_steps_div <- function(
+    name = waiver(), ..., low = muted("red"),
+    mid = "white", high = muted("blue"),
+    midpoint = 0, space = "Lab", na.value = "grey50",
+    transform = "identity", guide = "coloursteps",
+    aesthetics = "colour") {
+
   binned_scale(
     aesthetics, name = name,
     palette = div_gradient_pal(low, mid, high, space),
@@ -72,6 +82,12 @@ scale_colour_steps2 <- function(name = waiver(), ..., low = muted("red"),
     ...
   )
 }
+
+#' @rdname scale_steps
+#' @export
+#' @usage NULL
+scale_colour_steps2 <- scale_colour_steps_div
+
 #' @rdname scale_steps
 #' @export
 scale_colour_stepsn <- function(name = waiver(), ..., colours, values = NULL,
@@ -88,24 +104,34 @@ scale_colour_stepsn <- function(name = waiver(), ..., colours, values = NULL,
 }
 #' @rdname scale_steps
 #' @export
-scale_fill_steps <- function(name = waiver(), ..., low = "#132B43",
-                             high = "#56B1F7", space = "Lab",
-                             na.value = "grey50", guide = "coloursteps",
-                             aesthetics = "fill") {
+scale_fill_steps_seq <- function(
+    name = waiver(), ..., low = "#132B43",
+    high = "#56B1F7", space = "Lab",
+    na.value = "grey50", guide = "coloursteps",
+    aesthetics = "fill") {
+
   binned_scale(
     aesthetics, name = name,
     palette = pal_seq_gradient(low, high, space),
     na.value = na.value, guide = guide,
     ...
   )
 }
+
 #' @rdname scale_steps
 #' @export
-scale_fill_steps2 <- function(name = waiver(), ..., low = muted("red"),
-                              mid = "white", high = muted("blue"),
-                              midpoint = 0, space = "Lab", na.value = "grey50",
-                              transform = "identity", guide = "coloursteps",
-                              aesthetics = "fill") {
+#' @usage NULL
+scale_fill_steps <- scale_fill_steps_seq
+
+#' @rdname scale_steps
+#' @export
+scale_fill_steps_div <- function(
+    name = waiver(), ..., low = muted("red"),
+    mid = "white", high = muted("blue"),
+    midpoint = 0, space = "Lab", na.value = "grey50",
+    transform = "identity", guide = "coloursteps",
+    aesthetics = "fill") {
+
   binned_scale(
     aesthetics, name = name,
     palette = div_gradient_pal(low, mid, high, space),
@@ -114,6 +140,12 @@ scale_fill_steps2 <- function(name = waiver(), ..., low = muted("red"),
     ...
   )
 }
+
+#' @rdname scale_steps
+#' @export
+#' @usage NULL
+scale_fill_steps2 <- scale_fill_steps_div
+
 #' @rdname scale_steps
 #' @export
 scale_fill_stepsn <- function(name = waiver(), ..., colours, values = NULL,

R/zxx.R

@@ -175,11 +175,21 @@ scale_color_binned <- scale_colour_binned
 #' @usage NULL
 scale_color_discrete <- scale_colour_discrete
 
+#' @export
+#' @rdname scale_gradient
+#' @usage NULL
+scale_color_gradient_seq <- scale_colour_gradient_seq
+
 #' @export
 #' @rdname scale_gradient
 #' @usage NULL
 scale_color_gradient <- scale_colour_gradient
 
+#' @export
+#' @rdname scale_gradient
+#' @usage NULL
+scale_color_gradient_div <- scale_colour_gradient_div
+
 #' @export
 #' @rdname scale_gradient
 #' @usage NULL
@@ -190,11 +200,21 @@ scale_color_gradient2 <- scale_colour_gradient2
 #' @usage NULL
 scale_color_gradientn <- scale_colour_gradientn
 
+#' @export
+#' @rdname scale_steps
+#' @usage NULL
+scale_color_steps_seq <- scale_colour_steps_seq
+
 #' @export
 #' @rdname scale_steps
 #' @usage NULL
 scale_color_steps <- scale_colour_steps
 
+#' @export
+#' @rdname scale_steps
+#' @usage NULL
+scale_color_steps_div <- scale_colour_steps_div
+
 #' @export
 #' @rdname scale_steps
 #' @usage NULL