Add range function to Coord().

Author: clauswilke

NEWS.md

@@ -11,10 +11,11 @@
     that can be used to specify which graticules to label on which side of the plot
     (@clauswilke, #2846).
 
-*   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).
+*   `Coord` objects now have a function `backtransform_range()` that returns the
+    panel range in data coordinates. This change may affect developers of custom coords. It
+    may also affect developers of custom geoms that use the `range()` function. In
+    some applications, `backtransform_range()` may be more appropriate.
+    (@clauswilke, #2821).
 
 *   `geom_sf()` now respects `lineend`, `linejoin`, and `linemitre` parameters 
     for lines and polygons (@alistaire47, #2826)

R/coord-.r

@@ -19,7 +19,10 @@
 #'     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()`.
+#'   - `range(panel_params)`: Extracts the panel range provided
+#'     in `panel_params` (created by `setup_panel_params()`, see below) and
+#'     returns it. Unlike `backtransform_range()`, this function does not perform
+#'     any back-transformation and instead returns final transformed coordinates.
 #'   - `transform`: Transforms x and y coordinates.
 #'   - `distance`: Calculates distance.
 #'   - `is_linear`: Returns `TRUE` if the coordinate system is
@@ -87,20 +90,19 @@ Coord <- ggproto("Coord",
   # data coordinates
   backtransform_range = function(panel_params) {
     warning(
-      "range backtransformation not implemented in this coord; plot may be wrong.",
+      "range backtransformation not implemented in this coord; results 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) {
+  # return range stored in panel_params
+  range = function(panel_params) {
     warning(
-      "function `Coord$range()` is deprecated; use `Coord$backtransform_range()`.",
+      "range calculation not implemented in this coord; results may be wrong.",
       call. = FALSE
     )
-    self$backtransform_range(panel_params)
+    list(x = panel_params$x.range, y = panel_params$y.range)
   },
 
   setup_panel_params = function(scale_x, scale_y, params = list()) {

R/coord-cartesian-.r

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

R/coord-map.r

@@ -124,6 +124,11 @@ CoordMap <- ggproto("CoordMap", Coord,
     list(x = panel_params$x.range, y = panel_params$y.range)
   },
 
+  # not sure yet how to implement this, panel params store backtransformed range
+  #range = function(panel_params) {
+  #  list(x = panel_params$x.range, y = panel_params$y.range)
+  #},
+
   distance = function(x, y, panel_params) {
     max_dist <- dist_central_angle(panel_params$x.range, panel_params$y.range)
     dist_central_angle(x, y) / max_dist

R/coord-polar.r

@@ -97,6 +97,12 @@ CoordPolar <- ggproto("CoordPolar", Coord,
     )
   },
 
+  range = function(self, panel_params) {
+    # return angle as x and radius as y
+    # downstream functions (e.g. summarise_layout()) expect x and y
+    list(x = panel_params$theta.range, y = panel_params$r.range)
+  },
+
   setup_panel_params = function(self, scale_x, scale_y, params = list()) {
 
     ret <- list(x = list(), y = list())

R/sf.R

@@ -544,9 +544,15 @@ CoordSf <- ggproto("CoordSf", CoordCartesian,
   },
 
   backtransform_range = function(panel_params) {
+    # this does not actually return backtransformed ranges in the general case, needs fixing
     list(x = panel_params$x_range, y = panel_params$y_range)
   },
 
+  range = function(panel_params) {
+    list(x = panel_params$x_range, y = panel_params$y_range)
+  },
+
+
   # CoordSf enforces a fixed aspect ratio -> axes cannot be changed freely under faceting
   is_free = function() FALSE,
 

R/summarise-plot.R

@@ -38,7 +38,7 @@ summarise_layout = function(p) {
     setNames(res, facet_vars)
   })
 
-  xyranges <- lapply(l$panel_params, l$coord$backtransform_range)
+  xyranges <- lapply(l$panel_params, l$coord$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))