Merge branch 'main' into v3.4.2-rc

Author: teunbrand

.github/workflows/R-CMD-check.yaml

@@ -63,7 +63,7 @@ jobs:
           cache-version: 3
           extra-packages: >
             any::rcmdcheck,
-            Hmisc=?ignore-before-r=3.6.0,
+            Hmisc=?ignore-before-r=4.1.0,
             quantreg=?ignore-before-r=3.6.0,
           needs: check
 

DESCRIPTION

@@ -52,7 +52,6 @@ Suggests:
     hexbin,
     Hmisc,
     knitr,
-    lattice,
     mapproj,
     maps,
     maptools,
@@ -63,7 +62,6 @@ Suggests:
     quantreg,
     ragg,
     RColorBrewer,
-    rgeos,
     rmarkdown,
     rpart,
     sf (>= 0.7-3),

NEWS.md

@@ -1,5 +1,25 @@
 # ggplot2 (development version)
 
+* To improve `width` calculation in bar plots with empty factor levels, 
+  `resolution()` considers `mapped_discrete` values as having resolution 1 
+  (@teunbrand, #5211)
+* When `geom_path()` has aesthetics varying within groups, the `arrow()` is
+  applied to groups instead of individual segments (@teunbrand, #4935).
+* The default width of `geom_bar()` is now based on panel-wise resolution of
+  the data, rather than global resolution (@teunbrand, #4336).
+* To apply dodging more consistently in violin plots, `stat_ydensity()` now
+  has a `drop` argument to keep or discard groups with 1 observation.
+* Aesthetics listed in `geom_*()` and `stat_*()` layers now point to relevant
+  documentation (@teunbrand, #5123).
+* `coord_flip()` has been marked as superseded. The recommended alternative is
+  to swap the `x` and `y` aesthetic and/or using the `orientation` argument in
+  a layer (@teunbrand, #5130).
+* `stat_align()` is now applied per panel instead of globally, preventing issues
+  when facets have different ranges (@teunbrand, #5227).
+* A stacking bug in `stat_align()` was fixed (@teunbrand, #5176).
+* `stat_contour()` and `stat_contour_filled()` now warn about and remove
+  duplicated coordinates (@teunbrand, #5215).
+
 # ggplot2 3.4.2
 This is a hotfix release anticipating changes in r-devel, but folds in upkeep
 changes and a few bug fixes as well.

R/aes-colour-fill-alpha.R

@@ -8,6 +8,12 @@
 #'
 #' @section Colour and fill:
 #'
+#' The `colour` aesthetic is used to draw lines and strokes, such as in
+#' [`geom_point()`] and [`geom_line()`], but also the line contours of
+#' [`geom_rect()`] and [`geom_polygon()`]. The `fill` aesthetic is used to
+#' colour the inside areas of geoms, such as [`geom_rect()`] and
+#' [`geom_polygon()`], but also the insides of shapes 21-25 of [`geom_point()`].
+#'
 #' Colours and fills can be specified in the following ways:
 #' * A name, e.g., `"red"`. R has 657 built-in named colours, which can be
 #' listed with [grDevices::colors()].
@@ -38,9 +44,11 @@
 #' [scale_fill_gradient()], [scale_fill_grey()],
 #' [scale_fill_hue()], [scale_fill_identity()],
 #' [scale_fill_manual()], [scale_fill_viridis_d()]
-#' * Other options for modifying alpha: [scale_alpha()]
-#' * Run `vignette("ggplot2-specs")` to see an overview of other aesthestics that
+#' * Other options for modifying alpha:
+#' [scale_alpha()], [scale_alpha_manual()], [scale_alpha_identity()]
+#' * Run `vignette("ggplot2-specs")` to see an overview of other aesthetics that
 #' can be modified.
+#' @family aesthetics documentation
 #'
 #' @name aes_colour_fill_alpha
 #' @aliases colour color fill

R/aes-group-order.R

@@ -16,14 +16,23 @@
 #' and/or `linetype`. This is demonstrated in the examples below.
 #'
 #' There are three common cases where the default does not display the data correctly.
+#' 1. `geom_line()` where there are multiple individuals and the plot tries to
+#'   connect every observation, even across individuals, with a line.
+#' 1. `geom_line()` where a discrete x-position implies groups, whereas observations
+#'   span the discrete x-positions.
+#' 1. When the grouping needs to be different over different layers, for example
+#'   when computing a statistic on all observations when another layer shows
+#'   individuals.
+#'
 #' The examples below use a longitudinal dataset, `Oxboys`, from the nlme package to demonstrate
 #' these cases. `Oxboys` records the heights (height) and centered ages (age) of 26 boys (Subject),
 #' measured on nine occasions (Occasion).
 #'
 #' @seealso
 #' * Geoms commonly used with groups: [geom_bar()], [geom_histogram()], [geom_line()]
-#' * Run `vignette("ggplot2-specs")` to see an overview of other aesthestics that
+#' * Run `vignette("ggplot2-specs")` to see an overview of other aesthetics that
 #' can be modified.
+#' @family aesthetics documentation
 #'
 #' @examples
 #' \donttest{

R/aes-linetype-size-shape.R

@@ -1,32 +1,48 @@
 #' Differentiation related aesthetics: linetype, size, shape
 #'
 #' @description
-#' The `linetype`, `size`, and `shape` aesthetics modify the appearance of
-#' lines and/or points. They also apply to the outlines of polygons (`linetype`
-#' and `size`) or to text (`size`).
+#' The `linetype`, `linewidth`, `size`, and `shape` aesthetics modify the
+#' appearance of lines and/or points. They also apply to the outlines of
+#' polygons (`linetype` and `linewidth`) or to text (`size`).
 #'
+#' @section Linetype:
 #' The `linetype` aesthetic can be specified with either an integer (0-6), a
 #' name (0 = blank, 1 = solid, 2 = dashed, 3 = dotted, 4 = dotdash, 5 = longdash,
 #' 6 = twodash), a mapping to a discrete variable, or a string of an even number
 #' (up to eight) of hexadecimal digits which give the lengths in consecutive
 #' positions in the string. See examples for a hex string demonstration.
 #'
-#' The `size` aesthetic can be specified with a numerical value (in millimetres)
-#' or via a mapping to a continuous variable.
+#' @section Linewidth and stroke:
+#' The `linewidth` aesthetic sets the widths of lines, and can be specified
+#' with a numeric value (for historical reasons, these units are about 0.75
+#' millimetres). Alternatively, they can also be set via mapping to a continuous
+#' variable. The `stroke` aesthetic serves the same role for points, but is
+#' distinct for discriminating points from lines in geoms such as
+#' [`geom_pointrange()`].
 #'
-#' The `shape` aesthetic can be specified with an integer (between 0 and 25),
-#' a single character (which uses that character as the plotting symbol),
-#' a `.` to draw the smallest rectangle that is visible (i.e., about one pixel),
-#' an `NA` to draw nothing, or a mapping to a discrete variable. Symbols and
-#' filled shapes are described in the examples below.
+#' @section Size:
+#' The `size` aesthetic control the size of points and text, and can be
+#' specified with a numerical value (in millimetres) or via a mapping to a
+#' continuous variable.
+#'
+#' @section Shape:
+#' The `shape` aesthetic controls the symbols of points, and can be specified
+#' with an integer (between 0 and 25), a single character (which uses that
+#' character as the plotting symbol), a `.` to draw the smallest rectangle that
+#' is visible (i.e., about one pixel), an `NA` to draw nothing, or a mapping to
+#' a discrete variable. Symbols and filled shapes are described in the examples
+#' below.
 #'
 #' @seealso
 #' * [geom_line()] and [geom_point()] for geoms commonly used
 #'  with these aesthetics.
 #' * [aes_group_order()] for using `linetype`, `size`, or
 #' `shape` for grouping.
-#' * Run `vignette("ggplot2-specs")` to see an overview of other aesthestics that
+#' * Scales that can be used to modify these aesthetics: [`scale_linetype()`],
+#'   [`scale_linewidth()`], [`scale_size()`], and [`scale_shape()`].
+#' * Run `vignette("ggplot2-specs")` to see an overview of other aesthetics that
 #' can be modified.
+#' @family aesthetics documentation
 #' @name aes_linetype_size_shape
 #' @aliases linetype size shape
 #' @examples
@@ -45,6 +61,12 @@
 #' ggplot(economics_long, aes(date, value01)) +
 #'   geom_line(aes(linetype = variable))
 #'
+#' # Linewidth examples
+#' ggplot(economics, aes(date, unemploy)) +
+#'   geom_line(linewidth = 2, lineend = "round")
+#' ggplot(economics, aes(date, unemploy)) +
+#'   geom_line(aes(linewidth = uempmed), lineend = "round")
+#'
 #' # Size examples
 #' p <- ggplot(mtcars, aes(wt, mpg))
 #' p + geom_point(size = 4)

R/aes-position.R

@@ -12,6 +12,12 @@
 #' `xmin`, `xmax`, `ymin`  and `ymax` can be used to specify the position of
 #' annotations and to represent rectangular areas.
 #'
+#' In addition, there are position aesthetics that are contextual to the
+#' geometry that they're used in. These are `xintercept`, `yintercept`,
+#' `xmin_final`, `ymin_final`, `xmax_final`, `ymax_final`, `xlower`, `lower`,
+#' `xmiddle`, `middle`, `xupper`, `upper`, `x0` and `y0`. Many of these are used
+#' and automatically computed in [`geom_boxplot()`].
+#'
 #' @name aes_position
 #' @aliases x y xmin xmax ymin ymax xend yend
 #'
@@ -20,7 +26,13 @@
 #' [geom_curve()], [geom_errorbar()], [geom_line()], [geom_linerange()],
 #' [geom_path()], [geom_point()], [geom_pointrange()], [geom_rect()],
 #' [geom_segment()]
+#' * Scales that can be used to modify positions:
+#'   [`scale_continuous()`][scale_x_continuous()],
+#'   [`scale_discrete()`][scale_x_discrete()],
+#'   [`scale_binned()`][scale_x_binned()],
+#'   [`scale_date()`][scale_x_date()].
 #' * See also [annotate()] for placing annotations.
+#' @family aesthetics documentation
 #' @examples
 #'
 #' # Generate data: means and standard errors of means for prices

R/aes.R

@@ -33,7 +33,12 @@ NULL
 #' @seealso [vars()] for another quoting function designed for
 #'   faceting specifications.
 #'
+#'   Run `vignette("ggplot2-specs")` to see an overview of other aesthetics
+#'   that can be modified.
+#'
 #'   [Delayed evaluation][aes_eval] for working with computed variables.
+#'
+#' @family aesthetics documentation
 #' @return A list with class `uneval`. Components of the list are either
 #'   quosures or constants.
 #' @export

R/coord-flip.R

@@ -1,30 +1,48 @@
 #' Cartesian coordinates with x and y flipped
 #'
-#' Flip cartesian coordinates so that horizontal becomes vertical, and
-#' vertical, horizontal. This is primarily useful for converting geoms and
-#' statistics which display y conditional on x, to x conditional on y.
+#' @description
+#' `r lifecycle::badge("superseded")`
+#'
+#' This function is superseded because in many cases, `coord_flip()` can easily
+#' be replaced by swapping the x and y aesthetics, or optionally setting the
+#' `orientation` argument in geom and stat layers.
+#'
+#' `coord_flip()` is useful for geoms and statistics that do not support
+#' the `orientation` setting, and converting the display of y conditional on x,
+#' to x conditional on y.
 #'
 #' @export
 #' @inheritParams coord_cartesian
 #' @examples
-#' # Very useful for creating boxplots, and other interval
-#' # geoms in the horizontal instead of vertical position.
+#' # The preferred method of creating horizontal instead of vertical boxplots
+#' ggplot(diamonds, aes(price, cut)) +
+#'   geom_boxplot()
 #'
+#' # Using `coord_flip()` to make the same plot
 #' ggplot(diamonds, aes(cut, price)) +
 #'   geom_boxplot() +
 #'   coord_flip()
 #'
-#' h <- ggplot(diamonds, aes(carat)) +
-#'   geom_histogram()
-#' h
-#' h + coord_flip()
-#' h + coord_flip() + scale_x_reverse()
+#' # With swapped aesthetics, the y-scale controls the left axis
+#' ggplot(diamonds, aes(y = carat)) +
+#'   geom_histogram() +
+#'   scale_y_reverse()
+#'
+#' # In `coord_flip()`, the x-scale controls the left axis
+#' ggplot(diamonds, aes(carat)) +
+#'   geom_histogram() +
+#'   coord_flip() +
+#'   scale_x_reverse()
 #'
-#' # You can also use it to flip line and area plots:
-#' df <- data.frame(x = 1:5, y = (1:5) ^ 2)
-#' ggplot(df, aes(x, y)) +
-#'   geom_area()
-#' last_plot() + coord_flip()
+#' # In line and area plots, swapped aesthetics require an explicit orientation
+#' df <- data.frame(a = 1:5, b = (1:5) ^ 2)
+#' ggplot(df, aes(b, a)) +
+#'   geom_area(orientation = "y")
+#'
+#' # The same plot with `coord_flip()`
+#' ggplot(df, aes(a, b)) +
+#'   geom_area() +
+#'   coord_flip()
 coord_flip <- function(xlim = NULL, ylim = NULL, expand = TRUE, clip = "on") {
   ggproto(NULL, CoordFlip,
     limits = list(x = xlim, y = ylim),

R/geom-bar.R

@@ -144,7 +144,10 @@ GeomBar <- ggproto("GeomBar", GeomRect,
     data$flipped_aes <- params$flipped_aes
     data <- flip_data(data, params$flipped_aes)
     data$width <- data$width %||%
-      params$width %||% (resolution(data$x, FALSE) * 0.9)
+      params$width %||% (min(vapply(
+        split(data$x, data$PANEL),
+        resolution, numeric(1), zero = FALSE
+      )) * 0.9)
     data$just <- params$just %||% 0.5
     data <- transform(data,
       ymin = pmin(y, 0), ymax = pmax(y, 0),