Rename coord_trans() to coord_transform() (#6046)

* rename coord_trans to coord_transform, issue #5825

* Update _pkgdown.yml

* add deprecated function to pkgdown

* revert NEWS.md revision

* simplify alias

* class alias

* reoxygenate

* remove duplicate news entries

---------

Co-authored-by: Teun van den Brand <[email protected]>
Co-authored-by: Teun van den Brand <[email protected]>

Author: nmercadeb

NAMESPACE

@@ -168,6 +168,7 @@ export(CoordQuickmap)
 export(CoordRadial)
 export(CoordSf)
 export(CoordTrans)
+export(CoordTransform)
 export(Facet)
 export(FacetGrid)
 export(FacetNull)
@@ -322,6 +323,7 @@ export(coord_quickmap)
 export(coord_radial)
 export(coord_sf)
 export(coord_trans)
+export(coord_transform)
 export(cut_interval)
 export(cut_number)
 export(cut_width)

NEWS.md

@@ -280,6 +280,7 @@
   (@teunbrand, #5938, #4327).
 * Fixed bug where empty discrete scales weren't recognised as such
   (@teunbrand, #5945).
+* `coord_trans()` renamed to `coord_transform()` (@nmercadeb, #5825).
 * (internal) The summary function of `stat_summary()` and `stat_summary_bin()`
   is setup once in total instead of once per group (@teunbrand, #5971)
 * `facet_grid(space = "free")` can now be combined with `coord_fixed()`

R/annotation-logticks.R

@@ -24,7 +24,7 @@
 #' @param scaled is the data already log-scaled? This should be `TRUE`
 #'   (default) when the data is already transformed with `log10()` or when
 #'   using `scale_y_log10()`. It should be `FALSE` when using
-#'   `coord_trans(y = "log10")`.
+#'   `coord_transform(y = "log10")`.
 #' @param colour Colour of the tick marks.
 #' @param linewidth Thickness of tick marks, in mm.
 #' @param linetype Linetype of tick marks (`solid`, `dashed`, etc.)
@@ -36,7 +36,7 @@
 #' @export
 #' @seealso [scale_y_continuous()], [scale_y_log10()] for log scale
 #'   transformations.
-#' @seealso [coord_trans()] for log coordinate transformations.
+#' @seealso [coord_transform()] for log coordinate transformations.
 #'
 #' @examples
 #' # Make a log-log plot (without log ticks)
@@ -75,7 +75,7 @@
 #' # Using a coordinate transform requires scaled = FALSE
 #' t <- ggplot(msleep, aes(bodywt, brainwt)) +
 #'   geom_point() +
-#'   coord_trans(x = "log10", y = "log10") +
+#'   coord_transform(x = "log10", y = "log10") +
 #'   theme_bw()
 #' t + annotation_logticks(scaled = FALSE)
 #'

R/coord-.R

@@ -1,6 +1,6 @@
 #' @section Coordinate systems:
 #'
-#' All `coord_*()` functions (like `coord_trans()`) return a `Coord*`
+#' All `coord_*()` functions (like `coord_transform()`) return a `Coord*`
 #' object (like `CoordTrans`).
 #'
 #' Each of the `Coord*` objects is a [ggproto()] object,
@@ -16,7 +16,7 @@
 #'   - `backtransform_range(panel_params)`: Extracts the panel range provided
 #'     in `panel_params` (created by `setup_panel_params()`, see below) and
 #'     back-transforms to data coordinates. This back-transformation can be needed
-#'     for coords such as `coord_trans()` where the range in the transformed
+#'     for coords such as `coord_transform()` where the range in the transformed
 #'     coordinates differs from the range in the untransformed coordinates. Returns
 #'     a list of two ranges, `x` and `y`, and these correspond to the variables
 #'     mapped to the `x` and `y` aesthetics, even for coords such as `coord_flip()`

R/coord-transform.R

@@ -1,16 +1,19 @@
 #' Transformed Cartesian coordinate system
 #'
-#' `coord_trans()` is different to scale transformations in that it occurs after
+#' `coord_transform()` is different to scale transformations in that it occurs after
 #' statistical transformation and will affect the visual appearance of geoms - there is
 #' no guarantee that straight lines will continue to be straight.
 #'
 #' Transformations only work with continuous values: see
 #' [scales::new_transform()] for list of transformations, and instructions
 #' on how to create your own.
 #'
+#' The `coord_trans()` function is deprecated in favour of `coord_transform()`.
+#'
 #' @inheritParams coord_cartesian
 #' @param x,y Transformers for x and y axes or their names.
 #' @param limx,limy `r lifecycle::badge("deprecated")` use `xlim` and `ylim` instead.
+#' @param ... Arguments forwarded to `coord_transform()`.
 #' @seealso
 #' The `r link_book("coord transformations section", "coord#transformations-with-coord_trans")`
 #' @export
@@ -30,7 +33,7 @@
 #' #  * by transforming the coordinate system:
 #' ggplot(diamonds, aes(carat, price)) +
 #'   geom_point() +
-#'   coord_trans(x = "log10", y = "log10")
+#'   coord_transform(x = "log10", y = "log10")
 #'
 #' # The difference between transforming the scales and
 #' # transforming the coordinate system is that scale
@@ -49,7 +52,7 @@
 #' ggplot(d, aes(carat, price)) +
 #'   geom_point() +
 #'   geom_smooth(method = "lm") +
-#'   coord_trans(x = "log10", y = "log10")
+#'   coord_transform(x = "log10", y = "log10")
 #'
 #' # Here I used a subset of diamonds so that the smoothed line didn't
 #' # drop below zero, which obviously causes problems on the log-transformed
@@ -62,7 +65,7 @@
 #'   geom_smooth(method = "lm") +
 #'   scale_x_log10() +
 #'   scale_y_log10() +
-#'   coord_trans(x = scales::transform_exp(10), y = scales::transform_exp(10))
+#'   coord_transform(x = scales::transform_exp(10), y = scales::transform_exp(10))
 #'
 #' # cf.
 #' ggplot(diamonds, aes(carat, price)) +
@@ -74,18 +77,18 @@
 #' df <- data.frame(a = abs(rnorm(26)),letters)
 #' plot <- ggplot(df,aes(a,letters)) + geom_point()
 #'
-#' plot + coord_trans(x = "log10")
-#' plot + coord_trans(x = "sqrt")
+#' plot + coord_transform(x = "log10")
+#' plot + coord_transform(x = "sqrt")
 #' }
-coord_trans <- function(x = "identity", y = "identity", xlim = NULL, ylim = NULL,
-                        limx = deprecated(), limy = deprecated(), clip = "on",
-                        expand = TRUE, reverse = "none") {
+coord_transform <- function(x = "identity", y = "identity", xlim = NULL, ylim = NULL,
+                            limx = deprecated(), limy = deprecated(), clip = "on",
+                            expand = TRUE, reverse = "none") {
   if (lifecycle::is_present(limx)) {
-    deprecate_warn0("3.3.0", "coord_trans(limx)", "coord_trans(xlim)")
+    deprecate_warn0("3.3.0", "coord_transform(limx)", "coord_transform(xlim)")
     xlim <- limx
   }
   if (lifecycle::is_present(limy)) {
-    deprecate_warn0("3.3.0", "coord_trans(limy)", "coord_trans(ylim)")
+    deprecate_warn0("3.3.0", "coord_transform(limy)", "coord_transform(ylim)")
     ylim <- limy
   }
 
@@ -96,7 +99,8 @@ coord_trans <- function(x = "identity", y = "identity", xlim = NULL, ylim = NULL
   if (is.character(x)) x <- as.transform(x)
   if (is.character(y)) y <- as.transform(y)
 
-  ggproto(NULL, CoordTrans,
+  ggproto(
+    NULL, CoordTransform,
     trans = list(x = x, y = y),
     limits = list(x = xlim, y = ylim),
     expand = expand,
@@ -105,12 +109,23 @@ coord_trans <- function(x = "identity", y = "identity", xlim = NULL, ylim = NULL
   )
 }
 
+#' @rdname coord_transform
+#' @export
+coord_trans <- function(...) {
+  deprecate_soft0(
+    "3.5.2",
+    "coord_trans()",
+    "coord_transform()"
+  )
+  coord_transform(...)
+}
 
 #' @rdname ggplot2-ggproto
 #' @format NULL
 #' @usage NULL
 #' @export
-CoordTrans <- ggproto("CoordTrans", Coord,
+CoordTransform <- ggproto(
+  "CoordTransform", Coord,
   is_free = function() TRUE,
   distance = function(self, x, y, panel_params) {
     max_dist <- dist_euclidean(panel_params$x.range, panel_params$y.range)
@@ -182,6 +197,13 @@ CoordTrans <- ggproto("CoordTrans", Coord,
   }
 )
 
+# TODO: deprecate this some time in the future
+#' @rdname ggplot2-ggproto
+#' @format NULL
+#' @usage NULL
+#' @export
+CoordTrans <- ggproto("CoordTrans", CoordTransform)
+
 transform_value <- function(trans, value, range) {
   if (is.null(value))
     return(value)
@@ -257,3 +279,4 @@ warn_new_infinites <- function(old_values, new_values, axis, call = caller_env()
     cli::cli_warn("Transformation introduced infinite values in {axis}-axis", call = call)
   }
 }
+

R/geom-histogram.R

@@ -113,11 +113,11 @@
 #' # no observations have 0 ratings.
 #' m +
 #'   geom_histogram(boundary = 0) +
-#'   coord_trans(x = "log10")
+#'   coord_transform(x = "log10")
 #' # Use boundary = 0, to make sure we don't take sqrt of negative values
 #' m +
 #'   geom_histogram(boundary = 0) +
-#'   coord_trans(x = "sqrt")
+#'   coord_transform(x = "sqrt")
 #'
 #' # You can also transform the y axis.  Remember that the base of the bars
 #' # has value 0, so log transformations are not appropriate

R/geom-violin.R

@@ -79,10 +79,10 @@
 #'   scale_y_log10()
 #' m +
 #'   geom_violin() +
-#'   coord_trans(y = "log10")
+#'   coord_transform(y = "log10")
 #' m +
 #'   geom_violin() +
-#'   scale_y_log10() + coord_trans(y = "log10")
+#'   scale_y_log10() + coord_transform(y = "log10")
 #'
 #' # Violin plots with continuous x:
 #' # Use the group aesthetic to group observations in violins

R/guide-axis-logticks.R

@@ -13,7 +13,7 @@ NULL
 #' @param prescale.base Base of logarithm used to transform data manually. The
 #'   default, `NULL`, will use the scale transformation to calculate positions.
 #'   Only set `prescale.base` if the data has already been log-transformed.
-#'   When using a log-transform in the position scale or in `coord_trans()`,
+#'   When using a log-transform in the position scale or in `coord_transform()`,
 #'   keep the default `NULL` argument.
 #' @param negative.small When the scale limits include 0 or negative numbers,
 #'   what should be the smallest absolute value that is marked with a tick?
@@ -39,7 +39,7 @@ NULL
 #'   scale_y_log10(guide = "axis_logticks")
 #'
 #' # Or with log-transformed coordinates
-#' p + coord_trans(x = "log10", y = "log10") +
+#' p + coord_transform(x = "log10", y = "log10") +
 #'   guides(x = "axis_logticks", y = "axis_logticks")
 #'
 #' # When data is transformed manually, one should provide `prescale.base`

R/stat-summary.R

@@ -123,7 +123,7 @@
 #' # statistic has been computed. This means we're calculating the summary on the raw data
 #' # and stretching the geoms onto the log scale.  Compare the widths of the
 #' # standard errors.
-#' m2 + coord_trans(y="log10")
+#' m2 + coord_transform(y="log10")
 #' }
 #' }
 stat_summary <- function(mapping = NULL, data = NULL,

R/summarise-plot.R

@@ -33,7 +33,7 @@
 #' @section Coord summary:
 #'
 #' The function `summarise_coord()` returns information about the log base for
-#' coordinates that are log-transformed in `coord_trans()`, and it also indicates
+#' coordinates that are log-transformed in `coord_transform()`, and it also indicates
 #' whether the coord has flipped the x and y axes.
 #'
 #' @section Layer summary:

_pkgdown.yml

@@ -166,14 +166,15 @@ reference:
     The coordinate system determines how the `x` and `y` aesthetics combine
     to position elements in the plot. The default coordinate system is
     Cartesian (`coord_cartesian()`), which can be tweaked with `coord_map()`,
-    `coord_fixed()`, `coord_flip()`, and `coord_trans()`, or completely
+    `coord_fixed()`, `coord_flip()`, and `coord_transform()`, or completely
     replaced with `coord_polar()`.
   contents:
   - coord_cartesian
   - coord_fixed
   - coord_flip
   - coord_map
   - coord_polar
+  - coord_transform
   - coord_trans
 
 - title: Themes