Merge branch 'main' into boxplot_key

Author: teunbrand

NEWS.md

@@ -2,6 +2,12 @@
 
 * 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 +16,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/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)

R/scale-.r

@@ -1021,16 +1021,22 @@ ScaleBinned <- ggproto("ScaleBinned", Scale,
       x <- self$rescale(self$oob(x, range = limits), limits)
       breaks <- self$rescale(breaks, limits)
 
-      x_binned <- cut(x, breaks,
-        labels = FALSE,
-        include.lowest = TRUE,
-        right = self$right
-      )
+      if (length(breaks) > 1) {
+        x_binned <- cut(x, breaks,
+          labels = FALSE,
+          include.lowest = TRUE,
+          right = self$right
+        )
+        midpoints <- breaks[-1] - diff(breaks) / 2
+      } else {
+        x_binned  <- 1L
+        midpoints <- 0.5
+      }
 
       if (!is.null(self$palette.cache)) {
         pal <- self$palette.cache
       } else {
-        pal <- self$palette(breaks[-1] - diff(breaks) / 2)
+        pal <- self$palette(midpoints)
         self$palette.cache <- pal
       }
 
@@ -1075,10 +1081,13 @@ ScaleBinned <- ggproto("ScaleBinned", Scale,
       # Ensure terminal bins are same width if limits not set
       if (is.null(self$limits)) {
         # Remove calculated breaks if they coincide with limits
-        breaks <- setdiff(breaks, limits)
+        breaks <- breaks[!breaks %in% limits]
         nbreaks <- length(breaks)
         if (nbreaks >= 2) {
-          new_limits <- c(2 * breaks[1] - breaks[2], 2 * breaks[nbreaks] - breaks[nbreaks - 1])
+          new_limits <- c(
+            breaks[1] + (breaks[1] - breaks[2]),
+            breaks[nbreaks] + (breaks[nbreaks] - breaks[nbreaks - 1])
+          )
           if (breaks[nbreaks] > limits[2]) {
             new_limits[2] <- breaks[nbreaks]
             breaks <- breaks[-nbreaks]

R/stat-.r

@@ -14,7 +14,7 @@
 #'     `compute_panel(self, data, scales, ...)`, or
 #'     `compute_group(self, data, scales, ...)`.
 #'
-#'     `compute_layer()` is called once per layer, `compute_panel_()`
+#'     `compute_layer()` is called once per layer, `compute_panel()`
 #'     is called once per panel, and `compute_group()` is called once per
 #'     group. All must return a data frame.
 #'

R/stat-bin.r

@@ -27,14 +27,13 @@
 #'   or left edges of bins are included in the bin.
 #' @param pad If `TRUE`, adds empty bins at either end of x. This ensures
 #'   frequency polygons touch 0. Defaults to `FALSE`.
-#' @section Computed variables:
-#' \describe{
-#'   \item{`count`}{number of points in bin}
-#'   \item{`density`}{density of points in bin, scaled to integrate to 1}
-#'   \item{`ncount`}{count, scaled to maximum of 1}
-#'   \item{`ndensity`}{density, scaled to maximum of 1}
-#'   \item{`width`}{widths of bins}
-#' }
+#' @eval rd_computed_vars(
+#'   count    = "number of points in bin.",
+#'   density  = "density of points in bin, scaled to integrate to 1.",
+#'   ncount   = "count, scaled to a maximum of 1.",
+#'   ndensity = "density, scaled to a maximum of 1.",
+#'   width    = "widths of bins."
+#' )
 #'
 #' @section Dropped variables:
 #' \describe{

R/stat-bin2d.r

@@ -5,13 +5,12 @@
 #' @param drop if `TRUE` removes all cells with 0 counts.
 #' @export
 #' @rdname geom_bin_2d
-#' @section Computed variables:
-#' \describe{
-#'   \item{count}{number of points in bin}
-#'   \item{density}{density of points in bin, scaled to integrate to 1}
-#'   \item{ncount}{count, scaled to maximum of 1}
-#'   \item{ndensity}{density, scaled to maximum of 1}
-#' }
+#' @eval rd_computed_vars(
+#'   count    = "number of points in bin.",
+#'   density  = "density of points in bin, scaled to integrate to 1.",
+#'   ncount   = "count, scaled to maximum of 1.",
+#'   ndensity = "density, scaled to a maximum of 1."
+#' )
 stat_bin_2d <- function(mapping = NULL, data = NULL,
                         geom = "tile", position = "identity",
                         ...,