Crosslink aesthetics documentation (#5124)

* Connect scales to aes documentation

* Improvements to aes documentation

* Crosslink aes documentation

* Match aes to doc page

* Prevent having to import `relist()`

* Better crosslinks for position scales

* Roxygenate

* Add NEWS bullet

* Fix clumsy merge

* Fix clumsy merge part II

Author: teunbrand

NEWS.md

@@ -1,5 +1,7 @@
 # ggplot2 (development version)
 
+* 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).

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/scale-alpha.R

@@ -10,6 +10,11 @@
 #'   breaks, labels and so forth.
 #' @param range Output range of alpha values. Must lie between 0 and 1.
 #' @family colour scales
+#' @family alpha scales
+#' @seealso
+#' The documentation on [colour aesthetics][aes_colour_fill_alpha].
+#'
+#' Other alpha scales: [scale_alpha_manual()], [scale_alpha_identity()].
 #' @export
 #' @examples
 #' p <- ggplot(mpg, aes(displ, hwy)) +

R/scale-binned.R

@@ -8,6 +8,8 @@
 #' @inheritParams binned_scale
 #'
 #' @family position scales
+#' @seealso
+#' The [position documentation][aes_position].
 #' @name scale_binned
 #' @aliases NULL
 #'

R/scale-brewer.R

@@ -37,6 +37,8 @@
 #'   or [binned_scale()], for `brewer`, `distiller`, and `fermenter` variants
 #'   respectively, to control name, limits, breaks, labels and so forth.
 #' @family colour scales
+#' @seealso
+#' The documentation on [colour aesthetics][aes_colour_fill_alpha].
 #' @rdname scale_brewer
 #' @export
 #' @examples

R/scale-colour.R

@@ -35,6 +35,8 @@
 #' @seealso [scale_colour_gradient()], [scale_colour_viridis_c()],
 #'   [scale_colour_steps()], [scale_colour_viridis_b()], [scale_fill_gradient()],
 #'   [scale_fill_viridis_c()], [scale_fill_steps()], and [scale_fill_viridis_b()]
+#'
+#'   The documentation on [colour aesthetics][aes_colour_fill_alpha].
 #' @family colour scales
 #' @rdname scale_colour_continuous
 #' @section Color Blindness: