Rename trans arguments to transform

NEWS.md

@@ -1,5 +1,8 @@
 # ggplot2 (development version)
 
+* The `trans` argument in scales and secondary axes has been renamed to 
+  `transform`. The `trans` argument itself is deprecated (#5558).
+
 * Contour functions will not fail when `options("OutDec")` is not `.` (@eliocamp, #5555).
 
 * The `legend.key` theme element is set to inherit from the `panel.background`

R/axis-secondary.R

@@ -4,7 +4,9 @@
 #' secondary axis, positioned opposite of the primary axis. All secondary
 #' axes must be based on a one-to-one transformation of the primary axes.
 #'
-#' @param trans A formula or function of transformation
+#' @param transform A formula or function of transformation
+#'
+#' @param trans `r lifecycle::badge("deprecated")`
 #'
 #' @param name The name of the secondary axis
 #'
@@ -94,14 +96,20 @@
 #'   )
 #'
 #' @export
-sec_axis <- function(trans = NULL, name = waiver(), breaks = waiver(), labels = waiver(),
-                     guide = waiver()) {
+sec_axis <- function(transform = NULL,
+                     name = waiver(), breaks = waiver(), labels = waiver(),
+                     guide = waiver(), trans = lifecycle::deprecated()) {
+  if (lifecycle::is_present(trans)) {
+    deprecate_soft0("3.5.0", "sec_axis(trans)", "sec_axis(transform)")
+    transform <- trans
+  }
+
   # sec_axis() historically accepted two-sided formula, so be permissive.
-  if (length(trans) > 2) trans <- trans[c(1,3)]
+  if (length(transform) > 2) transform <- transform[c(1,3)]
 
-  trans <- as_function(trans)
+  transform <- as_function(transform)
   ggproto(NULL, AxisSecondary,
-    trans = trans,
+    trans = transform,
     name = name,
     breaks = breaks,
     labels = labels,
@@ -111,8 +119,9 @@ sec_axis <- function(trans = NULL, name = waiver(), breaks = waiver(), labels =
 #' @rdname sec_axis
 #'
 #' @export
-dup_axis <- function(trans = ~., name = derive(), breaks = derive(), labels = derive(), guide = derive()) {
-  sec_axis(trans, name, breaks, labels, guide)
+dup_axis <- function(transform = ~., trans = lifecycle::deprecated(),
+                     name = derive(), breaks = derive(), labels = derive(), guide = derive()) {
+  sec_axis(transform, trans = trans, name, breaks, labels, guide)
 }
 
 is.sec_axis <- function(x) {

R/fortify-multcomp.R

@@ -22,7 +22,7 @@
 #' ggplot(mapping = aes(lhs, estimate)) +
 #'    geom_linerange(aes(ymin = lwr, ymax = upr), data = CI) +
 #'    geom_point(aes(size = p), data = summary(wht)) +
-#'    scale_size(trans = "reverse")
+#'    scale_size(transform = "reverse")
 #'
 #' cld <- cld(wht)
 #' fortify(cld)

R/guide-axis-logticks.R

@@ -55,7 +55,7 @@ NULL
 #'   geom_density() +
 #'   scale_x_continuous(
 #'     breaks = c(-10^(4:0), 0, 10^(0:4)),
-#'     trans = "pseudo_log"
+#'     transform = "pseudo_log"
 #'   )
 #'
 #' # The log ticks are mirrored when 0 is included

R/limits.R

@@ -122,7 +122,7 @@ limits.numeric <- function(lims, var, call = caller_env()) {
     trans <- "identity"
   }
 
-  make_scale("continuous", var, limits = lims, trans = trans, call = call)
+  make_scale("continuous", var, limits = lims, transform = trans, call = call)
 }
 
 make_scale <- function(type, var, ..., call = NULL) {

R/scale-.R

@@ -65,18 +65,20 @@
 #'   - [scales::squish()] for squishing out of bounds values into range.
 #'   - [scales::squish_infinite()] for squishing infinite values into range.
 #' @param na.value Missing values will be replaced with this value.
-#' @param trans For continuous scales, the name of a transformation object
+#' @param transform For continuous scales, the name of a transformation object
 #'   or the object itself. Built-in transformations include "asn", "atanh",
 #'   "boxcox", "date", "exp", "hms", "identity", "log", "log10", "log1p", "log2",
 #'   "logit", "modulus", "probability", "probit", "pseudo_log", "reciprocal",
 #'   "reverse", "sqrt" and "time".
 #'
 #'   A transformation object bundles together a transform, its inverse,
 #'   and methods for generating breaks and labels. Transformation objects
-#'   are defined in the scales package, and are called `<name>_trans`. If
+#'   are defined in the scales package, and are called `transform_<name>`. If
 #'   transformations require arguments, you can call them from the scales
 #'   package, e.g. [`scales::transform_boxcox(p = 2)`][scales::transform_boxcox].
 #'   You can create your own transformation with [scales::new_transform()].
+#' @param trans `r lifecycle::badge("deprecated")` Deprecated in favour of
+#'   `transform`.
 #' @param guide A function used to create a guide or its name. See
 #'   [guides()] for more information.
 #' @param expand For position scales, a vector of range expansion constants used to add some
@@ -94,13 +96,18 @@ continuous_scale <- function(aesthetics, scale_name = deprecated(), palette, nam
                              breaks = waiver(), minor_breaks = waiver(), n.breaks = NULL,
                              labels = waiver(), limits = NULL, rescaler = rescale,
                              oob = censor, expand = waiver(), na.value = NA_real_,
-                             trans = "identity", guide = "legend", position = "left",
+                             transform = "identity", trans = lifecycle::deprecated(),
+                             guide = "legend", position = "left",
                              call = caller_call(),
                              super = ScaleContinuous) {
   call <- call %||% current_call()
   if (lifecycle::is_present(scale_name)) {
     deprecate_soft0("3.5.0", "continuous_scale(scale_name)")
   }
+  if (lifecycle::is_present(trans)) {
+    deprecate_soft0("3.5.0", "continuous_scale(trans)", "continuous_scale(transform)")
+    transform <- trans
+  }
 
   aesthetics <- standardise_aes_names(aesthetics)
 
@@ -113,9 +120,9 @@ continuous_scale <- function(aesthetics, scale_name = deprecated(), palette, nam
     guide <- "none"
   }
 
-  trans <- as.transform(trans)
+  transform <- as.transform(transform)
   if (!is.null(limits) && !is.function(limits)) {
-    limits <- trans$transform(limits)
+    limits <- transform$transform(limits)
   }
 
   # Convert formula to function if appropriate
@@ -134,7 +141,7 @@ continuous_scale <- function(aesthetics, scale_name = deprecated(), palette, nam
 
     range = ContinuousRange$new(),
     limits = limits,
-    trans = trans,
+    trans = transform,
     na.value = na.value,
     expand = expand,
     rescaler = rescaler,
@@ -259,13 +266,19 @@ binned_scale <- function(aesthetics, scale_name = deprecated(), palette, name =
                          breaks = waiver(), labels = waiver(), limits = NULL,
                          rescaler = rescale, oob = squish, expand = waiver(),
                          na.value = NA_real_, n.breaks = NULL, nice.breaks = TRUE,
-                         right = TRUE, trans = "identity", show.limits = FALSE,
+                         right = TRUE, transform = "identity",
+                         trans = lifecycle::deprecated(), show.limits = FALSE,
                          guide = "bins", position = "left",
                          call = caller_call(),
                          super = ScaleBinned) {
   if (lifecycle::is_present(scale_name)) {
     deprecate_soft0("3.5.0", "binned_scale(scale_name)")
   }
+  if (lifecycle::is_present(trans)) {
+    deprecate_soft0("3.5.0", "binned_scale(trans)", "binned_scale(transform)")
+    transform <- trans
+  }
+
   call <- call %||% current_call()
 
   aesthetics <- standardise_aes_names(aesthetics)
@@ -278,9 +291,9 @@ binned_scale <- function(aesthetics, scale_name = deprecated(), palette, name =
     guide <- "none"
   }
 
-  trans <- as.transform(trans)
+  transform <- as.transform(transform)
   if (!is.null(limits)) {
-    limits <- trans$transform(limits)
+    limits <- transform$transform(limits)
   }
 
   # Convert formula input to function if appropriate
@@ -298,7 +311,7 @@ binned_scale <- function(aesthetics, scale_name = deprecated(), palette, name =
 
     range = ContinuousRange$new(),
     limits = limits,
-    trans = trans,
+    trans = transform,
     na.value = na.value,
     expand = expand,
     rescaler = rescaler,

R/scale-binned.R

@@ -26,14 +26,17 @@ NULL
 scale_x_binned <- function(name = waiver(), n.breaks = 10, nice.breaks = TRUE,
                            breaks = waiver(), labels = waiver(), limits = NULL,
                            expand = waiver(), oob = squish, na.value = NA_real_,
-                           right = TRUE, show.limits = FALSE, trans = "identity",
+                           right = TRUE, show.limits = FALSE, transform = "identity",
+                           trans = lifecycle::deprecated(),
                            guide = waiver(), position = "bottom") {
   binned_scale(
     ggplot_global$x_aes,
     palette = identity, name = name, breaks = breaks,
-    labels = labels, limits = limits, expand = expand, oob = oob, na.value = na.value,
-    n.breaks = n.breaks, nice.breaks = nice.breaks, right = right, trans = trans,
-    show.limits = show.limits, guide = guide, position = position, super = ScaleBinnedPosition
+    labels = labels, limits = limits, expand = expand, oob = oob,
+    na.value = na.value, n.breaks = n.breaks, nice.breaks = nice.breaks,
+    right = right, transform = transform, trans = trans,
+    show.limits = show.limits, guide = guide, position = position,
+    super = ScaleBinnedPosition
   )
 }
 
@@ -43,14 +46,16 @@ scale_x_binned <- function(name = waiver(), n.breaks = 10, nice.breaks = TRUE,
 scale_y_binned <- function(name = waiver(), n.breaks = 10, nice.breaks = TRUE,
                            breaks = waiver(), labels = waiver(), limits = NULL,
                            expand = waiver(), oob = squish, na.value = NA_real_,
-                           right = TRUE, show.limits = FALSE, trans = "identity",
+                           right = TRUE, show.limits = FALSE, transform = "identity",
+                           trans = lifecycle::deprecated(),
                            guide = waiver(), position = "left") {
   binned_scale(
     ggplot_global$y_aes,
     palette = identity, name = name, breaks = breaks,
     labels = labels, limits = limits, expand = expand, oob = oob, na.value = na.value,
-    n.breaks = n.breaks, nice.breaks = nice.breaks, right = right, trans = trans,
-    show.limits = show.limits, guide = guide, position = position, super = ScaleBinnedPosition
+    n.breaks = n.breaks, nice.breaks = nice.breaks, right = right,
+    transform = transform, trans = trans, show.limits = show.limits,
+    guide = guide, position = position, super = ScaleBinnedPosition
   )
 }
 

R/scale-continuous.R

@@ -2,7 +2,7 @@
 #'
 #' `scale_x_continuous()` and `scale_y_continuous()` are the default
 #' scales for continuous x and y aesthetics. There are three variants
-#' that set the `trans` argument for commonly used transformations:
+#' that set the `transform` argument for commonly used transformations:
 #' `scale_*_log10()`, `scale_*_sqrt()` and `scale_*_reverse()`.
 #'
 #' For simple manipulation of labels and limits, you may wish to use
@@ -64,7 +64,7 @@
 #' p1 + scale_y_reverse()
 #'
 #' # Or you can supply a transformation in the `trans` argument:
-#' p1 + scale_y_continuous(trans = scales::transform_reciprocal())
+#' p1 + scale_y_continuous(transform = scales::transform_reciprocal())
 #'
 #' # You can also create your own. See ?scales::new_transform
 #'
@@ -81,7 +81,8 @@ scale_x_continuous <- function(name = waiver(), breaks = waiver(),
                                minor_breaks = waiver(), n.breaks = NULL,
                                labels = waiver(), limits = NULL,
                                expand = waiver(), oob = censor,
-                               na.value = NA_real_, trans = "identity",
+                               na.value = NA_real_, transform = "identity",
+                               trans = lifecycle::deprecated(),
                                guide = waiver(), position = "bottom",
                                sec.axis = waiver()) {
   call <- caller_call()
@@ -92,8 +93,8 @@ scale_x_continuous <- function(name = waiver(), breaks = waiver(),
     ggplot_global$x_aes,
     palette = identity, name = name, breaks = breaks, n.breaks = n.breaks,
     minor_breaks = minor_breaks, labels = labels, limits = limits,
-    expand = expand, oob = oob, na.value = na.value, trans = trans,
-    guide = guide, position = position, call = call,
+    expand = expand, oob = oob, na.value = na.value, transform = transform,
+    trans = trans, guide = guide, position = position, call = call,
     super = ScaleContinuousPosition
   )
 
@@ -107,7 +108,8 @@ scale_y_continuous <- function(name = waiver(), breaks = waiver(),
                                minor_breaks = waiver(), n.breaks = NULL,
                                labels = waiver(), limits = NULL,
                                expand = waiver(), oob = censor,
-                               na.value = NA_real_, trans = "identity",
+                               na.value = NA_real_, transform = "identity",
+                               trans = lifecycle::deprecated(),
                                guide = waiver(), position = "left",
                                sec.axis = waiver()) {
   call <- caller_call()
@@ -118,8 +120,8 @@ scale_y_continuous <- function(name = waiver(), breaks = waiver(),
     ggplot_global$y_aes,
     palette = identity, name = name, breaks = breaks, n.breaks = n.breaks,
     minor_breaks = minor_breaks, labels = labels, limits = limits,
-    expand = expand, oob = oob, na.value = na.value, trans = trans,
-    guide = guide, position = position, call = call,
+    expand = expand, oob = oob, na.value = na.value, transform = transform,
+    trans = trans, guide = guide, position = position, call = call,
     super = ScaleContinuousPosition
   )
 
@@ -169,30 +171,30 @@ ScaleContinuousPosition <- ggproto("ScaleContinuousPosition", ScaleContinuous,
 #' @rdname scale_continuous
 #' @export
 scale_x_log10 <- function(...) {
-  scale_x_continuous(..., trans = transform_log10())
+  scale_x_continuous(..., transform = transform_log10())
 }
 #' @rdname scale_continuous
 #' @export
 scale_y_log10 <- function(...) {
-  scale_y_continuous(..., trans = transform_log10())
+  scale_y_continuous(..., transform = transform_log10())
 }
 #' @rdname scale_continuous
 #' @export
 scale_x_reverse <- function(...) {
-  scale_x_continuous(..., trans = transform_reverse())
+  scale_x_continuous(..., transform = transform_reverse())
 }
 #' @rdname scale_continuous
 #' @export
 scale_y_reverse <- function(...) {
-  scale_y_continuous(..., trans = transform_reverse())
+  scale_y_continuous(..., transform = transform_reverse())
 }
 #' @rdname scale_continuous
 #' @export
 scale_x_sqrt <- function(...) {
-  scale_x_continuous(..., trans = transform_sqrt())
+  scale_x_continuous(..., transform = transform_sqrt())
 }
 #' @rdname scale_continuous
 #' @export
 scale_y_sqrt <- function(...) {
-  scale_y_continuous(..., trans = transform_sqrt())
+  scale_y_continuous(..., transform = transform_sqrt())
 }

R/scale-date.R

@@ -242,7 +242,7 @@ scale_x_time <- function(name = waiver(),
     na.value = na.value,
     guide = guide,
     position = position,
-    trans = scales::transform_hms(),
+    transform = scales::transform_hms(),
     sec.axis = sec.axis
   )
 }
@@ -273,7 +273,7 @@ scale_y_time <- function(name = waiver(),
     na.value = na.value,
     guide = guide,
     position = position,
-    trans = scales::transform_hms(),
+    transform = scales::transform_hms(),
     sec.axis = sec.axis
   )
 }
@@ -288,8 +288,8 @@ scale_y_time <- function(name = waiver(),
 #'
 #' @export
 #' @keywords internal
-datetime_scale <- function(aesthetics, trans, palette,
-                           breaks = pretty_breaks(), minor_breaks = waiver(),
+datetime_scale <- function(aesthetics, transform, trans = lifecycle::deprecated(),
+                           palette, breaks = pretty_breaks(), minor_breaks = waiver(),
                            labels = waiver(), date_breaks = waiver(),
                            date_labels = waiver(),
                            date_minor_breaks = waiver(), timezone = NULL,
@@ -317,15 +317,15 @@ datetime_scale <- function(aesthetics, trans, palette,
   # ScaleContinuousDatetime; others use ScaleContinuous
   if (all(aesthetics %in% c("x", "xmin", "xmax", "xend", "y", "ymin", "ymax", "yend"))) {
     scale_class <- switch(
-      trans,
+      transform,
       date = ScaleContinuousDate,
       time = ScaleContinuousDatetime
     )
   } else {
     scale_class <- ScaleContinuous
   }
 
-  trans <- switch(trans,
+  transform <- switch(transform,
     date = transform_date(),
     time = transform_time(timezone)
   )
@@ -337,6 +337,7 @@ datetime_scale <- function(aesthetics, trans, palette,
     minor_breaks = minor_breaks,
     labels = labels,
     guide = guide,
+    transform = transform,
     trans = trans,
     call = call,
     ...,