rename range() function of coord to backtransform_range()

Author: clauswilke

NEWS.md

@@ -1,5 +1,10 @@
 # ggplot2 3.0.0.9000
 
+*   The function `range()` in `Coord` has been renamed to `backtransform_range()`
+    to clarify its intended meaning. This affects developers of custom coords. It
+    may also affect developers of custom geoms that use the `range()` function. That
+    code should be migrated to use `backtransform_range()` (@clauswilke, breaking change).
+
 *   `geom_sf()` now respects `lineend`, `linejoin`, and `linemitre` parameters 
     for lines and polygons (@alistaire47, #2826)
 

R/coord-.r

@@ -13,12 +13,13 @@
 #'   - `render_bg`: Renders background elements.
 #'   - `render_axis_h`: Renders the horizontal axes.
 #'   - `render_axis_v`: Renders the vertical axes.
-#'   - `range(panel_params)`: Extracts the panel range provided
+#'   - `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 is needed
+#'     backtransforms to data coordinates. This back-transformation is needed
 #'     for coords such as `coord_flip()`, `coord_polar()`, `coord_trans()` where
 #'     the range in the transformed coordinates differs from the range in the
 #'     untransformed coordinates.
+#'   - `range`: Deprecated, do not implement. Calls `backtransform_range()`.
 #'   - `transform`: Transforms x and y coordinates.
 #'   - `distance`: Calculates distance.
 #'   - `is_linear`: Returns `TRUE` if the coordinate system is
@@ -84,14 +85,24 @@ Coord <- ggproto("Coord",
   # transform range given in transformed coordinates
   # back into range in given in (possibly scale-transformed)
   # data coordinates
-  range = function(panel_params) {
+  backtransform_range = function(panel_params) {
     warning(
       "range backtransformation not implemented in this coord; plot may be wrong.",
       call. = FALSE
       )
     list(x = panel_params$x.range, y = panel_params$y.range)
   },
 
+  # deprecated, do not use or reimplement
+  # kept only for backwards compatibility
+  range = function(self, panel_params) {
+    warning(
+      "function `Coord$range()` is deprecated; use `Coord$backtransform_range()`.",
+      call. = FALSE
+    )
+    self$backtransform_range(panel_params)
+  },
+
   setup_panel_params = function(scale_x, scale_y, params = list()) {
     list()
   },

R/coord-cartesian-.r

@@ -83,7 +83,7 @@ CoordCartesian <- ggproto("CoordCartesian", Coord,
     dist_euclidean(x, y) / max_dist
   },
 
-  range = function(panel_params) {
+  backtransform_range = function(panel_params) {
     list(x = panel_params$x.range, y = panel_params$y.range)
   },
 

R/coord-flip.r

@@ -44,7 +44,7 @@ CoordFlip <- ggproto("CoordFlip", CoordCartesian,
     CoordCartesian$transform(data, panel_params)
   },
 
-  range = function(panel_params) {
+  backtransform_range = function(panel_params) {
     list(x = panel_params$y.range, y = panel_params$x.range)
   },
 

R/coord-map.r

@@ -119,7 +119,7 @@ CoordMap <- ggproto("CoordMap", Coord,
     out
   },
 
-  range = function(panel_params) {
+  backtransform_range = function(panel_params) {
     # range is stored in data coordinates and doesn't have to be back-transformed
     list(x = panel_params$x.range, y = panel_params$y.range)
   },

R/coord-munch.r

@@ -15,7 +15,7 @@ coord_munch <- function(coord, data, range, segment_length = 0.01) {
   if (coord$is_linear()) return(coord$transform(data, range))
 
   # range has theta and r values; get corresponding x and y values
-  ranges <- coord$range(range)
+  ranges <- coord$backtransform_range(range)
 
   # Convert any infinite locations into max/min
   # Only need to work with x and y because for munching, those are the

R/coord-polar.r

@@ -90,7 +90,7 @@ CoordPolar <- ggproto("CoordPolar", Coord,
     dist_polar(r, theta)
   },
 
-  range = function(self, panel_params) {
+  backtransform_range = function(self, panel_params) {
     setNames(
       list(panel_params$theta.range, panel_params$r.range),
       c(self$theta, self$r)

R/coord-transform.r

@@ -119,7 +119,7 @@ CoordTrans <- ggproto("CoordTrans", Coord,
     dist_euclidean(self$trans$x$transform(x), self$trans$y$transform(y)) / max_dist
   },
 
-  range = function(self, panel_params) {
+  backtransform_range = function(self, panel_params) {
     list(
       x = self$trans$x$inverse(panel_params$x.range),
       y = self$trans$y$inverse(panel_params$y.range)

R/geom-abline.r

@@ -111,7 +111,7 @@ geom_abline <- function(mapping = NULL, data = NULL,
 #' @export
 GeomAbline <- ggproto("GeomAbline", Geom,
   draw_panel = function(data, panel_params, coord) {
-    ranges <- coord$range(panel_params)
+    ranges <- coord$backtransform_range(panel_params)
 
     data$x    <- ranges$x[1]
     data$xend <- ranges$x[2]

R/geom-hline.r

@@ -37,7 +37,7 @@ geom_hline <- function(mapping = NULL, data = NULL,
 #' @export
 GeomHline <- ggproto("GeomHline", Geom,
   draw_panel = function(data, panel_params, coord) {
-    ranges <- coord$range(panel_params)
+    ranges <- coord$backtransform_range(panel_params)
 
     data$x    <- ranges$x[1]
     data$xend <- ranges$x[2]

R/geom-vline.r

@@ -37,7 +37,7 @@ geom_vline <- function(mapping = NULL, data = NULL,
 #' @export
 GeomVline <- ggproto("GeomVline", Geom,
   draw_panel = function(data, panel_params, coord) {
-    ranges <- coord$range(panel_params)
+    ranges <- coord$backtransform_range(panel_params)
 
     data$x    <- data$xintercept
     data$xend <- data$xintercept

R/sf.R

@@ -361,7 +361,7 @@ CoordSf <- ggproto("CoordSf", CoordCartesian,
     )
   },
 
-  range = function(panel_params) {
+  backtransform_range = function(panel_params) {
     list(x = panel_params$x_range, y = panel_params$y_range)
   },
 

R/summarise-plot.R

@@ -38,7 +38,7 @@ summarise_layout = function(p) {
     setNames(res, facet_vars)
   })
 
-  xyranges <- lapply(l$panel_params, l$coord$range)
+  xyranges <- lapply(l$panel_params, l$coord$backtransform_range)
   layout$xmin <- vapply(xyranges, function(xyrange) xyrange$x[[1]], numeric(1))
   layout$xmax <- vapply(xyranges, function(xyrange) xyrange$x[[2]], numeric(1))
   layout$ymin <- vapply(xyranges, function(xyrange) xyrange$y[[1]], numeric(1))