Scale name first (#5583)

* name is first scale argument * hotfix for midpoint rescale * add news bullet * document
tidyverse · Dec 14, 2023 · 0f9fb64 · 0f9fb64
1 parent dd7887f
commit 0f9fb64
Show file tree

Hide file tree

Showing 30 changed files with 497 additions and 257 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -1,7 +1,11 @@
 # ggplot2 (development version)
 
+* The `name` argument in most scales is now explicitly the first argument 
+  (#5535)
+
 * New `display` argument in `guide_colourbar()` supplants the `raster` argument.
   In R 4.1.0 and above, `display = "gradient"` will draw a gradient.
+
 * When using `geom_dotplot(binaxis = "x")` with a discrete y-variable, dots are
   now stacked from the y-position rather than from 0 (@teunbrand, #5462)
 

diff --git a/R/scale-alpha.R b/R/scale-alpha.R
@@ -9,6 +9,7 @@
 #'   or [discrete_scale()] as appropriate, to control name, limits,
 #'   breaks, labels and so forth.
 #' @param range Output range of alpha values. Must lie between 0 and 1.
+#' @inheritParams continuous_scale
 #' @family colour scales
 #' @family alpha scales
 #' @seealso
@@ -23,8 +24,8 @@
 #' p
 #' p + scale_alpha("cylinders")
 #' p + scale_alpha(range = c(0.4, 0.8))
-scale_alpha <- function(..., range = c(0.1, 1)) {
-  continuous_scale("alpha", palette = pal_rescale(range), ...)
+scale_alpha <- function(name = waiver(), ..., range = c(0.1, 1)) {
+  continuous_scale("alpha", name = name, palette = pal_rescale(range), ...)
 }
 
 #' @rdname scale_alpha
@@ -33,8 +34,8 @@ scale_alpha_continuous <- scale_alpha
 
 #' @rdname scale_alpha
 #' @export
-scale_alpha_binned <- function(..., range = c(0.1, 1)) {
-  binned_scale("alpha", palette = pal_rescale(range), ...)
+scale_alpha_binned <- function(name = waiver(), ..., range = c(0.1, 1)) {
+  binned_scale("alpha", name = name, palette = pal_rescale(range), ...)
 }
 
 #' @rdname scale_alpha
@@ -48,9 +49,9 @@ scale_alpha_discrete <- function(...) {
 
 #' @rdname scale_alpha
 #' @export
-scale_alpha_ordinal <- function(..., range = c(0.1, 1)) {
+scale_alpha_ordinal <- function(name = waiver(), ..., range = c(0.1, 1)) {
   discrete_scale(
-    "alpha",
+    "alpha", name = name,
     palette = function(n) seq(range[1], range[2], length.out = n),
     ...
   )
@@ -59,13 +60,21 @@ scale_alpha_ordinal <- function(..., range = c(0.1, 1)) {
 #' @rdname scale_alpha
 #' @export
 #' @usage NULL
-scale_alpha_datetime <- function(..., range = c(0.1, 1)) {
-  datetime_scale("alpha", "time", palette = pal_rescale(range), ...)
+scale_alpha_datetime <- function(name = waiver(), ..., range = c(0.1, 1)) {
+  datetime_scale(
+    aesthetics = "alpha", transform = "time", name = name,
+    palette = pal_rescale(range),
+    ...
+  )
 }
 
 #' @rdname scale_alpha
 #' @export
 #' @usage NULL
-scale_alpha_date <- function(..., range = c(0.1, 1)){
-  datetime_scale("alpha", "date", palette = pal_rescale(range), ...)
+scale_alpha_date <- function(name = waiver(), ..., range = c(0.1, 1)){
+  datetime_scale(
+    aesthetics = "alpha", transform = "date", name = name,
+    palette = pal_rescale(range),
+    ...
+  )
 }
diff --git a/R/scale-brewer.R b/R/scale-brewer.R
@@ -83,19 +83,32 @@
 #' # or use blender variants to discretise continuous data
 #' v + scale_fill_fermenter()
 #'
-scale_colour_brewer <- function(..., type = "seq", palette = 1, direction = 1, aesthetics = "colour") {
-  discrete_scale(aesthetics, palette = pal_brewer(type, palette, direction), ...)
+scale_colour_brewer <- function(name = waiver(), ..., type = "seq", palette = 1,
+                                direction = 1, aesthetics = "colour") {
+  discrete_scale(
+    aesthetics, name = name,
+    palette = pal_brewer(type, palette, direction),
+    ...
+  )
 }
 
 #' @export
 #' @rdname scale_brewer
-scale_fill_brewer <- function(..., type = "seq", palette = 1, direction = 1, aesthetics = "fill") {
-  discrete_scale(aesthetics, palette = pal_brewer(type, palette, direction), ...)
+scale_fill_brewer <- function(name = waiver(), ..., type = "seq", palette = 1,
+                              direction = 1, aesthetics = "fill") {
+  discrete_scale(
+    aesthetics, name = name,
+    palette = pal_brewer(type, palette, direction),
+    ...
+  )
 }
 
 #' @export
 #' @rdname scale_brewer
-scale_colour_distiller <- function(..., type = "seq", palette = 1, direction = -1, values = NULL, space = "Lab", na.value = "grey50", guide = "colourbar", aesthetics = "colour") {
+scale_colour_distiller <- function(name = waiver(), ..., type = "seq",
+                                   palette = 1, direction = -1, values = NULL,
+                                   space = "Lab", na.value = "grey50",
+                                   guide = "colourbar", aesthetics = "colour") {
   # warn about using a qualitative brewer palette to generate the gradient
   type <- arg_match0(type, c("seq", "div", "qual"))
   if (type == "qual") {
@@ -105,7 +118,7 @@ scale_colour_distiller <- function(..., type = "seq", palette = 1, direction = -
     ))
   }
   continuous_scale(
-    aesthetics,
+    aesthetics, name = name,
     palette = pal_gradient_n(pal_brewer(type, palette, direction)(7), values, space),
     na.value = na.value, guide = guide, ...
   )
@@ -115,7 +128,10 @@ scale_colour_distiller <- function(..., type = "seq", palette = 1, direction = -
 
 #' @export
 #' @rdname scale_brewer
-scale_fill_distiller <- function(..., type = "seq", palette = 1, direction = -1, values = NULL, space = "Lab", na.value = "grey50", guide = "colourbar", aesthetics = "fill") {
+scale_fill_distiller <- function(name = waiver(), ..., type = "seq",
+                                 palette = 1, direction = -1, values = NULL,
+                                 space = "Lab", na.value = "grey50",
+                                 guide = "colourbar", aesthetics = "fill") {
   type <- arg_match0(type, c("seq", "div", "qual"))
   if (type == "qual") {
     cli::cli_warn(c(
@@ -124,15 +140,18 @@ scale_fill_distiller <- function(..., type = "seq", palette = 1, direction = -1,
     ))
   }
   continuous_scale(
-    aesthetics,
+    aesthetics, name = name,
     palette = pal_gradient_n(pal_brewer(type, palette, direction)(7), values, space),
     na.value = na.value, guide = guide, ...
   )
 }
 
 #' @export
 #' @rdname scale_brewer
-scale_colour_fermenter <- function(..., type = "seq", palette = 1, direction = -1, na.value = "grey50", guide = "coloursteps", aesthetics = "colour") {
+scale_colour_fermenter <- function(name = waiver(), ..., type = "seq",
+                                   palette = 1, direction = -1,
+                                   na.value = "grey50", guide = "coloursteps",
+                                   aesthetics = "colour") {
   # warn about using a qualitative brewer palette to generate the gradient
   type <- arg_match0(type, c("seq", "div", "qual"))
   if (type == "qual") {
@@ -141,18 +160,30 @@ scale_colour_fermenter <- function(..., type = "seq", palette = 1, direction = -
       "i" = "Consider using {.code type = \"seq\"} or {.code type = \"div\"} instead"
     ))
   }
-  binned_scale(aesthetics, palette = pal_binned(pal_brewer(type, palette, direction)), na.value = na.value, guide = guide, ...)
+  binned_scale(
+    aesthetics, name = name,
+    palette = pal_binned(pal_brewer(type, palette, direction)),
+    na.value = na.value, guide = guide,
+    ...
+  )
 }
 
 #' @export
 #' @rdname scale_brewer
-scale_fill_fermenter <- function(..., type = "seq", palette = 1, direction = -1, na.value = "grey50", guide = "coloursteps", aesthetics = "fill") {
+scale_fill_fermenter <- function(name = waiver(), ..., type = "seq", palette = 1,
+                                 direction = -1, na.value = "grey50",
+                                 guide = "coloursteps", aesthetics = "fill") {
   type <- arg_match0(type, c("seq", "div", "qual"))
   if (type == "qual") {
     cli::cli_warn(c(
       "Using a discrete colour palette in a binned scale",
       "i" = "Consider using {.code type = \"seq\"} or {.code type = \"div\"} instead"
     ))
   }
-  binned_scale(aesthetics, palette = pal_binned(pal_brewer(type, palette, direction)), na.value = na.value, guide = guide, ...)
+  binned_scale(
+    aesthetics, name = name,
+    palette = pal_binned(pal_brewer(type, palette, direction)),
+    na.value = na.value, guide = guide,
+    ...
+  )
 }
diff --git a/R/scale-discrete-.R b/R/scale-discrete-.R
@@ -61,18 +61,28 @@
 #'   geom_point() +
 #'   scale_x_discrete(labels = abbreviate)
 #' }
-scale_x_discrete <- function(..., expand = waiver(), guide = waiver(), position = "bottom") {
-  sc <- discrete_scale(c("x", "xmin", "xmax", "xend"), palette = identity, ...,
-    expand = expand, guide = guide, position = position, super = ScaleDiscretePosition)
+scale_x_discrete <- function(name = waiver(), ..., expand = waiver(),
+                             guide = waiver(), position = "bottom") {
+  sc <- discrete_scale(
+    aesthetics = c("x", "xmin", "xmax", "xend"), name = name,
+    palette = identity, ...,
+    expand = expand, guide = guide, position = position,
+    super = ScaleDiscretePosition
+  )
 
   sc$range_c <- ContinuousRange$new()
   sc
 }
 #' @rdname scale_discrete
 #' @export
-scale_y_discrete <- function(..., expand = waiver(), guide = waiver(), position = "left") {
-  sc <- discrete_scale(c("y", "ymin", "ymax", "yend"), palette = identity, ...,
-    expand = expand, guide = guide, position = position, super = ScaleDiscretePosition)
+scale_y_discrete <- function(name = waiver(), ..., expand = waiver(),
+                             guide = waiver(), position = "left") {
+  sc <- discrete_scale(
+    aesthetics = c("y", "ymin", "ymax", "yend"), name = name,
+    palette = identity, ...,
+    expand = expand, guide = guide, position = position,
+    super = ScaleDiscretePosition
+  )
 
   sc$range_c <- ContinuousRange$new()
   sc

diff --git a/R/scale-gradient.R b/R/scale-gradient.R
@@ -75,18 +75,30 @@
 #'    geom_point(aes(colour = z1)) +
 #'    scale_colour_gradient(low = "yellow", high = "red", na.value = NA)
 #'
-scale_colour_gradient <- function(..., low = "#132B43", high = "#56B1F7", space = "Lab",
-                                  na.value = "grey50", guide = "colourbar", aesthetics = "colour") {
-  continuous_scale(aesthetics, palette = pal_seq_gradient(low, high, space),
-    na.value = na.value, guide = guide, ...)
+scale_colour_gradient <- 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),
+    na.value = na.value, guide = guide,
+    ...
+  )
 }
 
 #' @rdname scale_gradient
 #' @export
-scale_fill_gradient <- function(..., low = "#132B43", high = "#56B1F7", space = "Lab",
-                                na.value = "grey50", guide = "colourbar", aesthetics = "fill") {
-  continuous_scale(aesthetics, palette = pal_seq_gradient(low, high, space),
-    na.value = na.value, guide = guide, ...)
+scale_fill_gradient <- 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),
+    na.value = na.value, guide = guide,
+    ...
+  )
 }
 
 #' @inheritParams scales::pal_div_gradient
@@ -95,12 +107,13 @@ scale_fill_gradient <- function(..., low = "#132B43", high = "#56B1F7", space =
 #'   Defaults to 0.
 #' @rdname scale_gradient
 #' @export
-scale_colour_gradient2 <- function(..., low = muted("red"), mid = "white", high = muted("blue"),
+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") {
   continuous_scale(
-    aesthetics,
+    aesthetics, name = name,
     palette = div_gradient_pal(low, mid, high, space),
     na.value = na.value, transform = transform, guide = guide, ...,
     rescaler = mid_rescaler(mid = midpoint, transform = transform)
@@ -109,12 +122,13 @@ scale_colour_gradient2 <- function(..., low = muted("red"), mid = "white", high
 
 #' @rdname scale_gradient
 #' @export
-scale_fill_gradient2 <- function(..., low = muted("red"), mid = "white", high = muted("blue"),
+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") {
   continuous_scale(
-    aesthetics,
+    aesthetics, name = name,
     palette = div_gradient_pal(low, mid, high, space),
     na.value = na.value, transform = transform, guide = guide, ...,
     rescaler = mid_rescaler(mid = midpoint, transform = transform)
@@ -138,24 +152,28 @@ mid_rescaler <- function(mid, transform = "identity",
 #' @param colours,colors Vector of colours to use for n-colour gradient.
 #' @rdname scale_gradient
 #' @export
-scale_colour_gradientn <- function(..., colours, values = NULL, space = "Lab", na.value = "grey50",
-                                   guide = "colourbar", aesthetics = "colour", colors) {
+scale_colour_gradientn <- function(name = waiver(), ..., colours, values = NULL,
+                                   space = "Lab", na.value = "grey50",
+                                   guide = "colourbar", aesthetics = "colour",
+                                   colors) {
   colours <- if (missing(colours)) colors else colours
 
   continuous_scale(
-    aesthetics,
+    aesthetics, name = name,
     palette = pal_gradient_n(colours, values, space),
     na.value = na.value, guide = guide, ...
   )
 }
 #' @rdname scale_gradient
 #' @export
-scale_fill_gradientn <- function(..., colours, values = NULL, space = "Lab", na.value = "grey50",
-                                 guide = "colourbar", aesthetics = "fill", colors) {
+scale_fill_gradientn <- function(name = waiver(), ..., colours, values = NULL,
+                                 space = "Lab", na.value = "grey50",
+                                 guide = "colourbar", aesthetics = "fill",
+                                 colors) {
   colours <- if (missing(colours)) colors else colours
 
   continuous_scale(
-    aesthetics,
+    aesthetics, name = name,
     palette = pal_gradient_n(colours, values, space),
     na.value = na.value, guide = guide, ...
   )

diff --git a/R/scale-grey.R b/R/scale-grey.R
@@ -27,14 +27,22 @@
 #' ggplot(mtcars, aes(mpg, wt)) +
 #'   geom_point(aes(colour = miss)) +
 #'   scale_colour_grey(na.value = "green")
-scale_colour_grey <- function(..., start = 0.2, end = 0.8, na.value = "red", aesthetics = "colour") {
-  discrete_scale(aesthetics, palette = pal_grey(start, end),
-    na.value = na.value, ...)
+scale_colour_grey <- function(name = waiver(), ..., start = 0.2, end = 0.8,
+                              na.value = "red", aesthetics = "colour") {
+  discrete_scale(
+    aesthetics, name = name,
+    palette = pal_grey(start, end),
+    na.value = na.value, ...
+  )
 }
 
 #' @rdname scale_grey
 #' @export
-scale_fill_grey <- function(..., start = 0.2, end = 0.8, na.value = "red", aesthetics = "fill") {
-  discrete_scale(aesthetics, palette = pal_grey(start, end),
-    na.value = na.value, ...)
+scale_fill_grey <- function(name = waiver(), ..., start = 0.2, end = 0.8,
+                            na.value = "red", aesthetics = "fill") {
+  discrete_scale(
+    aesthetics, name = name,
+    palette = pal_grey(start, end),
+    na.value = na.value, ...
+  )
 }