Merge branch 'main' into binned_limits

Author: teunbrand

NEWS.md

@@ -2,6 +2,16 @@
 
 * Automatic breaks in `scale_*_binned()` should no longer be out-of-bounds,
   and automatic limits expand to include these (@teunbrand, #5095, #5100).
+* Renamed computed aesthetic in `stat_ecdf()` to `ecdf`, to prevent incorrect
+  scale transformations (@teunbrand, #5113 and #5112).
+* Fixed misbehaviour of `draw_key_boxplot()` and `draw_key_crossbar()` with 
+  skewed key aspect ratio (@teunbrand, #5082).
+* `scale_*_binned()` handles zero-range limits more gracefully (@teunbrand, 
+  #5066)
+* Binned scales are now compatible with `trans = "date"` and `trans = "time"` 
+  (@teunbrand, #4217).
+* `ggsave()` warns when multiple `filename`s are given, and only writes to the
+  first file (@teunbrand, #5114)
 * Fixed a regression in `geom_hex()` where aesthetics were replicated across 
   bins (@thomasp85, #5037 and #5044)
 * Fixed spurious warning when `weight` aesthetic was used in `stat_smooth()` 
@@ -10,7 +20,7 @@
   (@teunbrand based on @clauswilke's suggestion #5051).
 * Fixed a regression in `Coord$train_panel_guides()` where names of guides were 
   dropped (@maxsutton, #5063)
-  
+
 # ggplot2 3.4.0
 This is a minor release focusing on tightening up the internals and ironing out
 some inconsistencies in the API. The biggest change is the addition of the 

R/aes-evaluation.r

@@ -1,41 +1,114 @@
 #' Control aesthetic evaluation
 #'
-#' Most aesthetics are mapped from variables found in the data. Sometimes,
-#' however, you want to delay the mapping until later in the rendering process.
-#' ggplot2 has three stages of the data that you can map aesthetics from. The
-#' default is to map at the beginning, using the layer data provided by the
-#' user. The second stage is after the data has been transformed by the layer
-#' stat. The third and last stage is after the data has been transformed and
-#' mapped by the plot scales. The most common example of mapping from stat
-#' transformed data is the height of bars in [geom_histogram()]:
-#' the height does not come from a variable in the underlying data, but
-#' is instead mapped to the `count` computed by [stat_bin()]. An example of
-#' mapping from scaled data could be to use a desaturated version of the stroke
-#' colour for fill. If you want to map directly from the layer data you should
-#' not do anything special. In order to map from stat transformed data you
+#' @description
+#' Most [aesthetics][aes()] are mapped from variables found in the data.
+#' Sometimes, however, you want to delay the mapping until later in the
+#' rendering process. ggplot2 has three stages of the data that you can map
+#' aesthetics from, and three functions to control at which stage aesthetics
+#' should be evaluated.
+#'
+#' @description
+#' `after_stat()` replaces the old approaches of using either `stat()`, e.g.
+#' `stat(density)`, or surrounding the variable names with `..`, e.g.
+#' `..density..`.
+#'
+#' @usage
+#' # These functions can be used inside the `aes()` function
+#' # used as the `mapping` argument in layers, for example:
+#' # geom_density(mapping = aes(y = after_stat(scaled)))
+#'
+#' @param x <[`data-masking`][rlang::topic-data-mask]> An aesthetic expression
+#'   using variables calculated by the stat (`after_stat()`) or layer aesthetics
+#'   (`after_scale()`).
+#' @param start <[`data-masking`][rlang::topic-data-mask]> An aesthetic
+#'   expression using variables from the layer data.
+#' @param after_stat <[`data-masking`][rlang::topic-data-mask]> An aesthetic
+#'   expression using variables calculated by the stat.
+#' @param after_scale <[`data-masking`][rlang::topic-data-mask]> An aesthetic
+#'   expression using layer aesthetics.
+#'
+#' @details
+#' # Staging
+#' Below follows an overview of the three stages of evaluation and how aesthetic
+#' evaluation can be controlled.
+#'
+#' ## Stage 1: direct input
+#' The default is to map at the beginning, using the layer data provided by
+#' the user. If you want to map directly from the layer data you should not do
+#' anything special. This is the only stage where the original layer data can
+#' be accessed.
+#'
+#' ```r
+#' # 'x' and 'y' are mapped directly
+#' ggplot(mtcars) + geom_point(aes(x = mpg, y = disp))
+#' ```
+#'
+#' ## Stage 2: after stat transformation
+#' The second stage is after the data has been transformed by the layer
+#' stat. The most common example of mapping from stat transformed data is the
+#' height of bars in [geom_histogram()]: the height does not come from a
+#' variable in the underlying data, but is instead mapped to the `count`
+#' computed by [stat_bin()]. In order to map from stat transformed data you
 #' should use the `after_stat()` function to flag that evaluation of the
 #' aesthetic mapping should be postponed until after stat transformation.
-#' Similarly, you should use `after_scale()` to flag evaluation of mapping for
-#' after data has been scaled. If you want to map the same aesthetic multiple
-#' times, e.g. map `x` to a data column for the stat, but remap it for the geom,
-#' you can use the `stage()` function to collect multiple mappings.
-#'
-#' `after_stat()` replaces the old approaches of using either `stat()` or
-#' surrounding the variable names with `..`.
-#'
-#' @note Evaluation after stat transformation will have access to the
-#' variables calculated by the stat, not the original mapped values. Evaluation
-#' after scaling will only have access to the final aesthetics of the layer
-#' (including non-mapped, default aesthetics). The original layer data can only
-#' be accessed at the first stage.
-#'
-#' @param x An aesthetic expression using variables calculated by the stat
-#'   (`after_stat()`) or layer aesthetics (`after_scale()`).
-#' @param start An aesthetic expression using variables from the layer data.
-#' @param after_stat An aesthetic expression using variables calculated by the
-#'   stat.
-#' @param after_scale An aesthetic expression using layer aesthetics.
+#' Evaluation after stat transformation will have access to the variables
+#' calculated by the stat, not the original mapped values. The 'computed
+#' variables' section in each stat lists which variables are available to
+#' access.
+#'
+#' ```r
+#' # The 'y' values for the histogram are computed by the stat
+#' ggplot(faithful, aes(x = waiting)) +
+#'   geom_histogram()
+#'
+#' # Choosing a different computed variable to display, matching up the
+#' # histogram with the density plot
+#' ggplot(faithful, aes(x = waiting)) +
+#'   geom_histogram(aes(y = after_stat(density))) +
+#'   geom_density()
+#' ```
+#'
+#' ## Stage 3: after scale transformation
+#' The third and last stage is after the data has been transformed and
+#' mapped by the plot scales. An example of mapping from scaled data could
+#' be to use a desaturated version of the stroke colour for fill. You should
+#' use `after_scale()` to flag evaluation of mapping for after data has been
+#' scaled. Evaluation after scaling will only have access to the final
+#' aesthetics of the layer (including non-mapped, default aesthetics).
+#'
+#' ```r
+#' # The exact colour is known after scale transformation
+#' ggplot(mpg, aes(cty, colour = factor(cyl))) +
+#'   geom_density()
 #'
+#' # We re-use colour properties for the fill without a separate fill scale
+#' ggplot(mpg, aes(cty, colour = factor(cyl))) +
+#'   geom_density(aes(fill = after_scale(alpha(colour, 0.3))))
+#' ```
+#'
+#' ## Complex staging
+#' If you want to map the same aesthetic multiple times, e.g. map `x` to a
+#' data column for the stat, but remap it for the geom, you can use the
+#' `stage()` function to collect multiple mappings.
+#'
+#' ```r
+#' # Use stage to modify the scaled fill
+#' ggplot(mpg, aes(class, hwy)) +
+#'   geom_boxplot(aes(fill = stage(class, after_scale = alpha(fill, 0.4))))
+#'
+#' # Using data for computing summary, but placing label elsewhere.
+#' # Also, we're making our own computed variable to use for the label.
+#' ggplot(mpg, aes(class, displ)) +
+#'   geom_violin() +
+#'   stat_summary(
+#'     aes(
+#'       y = stage(displ, after_stat = 8),
+#'       label = after_stat(paste(mean, "±", sd))
+#'     ),
+#'     geom = "text",
+#'     fun.data = ~ round(data.frame(mean = mean(.x), sd = sd(.x)), 2)
+#'   )
+#' ```
 #' @rdname aes_eval
 #' @name aes_eval
 #'
@@ -55,6 +128,52 @@
 #' # Use stage to modify the scaled fill
 #' ggplot(mpg, aes(class, hwy)) +
 #'   geom_boxplot(aes(fill = stage(class, after_scale = alpha(fill, 0.4))))
+#'
+#' # Making a proportional stacked density plot
+#' ggplot(mpg, aes(cty)) +
+#'   geom_density(
+#'     aes(
+#'       colour = factor(cyl),
+#'       fill = after_scale(alpha(colour, 0.3)),
+#'       y = after_stat(count / sum(n[!duplicated(group)]))
+#'     ),
+#'     position = "stack", bw = 1
+#'   ) +
+#'   geom_density(bw = 1)
+#'
+#' # Imitating a ridgeline plot
+#' ggplot(mpg, aes(cty, colour = factor(cyl))) +
+#'   geom_ribbon(
+#'     stat = "density", outline.type = "upper",
+#'     aes(
+#'       fill = after_scale(alpha(colour, 0.3)),
+#'       ymin = after_stat(group),
+#'       ymax = after_stat(group + ndensity)
+#'     )
+#'   )
+#'
+#' # Labelling a bar plot
+#' ggplot(mpg, aes(class)) +
+#'   geom_bar() +
+#'   geom_text(
+#'     aes(
+#'       y = after_stat(count + 2),
+#'       label = after_stat(count)
+#'     ),
+#'     stat = "count"
+#'   )
+#'
+#' # Labelling the upper hinge of a boxplot,
+#' # inspired by June Choe
+#' ggplot(mpg, aes(displ, class)) +
+#'   geom_boxplot(outlier.shape = NA) +
+#'   geom_text(
+#'     aes(
+#'       label = after_stat(xmax),
+#'       x = stage(displ, after_stat = xmax)
+#'     ),
+#'     stat = "boxplot", hjust = -0.5
+#'   )
 NULL
 
 #' @rdname aes_eval

R/aes.r

@@ -31,6 +31,8 @@ NULL
 #'   are typically omitted because they are so common; all other aesthetics must be named.
 #' @seealso [vars()] for another quoting function designed for
 #'   faceting specifications.
+#'
+#'   [Delayed evaluation][aes_eval] for working with computed variables.
 #' @return A list with class `uneval`. Components of the list are either
 #'   quosures or constants.
 #' @export

R/geom-.r

@@ -78,7 +78,12 @@ Geom <- ggproto("Geom",
     # Trim off extra parameters
     params <- params[intersect(names(params), self$parameters())]
 
-    lapply(split(data, data$PANEL), function(data) {
+    if (nlevels(as.factor(data$PANEL)) > 1L) {
+      data_panels <- split(data, data$PANEL)
+    } else {
+      data_panels <- list(data)
+    }
+    lapply(data_panels, function(data) {
       if (empty(data)) return(zeroGrob())
 
       panel_params <- layout$panel_params[[data$PANEL[1]]]

R/geom-dotplot.r

@@ -17,18 +17,17 @@
 #' to match the number of dots.
 #'
 #' @eval rd_aesthetics("geom", "dotplot")
-#' @section Computed variables:
-#' \describe{
-#'   \item{x}{center of each bin, if binaxis is "x"}
-#'   \item{y}{center of each bin, if binaxis is "x"}
-#'   \item{binwidth}{max width of each bin if method is "dotdensity";
-#'     width of each bin if method is "histodot"}
-#'   \item{count}{number of points in bin}
-#'   \item{ncount}{count, scaled to maximum of 1}
-#'   \item{density}{density of points in bin, scaled to integrate to 1,
-#'     if method is "histodot"}
-#'   \item{ndensity}{density, scaled to maximum of 1, if method is "histodot"}
-#' }
+#' @eval rd_computed_vars(
+#'   x = 'center of each bin, if `binaxis` is `"x"`.',
+#'   y = 'center of each bin, if `binaxis` is `"x"`.',
+#'   binwidth = 'maximum width of each bin if method is `"dotdensity"`;
+#'   width of each bin if method is `"histodot"`.',
+#'   count   = "number of points in bin.",
+#'   ncount  = "count, scaled to a maximum of 1.",
+#'   density = 'density of points in bin, scaled to integrate to 1, if method
+#'   is `"histodot"`.',
+#'   ndensity = 'density, scaled to maximum of 1, if method is `"histodot"`.'
+#' )
 #'
 #' @inheritParams layer
 #' @inheritParams geom_point

R/legend-draw.r

@@ -98,39 +98,58 @@ draw_key_blank <- function(data, params, size) {
 #' @export
 #' @rdname draw_key
 draw_key_boxplot <- function(data, params, size) {
-  grobTree(
-    linesGrob(0.5, c(0.1, 0.25)),
-    linesGrob(0.5, c(0.75, 0.9)),
-    rectGrob(height = 0.5, width = 0.75),
-    linesGrob(c(0.125, 0.875), 0.5),
-    gp = gpar(
-      col = data$colour %||% "grey20",
-      fill = alpha(data$fill %||% "white", data$alpha),
-      lwd = (data$linewidth %||% 0.5) * .pt,
-      lty = data$linetype %||% 1,
-      lineend = params$lineend %||% "butt",
-      linejoin = params$linejoin %||% "mitre"
-    ),
-    vp = if (isTRUE(params$flipped_aes)) viewport(angle = -90)
+  gp <- gpar(
+    col = data$colour %||% "grey20",
+    fill = alpha(data$fill %||% "white", data$alpha),
+    lwd = (data$linewidth %||% 0.5) * .pt,
+    lty = data$linetype %||% 1,
+    lineend = params$lineend %||% "butt",
+    linejoin = params$linejoin %||% "mitre"
   )
+
+  if (isTRUE(params$flipped_aes)) {
+    grobTree(
+      linesGrob(c(0.1, 0.25), 0.5),
+      linesGrob(c(0.75, 0.9), 0.5),
+      rectGrob(width = 0.5, height = 0.75),
+      linesGrob(0.5, c(0.125, 0.875)),
+      gp = gp
+    )
+  } else {
+    grobTree(
+      linesGrob(0.5, c(0.1, 0.25)),
+      linesGrob(0.5, c(0.75, 0.9)),
+      rectGrob(height = 0.5, width = 0.75),
+      linesGrob(c(0.125, 0.875), 0.5),
+      gp = gp
+    )
+  }
 }
 
 #' @export
 #' @rdname draw_key
 draw_key_crossbar <- function(data, params, size) {
-  grobTree(
-    rectGrob(height = 0.5, width = 0.75),
-    linesGrob(c(0.125, 0.875), 0.5),
-    gp = gpar(
-      col = data$colour %||% "grey20",
-      fill = alpha(data$fill %||% "white", data$alpha),
-      lwd = (data$linewidth %||% 0.5) * .pt,
-      lty = data$linetype %||% 1,
-      lineend = params$lineend %||% "butt",
-      linejoin = params$linejoin %||% "mitre"
-    ),
-    vp = if (isTRUE(params$flipped_aes)) viewport(angle = -90)
+  gp <- gpar(
+    col = data$colour %||% "grey20",
+    fill = alpha(data$fill %||% "white", data$alpha),
+    lwd = (data$linewidth %||% 0.5) * .pt,
+    lty = data$linetype %||% 1,
+    lineend = params$lineend %||% "butt",
+    linejoin = params$linejoin %||% "mitre"
   )
+  if (isTRUE(params$flipped_aes)) {
+    grobTree(
+      rectGrob(height = 0.75, width = 0.5),
+      linesGrob(0.5, c(0.125, 0.875)),
+      gp = gp
+    )
+  } else {
+    grobTree(
+      rectGrob(height = 0.5, width = 0.75),
+      linesGrob(c(0.125, 0.875), 0.5),
+      gp = gp
+    )
+  }
 }
 
 #' @export

R/save.r

@@ -77,6 +77,17 @@ ggsave <- function(filename, plot = last_plot(),
                    device = NULL, path = NULL, scale = 1,
                    width = NA, height = NA, units = c("in", "cm", "mm", "px"),
                    dpi = 300, limitsize = TRUE, bg = NULL, ...) {
+  if (length(filename) != 1) {
+    if (length(filename) == 0) {
+      cli::cli_abort("{.arg filename} cannot be empty.")
+    }
+    len <- length(filename)
+    filename <- filename[1]
+    cli::cli_warn(c(
+      "{.arg filename} must have length 1, not length {len}.",
+      "!" = "Only the first, {.file {filename}}, will be used."
+    ))
+  }
 
   dpi <- parse_dpi(dpi)
   dev <- plot_dev(device, filename, dpi = dpi)