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:

R/scale-continuous.R

@@ -10,6 +10,9 @@
 #'
 #' @inheritParams continuous_scale
 #' @family position scales
+#' @seealso
+#' The [position documentation][aes_position].
+#'
 #' @param ... Other arguments passed on to `scale_(x|y)_continuous()`
 #' @examples
 #' p1 <- ggplot(mpg, aes(displ, hwy)) +

R/scale-date.R

@@ -34,7 +34,10 @@
 #' @param timezone The timezone to use for display on the axes. The default
 #'   (`NULL`) uses the timezone encoded in the data.
 #' @family position scales
-#' @seealso [sec_axis()] for how to specify secondary axes
+#' @seealso
+#' [sec_axis()] for how to specify secondary axes
+#'
+#' The [position documentation][aes_position].
 #' @examples
 #' last_month <- Sys.Date() - 0:29
 #' set.seed(1)

R/scale-discrete-.R

@@ -14,6 +14,8 @@
 #' @inheritParams discrete_scale
 #' @rdname scale_discrete
 #' @family position scales
+#' @seealso
+#' The [position documentation][aes_position].
 #' @export
 #' @examples
 #' ggplot(diamonds, aes(cut)) + geom_bar()

R/scale-gradient.R

@@ -19,6 +19,8 @@
 #' @inheritDotParams continuous_scale -na.value -guide -aesthetics
 #' @seealso [scales::seq_gradient_pal()] for details on underlying
 #'   palette, [scale_colour_steps()] for binned variants of these scales.
+#'
+#'   The documentation on [colour aesthetics][aes_colour_fill_alpha].
 #' @family colour scales
 #' @rdname scale_gradient
 #' @export

R/scale-grey.R

@@ -7,6 +7,8 @@
 #' @inheritParams scale_colour_hue
 #' @inheritDotParams discrete_scale
 #' @family colour scales
+#' @seealso
+#' The documentation on [colour aesthetics][aes_colour_fill_alpha].
 #' @rdname scale_grey
 #' @export
 #' @examples

R/scale-hue.R

@@ -13,6 +13,8 @@
 #' @rdname scale_hue
 #' @export
 #' @family colour scales
+#' @seealso
+#' The documentation on [colour aesthetics][aes_colour_fill_alpha].
 #' @examples
 #' \donttest{
 #' set.seed(596)

R/scale-identity.R

@@ -21,6 +21,7 @@
 #'   example, to apply colour settings to the `colour` and `fill` aesthetics at the
 #'   same time, via `aesthetics = c("colour", "fill")`.
 #' @param guide Guide to use for this scale. Defaults to `"none"`.
+#' @family colour scales
 #' @examples
 #' ggplot(luv_colours, aes(u, v)) +
 #'   geom_point(aes(colour = col), size = 3) +
@@ -78,6 +79,8 @@ scale_fill_identity <- function(..., guide = "none", aesthetics = "fill") {
 }
 
 #' @rdname scale_identity
+#' @seealso
+#' Other shape scales: [scale_shape()], [scale_shape_manual()].
 #' @export
 scale_shape_identity <- function(..., guide = "none") {
   sc <- continuous_scale("shape", "identity", identity_pal(), ..., guide = guide,
@@ -87,6 +90,8 @@ scale_shape_identity <- function(..., guide = "none") {
 }
 
 #' @rdname scale_identity
+#' @seealso
+#' Other linetype scales: [scale_linetype()], [scale_linetype_manual()].
 #' @export
 scale_linetype_identity <- function(..., guide = "none") {
   sc <- discrete_scale("linetype", "identity", identity_pal(), ..., guide = guide,
@@ -96,6 +101,8 @@ scale_linetype_identity <- function(..., guide = "none") {
 }
 
 #' @rdname scale_identity
+#' @seealso
+#' Other alpha scales: [scale_alpha()], [scale_alpha_manual()].
 #' @export
 scale_linewidth_identity <- function(..., guide = "none") {
   sc <- continuous_scale("linewidth", "identity", identity_pal(), ...,
@@ -114,6 +121,8 @@ scale_alpha_identity <- function(..., guide = "none") {
 }
 
 #' @rdname scale_identity
+#' @seealso
+#' Other size scales: [scale_size()], [scale_size_manual()].
 #' @export
 scale_size_identity <- function(..., guide = "none") {
   sc <- continuous_scale("size", "identity", identity_pal(), ..., guide = guide,

R/scale-linetype.R

@@ -9,6 +9,10 @@
 #' @inheritDotParams discrete_scale -expand -position -na.value
 #' @param na.value The linetype to use for `NA` values.
 #' @rdname scale_linetype
+#' @seealso
+#' The documentation for [differentiation related aesthetics][aes_linetype_size_shape].
+#'
+#' Other linetype scales: [scale_linetype_manual()], [scale_linetype_identity()].
 #' @export
 #' @examples
 #' base <- ggplot(economics_long, aes(date, value01))

R/scale-linewidth.R

@@ -8,6 +8,8 @@
 #' @name scale_linewidth
 #' @inheritParams continuous_scale
 #' @inheritParams binned_scale
+#' @seealso
+#' The documentation for [differentiation related aesthetics][aes_linetype_size_shape].
 #' @param range a numeric vector of length 2 that specifies the minimum and
 #'   maximum size of the plotting symbol after transformation.
 #' @examples

R/scale-manual.R

@@ -29,6 +29,11 @@
 #'   - A function that takes the limits as input and returns breaks
 #'     as output
 #' @param na.value The aesthetic value to use for missing (`NA`) values
+#' @family colour scales
+#' @seealso
+#' The documentation for [differentiation related aesthetics][aes_linetype_size_shape].
+#'
+#' The documentation on [colour aesthetics][aes_colour_fill_alpha].
 #'
 #' @section Color Blindness:
 #' Many color palettes derived from RGB combinations (like the "rainbow" color
@@ -93,24 +98,32 @@ scale_fill_manual <- function(..., values, aesthetics = "fill", breaks = waiver(
 }
 
 #' @rdname scale_manual
+#' @seealso
+#' Other size scales: [scale_size()], [scale_size_identity()].
 #' @export
 scale_size_manual <- function(..., values, breaks = waiver(), na.value = NA) {
   manual_scale("size", values, breaks, ..., na.value = na.value)
 }
 
 #' @rdname scale_manual
+#' @seealso
+#' Other shape scales: [scale_shape()], [scale_shape_identity()].
 #' @export
 scale_shape_manual <- function(..., values, breaks = waiver(), na.value = NA) {
   manual_scale("shape", values, breaks, ..., na.value = na.value)
 }
 
 #' @rdname scale_manual
+#' @seealso
+#' Other linetype scales: [scale_linetype()], [scale_linetype_identity()].
 #' @export
 scale_linetype_manual <- function(..., values, breaks = waiver(), na.value = "blank") {
   manual_scale("linetype", values, breaks, ..., na.value = na.value)
 }
 
 #' @rdname scale_manual
+#' @seealso
+#' Other alpha scales: [scale_alpha()], [scale_alpha_identity()].
 #' @export
 scale_linewidth_manual <- function(..., values, breaks = waiver(), na.value = NA) {
   manual_scale("linewidth", values, breaks, ..., na.value = na.value)

R/scale-shape.R

@@ -12,6 +12,10 @@
 #' @inheritParams scale_x_discrete
 #' @inheritDotParams discrete_scale -expand -position
 #' @rdname scale_shape
+#' @seealso
+#' The documentation for [differentiation related aesthetics][aes_linetype_size_shape].
+#'
+#' Other shape scales: [scale_shape_manual()], [scale_shape_identity()].
 #' @export
 #' @examples
 #' set.seed(596)

R/scale-size.R

@@ -22,6 +22,8 @@
 #' @seealso [scale_size_area()] if you want 0 values to be mapped
 #'   to points with size 0. [scale_linewidth()] if you want to scale the width
 #'   of lines.
+#'
+#'   The documentation for [differentiation related aesthetics][aes_linetype_size_shape].
 #' @examples
 #' p <- ggplot(mpg, aes(displ, hwy, size = hwy)) +
 #'    geom_point()