New coord_cartesian(ratio) argument (#6450)

* incorporate `coord_cartesian(ratio)`

* simplify `coord_fixed()`

* improve information in error message

* adjust documentation

* add example

* add news bullet

* Don't officially supersede `coord_fixed()`/`coord_equal()`

Author: teunbrand

NEWS.md

@@ -1,5 +1,8 @@
 # ggplot2 (development version)
 
+* New `coord_cartesian(ratio)` argument that absorbs the aspect ratio 
+  functionality from `coord_equal()` and `coord_fixed()`, which are now 
+  wrappers for `coord_cartesian()`.
 * Better handling of the `guide_axis_logticks(negative.small)` parameter when
   scale limits have small maximum (@teunbrand, #6121).
 * Fixed bug where the `ggplot2::`-prefix did not work with `stage()` 

R/coord-cartesian-.R

@@ -29,6 +29,10 @@
 #'   (default) keeps directions as is. `"x"` and `"y"` can be used to reverse
 #'   their respective directions. `"xy"` can be used to reverse both
 #'   directions.
+#' @param ratio aspect ratio, expressed as `y / x`. Can be `NULL` (default) to
+#'   not use an aspect ratio. Using `1` ensures that one unit on the x-axis
+#'   is the same length as one unit on the y-axis. Ratios higher than one make
+#'   units on the y-axis longer than units on the x-axis, and vice versa.
 #' @export
 #' @examples
 #' # There are two ways of zooming the plot display: with scales or
@@ -55,6 +59,10 @@
 #' # default limits
 #' p + coord_cartesian(expand = FALSE)
 #'
+#' # Using a fixed ratio: 1 y-axis unit is 100 x-axis units
+#' # Plot window can be resized and aspect ratio will be maintained
+#' p + coord_cartesian(ratio = 100)
+#'
 #' # You can see the same thing with this 2d histogram
 #' d <- ggplot(diamonds, aes(carat, price)) +
 #'   stat_bin_2d(bins = 25, colour = "white")
@@ -68,15 +76,18 @@
 #' # displayed bigger
 #' d + coord_cartesian(xlim = c(0, 1))
 coord_cartesian <- function(xlim = NULL, ylim = NULL, expand = TRUE,
-                            default = FALSE, clip = "on", reverse = "none") {
+                            default = FALSE, clip = "on", reverse = "none",
+                            ratio = NULL) {
   check_coord_limits(xlim)
   check_coord_limits(ylim)
+  check_number_decimal(ratio, allow_infinite = FALSE, allow_null = TRUE)
   ggproto(NULL, CoordCartesian,
     limits = list(x = xlim, y = ylim),
     reverse = reverse,
     expand = expand,
     default = default,
-    clip = clip
+    clip = clip,
+    ratio = ratio
   )
 }
 
@@ -87,7 +98,13 @@ coord_cartesian <- function(xlim = NULL, ylim = NULL, expand = TRUE,
 CoordCartesian <- ggproto("CoordCartesian", Coord,
 
   is_linear = function() TRUE,
-  is_free = function() TRUE,
+  is_free = function(self) is.null(self$ratio),
+  aspect = function(self, ranges) {
+    if (is.null(self$ratio)) {
+      return(NULL)
+    }
+    diff(ranges$y.range) / diff(ranges$x.range) * self$ratio
+  },
 
   distance = function(x, y, panel_params) {
     max_dist <- dist_euclidean(panel_params$x$dimension(), panel_params$y$dimension())

R/coord-fixed.R

@@ -10,7 +10,7 @@
 #'
 #' @export
 #' @inheritParams coord_cartesian
-#' @param ratio aspect ratio, expressed as `y / x`
+#' @inheritDotParams coord_cartesian
 #' @examples
 #' # ensures that the ranges of axes are equal to the specified ratio by
 #' # adjusting the plot aspect ratio
@@ -22,17 +22,8 @@
 #' p + coord_fixed(xlim = c(15, 30))
 #'
 #' # Resize the plot to see that the specified aspect ratio is maintained
-coord_fixed <- function(ratio = 1, xlim = NULL, ylim = NULL, expand = TRUE,
-                        clip = "on", reverse = "none") {
-  check_coord_limits(xlim)
-  check_coord_limits(ylim)
-  ggproto(NULL, CoordFixed,
-    limits = list(x = xlim, y = ylim),
-    ratio = ratio,
-    expand = expand,
-    reverse = reverse,
-    clip = clip
-  )
+coord_fixed <- function(ratio = 1, ...) {
+  coord_cartesian(ratio = ratio, ...)
 }
 
 #' @export

R/facet-.R

@@ -513,10 +513,12 @@ Facet <- ggproto("Facet", NULL,
       if (space$x && space$y) {
         aspect_ratio <- aspect_ratio %||% coord$ratio
       } else if (free$x || free$y) {
-        cli::cli_abort(
-          "{.fn {snake_class(self)}} can't use free scales with \\
-          {.fn {snake_class(coord)}}."
-        )
+        msg <- paste0("{.fn {snake_class(self)}} can't use free scales with ",
+                      "{.fn {snake_class(coord)}}")
+        if (!is.null(coord$ratio)) {
+          msg <- paste0(msg, " with a fixed {.arg ratio} argument")
+        }
+        cli::cli_abort(paste0(msg, "."))
       }
     }
 

man/coord_cartesian.Rd

@@ -33,11 +33,11 @@
 
 ---
 
-    `facet_wrap()` can't use free scales with `coord_fixed()`.
+    `facet_wrap()` can't use free scales with `coord_cartesian()` with a fixed `ratio` argument.
 
 # facet_grid throws errors at bad layout specs
 
-    `facet_grid()` can't use free scales with `coord_fixed()`.
+    `facet_grid()` can't use free scales with `coord_cartesian()` with a fixed `ratio` argument.
 
 ---