improve aesthetic documentation (#3788)

* improve aesthetic documentation

* rewording alpha description

* clean up colour fill alpha docs

* clean up aes group order

* cleanup linetype size shape

* clean up aes position

* minor cleanup

* copy edits

* copy edit

Co-authored-by: Claus Wilke <wilke@austin.utexas.edu>

Author: rivaquiroga

DESCRIPTION

@@ -262,6 +262,6 @@ Collate:
     'zxx.r'
     'zzz.r'
 VignetteBuilder: knitr
-RoxygenNote: 7.0.2
+RoxygenNote: 7.1.0
 Roxygen: list(markdown = TRUE)
 Encoding: UTF-8

R/aes-colour-fill-alpha.r

@@ -39,57 +39,62 @@
 #' [scale_fill_hue()], [scale_fill_identity()],
 #' [scale_fill_manual()], [scale_fill_viridis_d()]
 #' * Other options for modifying alpha: [scale_alpha()]
-#' * `vignette("ggplot2-specs")` provides an overview of other aesthestics that
-#' can be modified
+#' * Run `vignette("ggplot2-specs")` to see an overview of other aesthestics that
+#' can be modified.
 #'
 #' @name aes_colour_fill_alpha
 #' @aliases colour color fill
 #' @examples
 #' \donttest{
 #'
 #' # Bar chart example
-#' c <- ggplot(mtcars, aes(factor(cyl)))
+#' p <- ggplot(mtcars, aes(factor(cyl)))
 #' # Default plotting
-#' c + geom_bar()
+#' p + geom_bar()
 #' # To change the interior colouring use fill aesthetic
-#' c + geom_bar(fill = "red")
+#' p + geom_bar(fill = "red")
 #' # Compare with the colour aesthetic which changes just the bar outline
-#' c + geom_bar(colour = "red")
+#' p + geom_bar(colour = "red")
 #' # Combining both, you can see the changes more clearly
-#' c + geom_bar(fill = "white", colour = "red")
+#' p + geom_bar(fill = "white", colour = "red")
+#' # Both colour and fill can take an rgb specification.
+#' p + geom_bar(fill = "#00abff")
+#' # Use NA for a completely transparent colour.
+#' p + geom_bar(fill = NA, colour = "#00abff")
 #'
-#' # The aesthetic fill also takes different colouring scales
-#' # setting fill equal to a factor variable uses a discrete colour scale
-#' k <- ggplot(mtcars, aes(factor(cyl), fill = factor(vs)))
-#' k + geom_bar()
+#' # Colouring scales differ depending on whether a discrete or
+#' # continuous variable is being mapped. For example, when mapping
+#' # fill to a factor variable, a discrete colour scale is used.
+#' ggplot(mtcars, aes(factor(cyl), fill = factor(vs))) + geom_bar()
 #'
-#' # Fill aesthetic can also be used with a continuous variable
-#' m <- ggplot(faithfuld, aes(waiting, eruptions))
-#' m + geom_raster()
-#' m + geom_raster(aes(fill = density))
+#' # When mapping fill to continuous variable a continuous colour
+#' # scale is used.
+#' ggplot(faithfuld, aes(waiting, eruptions)) +
+#'   geom_raster(aes(fill = density))
 #'
-#' # Some geoms don't use both aesthetics (i.e. geom_point or geom_line)
-#' b <- ggplot(economics, aes(x = date, y = unemploy))
-#' b + geom_line()
-#' b + geom_line(colour = "green")
-#' b + geom_point()
-#' b + geom_point(colour = "red")
+#' # Some geoms only use the colour aesthetic but not the fill
+#' # aesthetic (e.g. geom_point() or geom_line()).
+#' p <- ggplot(economics, aes(x = date, y = unemploy))
+#' p + geom_line()
+#' p + geom_line(colour = "green")
+#' p + geom_point()
+#' p + geom_point(colour = "red")
 #'
 #' # For large datasets with overplotting the alpha
-#' # aesthetic will make the points more transparent
+#' # aesthetic will make the points more transparent.
 #' df <- data.frame(x = rnorm(5000), y = rnorm(5000))
-#' h  <- ggplot(df, aes(x,y))
-#' h + geom_point()
-#' h + geom_point(alpha = 0.5)
-#' h + geom_point(alpha = 1/10)
+#' p  <- ggplot(df, aes(x,y))
+#' p + geom_point()
+#' p + geom_point(alpha = 0.5)
+#' p + geom_point(alpha = 1/10)
 #'
-#' # Alpha can also be used to add shading
-#' j <- b + geom_line()
-#' j
+#' # Alpha can also be used to add shading.
+#' p <- ggplot(economics, aes(x = date, y = unemploy)) + geom_line()
+#' p
 #' yrng <- range(economics$unemploy)
-#' j <- j + geom_rect(aes(NULL, NULL, xmin = start, xmax = end, fill = party),
+#' p <- p + geom_rect(aes(NULL, NULL, xmin = start, xmax = end, fill = party),
 #' ymin = yrng[1], ymax = yrng[2], data = presidential)
-#' j
-#' j + scale_fill_manual(values = alpha(c("blue", "red"), .3))
+#' p
+#' p + scale_fill_manual(values = alpha(c("blue", "red"), .3))
 #' }
 NULL

R/aes-group-order.r

@@ -3,74 +3,78 @@
 #' @name aes_group_order
 #' @aliases group
 #'
-#' @examples
-#' \donttest{
+#' @description
+#' The `group` aesthetic is by default set to the interaction of all discrete variables
+#' in the plot. This choice often partitions the data correctly, but when it does not,
+#' or when no discrete variable is used in the plot, you will need to explicitly define the
+#' grouping structure by mapping `group` to a variable that has a different value
+#' for each group.
+#'
+#' @details
+#' For most applications the grouping is set implicitly by mapping one or more
+#' discrete variables to `x`, `y`, `colour`, `fill`, `alpha`, `shape`, `size`,
+#' and/or `linetype`. This is demonstrated in the examples below.
+#'
+#' There are three common cases where the default does not display the data correctly.
+#' 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).
 #'
-#' # By default, the group is set to the interaction of all discrete variables in the
-#' # plot. This often partitions the data correctly, but when it does not, or when
-#' # no discrete variable is used in the plot, you will need to explicitly define the
-#' # grouping structure, by mapping group to a variable that has a different value
-#' # for each group.
+#' @seealso
+#' * Geoms commonly used with groups: [geom_bar()], [geom_histogram()], [geom_line()]
+#' * Run `vignette("ggplot2-specs")` to see an overview of other aesthestics that
+#' can be modified.
 #'
-#' # For most applications you can simply specify the grouping with
-#' # various aesthetics (colour, shape, fill, linetype) or with facets.
+#' @examples
+#' \donttest{
 #'
 #' p <- ggplot(mtcars, aes(wt, mpg))
 #' # A basic scatter plot
 #' p + geom_point(size = 4)
-#' # The colour aesthetic
+#' # Using the colour aesthetic
 #' p + geom_point(aes(colour = factor(cyl)), size = 4)
-#' # Or you can use shape to distinguish the data
+#' # Using the shape aesthetic
 #' p + geom_point(aes(shape = factor(cyl)), size = 4)
 #'
 #' # Using fill
-#' a <- ggplot(mtcars, aes(factor(cyl)))
-#' a + geom_bar()
-#' a + geom_bar(aes(fill = factor(cyl)))
-#' a + geom_bar(aes(fill = factor(vs)))
+#' p <- ggplot(mtcars, aes(factor(cyl)))
+#' p + geom_bar()
+#' p + geom_bar(aes(fill = factor(cyl)))
+#' p + geom_bar(aes(fill = factor(vs)))
 #'
 #' # Using linetypes
-#' f <- ggplot(economics_long, aes(date, value01))
-#' f + geom_line(aes(linetype = variable))
-#'
-#' # Using facets
-#' k <- ggplot(diamonds, aes(carat, after_stat(density))) +
-#'   geom_histogram(binwidth = 0.2)
-#' k + facet_grid(. ~ cut)
-#'
-#' # There are three common cases where the default is not enough, and we
-#' # will consider each one below. In the following examples, we will use a simple
-#' # longitudinal dataset, Oxboys, from the nlme package. It records the heights
-#' # (height) and centered ages (age) of 26 boys (Subject), measured on nine
-#' # occasions (Occasion).
+#' ggplot(economics_long, aes(date, value01)) +
+#'   geom_line(aes(linetype = variable))
 #'
 #' # Multiple groups with one aesthetic
-#' h <- ggplot(nlme::Oxboys, aes(age, height))
-#' # A single line tries to connect all the observations
-#' h + geom_line()
-#' # The group aesthetic maps a different line for each subject
-#' h + geom_line(aes(group = Subject))
+#' p <- ggplot(nlme::Oxboys, aes(age, height))
+#' # The default is not sufficient here. A single line tries to connect all
+#' # the observations.
+#' p + geom_line()
+#' # To fix this, use the group aesthetic to map a different line for each
+#' # subject.
+#' p + geom_line(aes(group = Subject))
 #'
 #' # Different groups on different layers
-#' h <- h + geom_line(aes(group = Subject))
+#' p <- p + geom_line(aes(group = Subject))
 #' # Using the group aesthetic with both geom_line() and geom_smooth()
 #' # groups the data the same way for both layers
-#' h + geom_smooth(aes(group = Subject), method = "lm", se = FALSE)
+#' p + geom_smooth(aes(group = Subject), method = "lm", se = FALSE)
 #' # Changing the group aesthetic for the smoother layer
 #' # fits a single line of best fit across all boys
-#' h + geom_smooth(aes(group = 1), size = 2, method = "lm", se = FALSE)
+#' p + geom_smooth(aes(group = 1), size = 2, method = "lm", se = FALSE)
 #'
 #' # Overriding the default grouping
-#' # The plot has a discrete scale but you want to draw lines that connect across
-#' # groups. This is the strategy used in interaction plots, profile plots, and parallel
-#' # coordinate plots, among others. For example, we draw boxplots of height at
-#' # each measurement occasion
-#' boysbox <- ggplot(nlme::Oxboys, aes(Occasion, height))
-#' boysbox + geom_boxplot()
+#' # Sometimes the plot has a discrete scale but you want to draw lines
+#' # that connect across groups. This is the strategy used in interaction
+#' # plots, profile plots, and parallel coordinate plots, among others.
+#' # For example, we draw boxplots of height at each measurement occasion.
+#' p <- ggplot(nlme::Oxboys, aes(Occasion, height)) + geom_boxplot()
+#' p
 #' # There is no need to specify the group aesthetic here; the default grouping
-#' # works because occasion is a discrete variable. To overlay individual trajectories
-#' # we again need to override the default grouping for that layer with aes(group = Subject)
-#' boysbox <- boysbox + geom_boxplot()
-#' boysbox + geom_line(aes(group = Subject), colour = "blue")
+#' # works because occasion is a discrete variable. To overlay individual
+#' # trajectories, we again need to override the default grouping for that layer
+#' # with aes(group = Subject)
+#' p + geom_line(aes(group = Subject), colour = "blue")
 #' }
 NULL

R/aes-linetype-size-shape.r

@@ -1,64 +1,74 @@
 #' Differentiation related aesthetics: linetype, size, shape
 #'
-#' This page demonstrates the usage of a sub-group
-#' of aesthetics; linetype, size and 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` 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.
+#'
+#' 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.
+#'
+#' @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
+#' can be modified.
 #' @name aes_linetype_size_shape
 #' @aliases linetype size shape
 #' @examples
 #'
-#' # Line types should be specified with either an integer, a name, or with a string of
-#' # an even number (up to eight) of hexadecimal digits which give the lengths in
-#' # consecutive positions in the string.
-#' # 0 = blank, 1 = solid, 2 = dashed, 3 = dotted, 4 = dotdash, 5 = longdash, 6 = twodash
-#'
-#' # Data
 #' df <- data.frame(x = 1:10 , y = 1:10)
-#' f <- ggplot(df, aes(x, y))
-#' f + geom_line(linetype = 2)
-#' f + geom_line(linetype = "dotdash")
+#' p <- ggplot(df, aes(x, y))
+#' p + geom_line(linetype = 2)
+#' p + geom_line(linetype = "dotdash")
 #'
-#' # An example with hex strings, the string "33" specifies three units on followed
+#' # An example with hex strings; the string "33" specifies three units on followed
 #' # by three off and "3313" specifies three units on followed by three off followed
 #' # by one on and finally three off.
-#' f + geom_line(linetype = "3313")
+#' p + geom_line(linetype = "3313")
 #'
-#' # Mapping line type from a variable
+#' # Mapping line type from a grouping variable
 #' ggplot(economics_long, aes(date, value01)) +
 #'   geom_line(aes(linetype = variable))
 #'
 #' # Size examples
-#' # Should be specified with a numerical value (in millimetres),
-#' # or from a variable source
 #' p <- ggplot(mtcars, aes(wt, mpg))
 #' p + geom_point(size = 4)
 #' p + geom_point(aes(size = qsec))
 #' p + geom_point(size = 2.5) +
 #'   geom_hline(yintercept = 25, size = 3.5)
 #'
 #' # Shape examples
-#' # Shape takes four types of values: an integer in [0, 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
 #' p + geom_point()
 #' p + geom_point(shape = 5)
 #' p + geom_point(shape = "k", size = 3)
 #' p + geom_point(shape = ".")
 #' p + geom_point(shape = NA)
-#'
-#' # Shape can also be mapped from a variable
 #' p + geom_point(aes(shape = factor(cyl)))
 #'
 #' # A look at all 25 symbols
 #' df2 <- data.frame(x = 1:5 , y = 1:25, z = 1:25)
-#' s <- ggplot(df2, aes(x, y))
-#' s + geom_point(aes(shape = z), size = 4) +
+#' p <- ggplot(df2, aes(x, y))
+#' p + geom_point(aes(shape = z), size = 4) +
 #'   scale_shape_identity()
 #' # While all symbols have a foreground colour, symbols 19-25 also take a
 #' # background colour (fill)
-#' s + geom_point(aes(shape = z), size = 4, colour = "Red") +
+#' p + geom_point(aes(shape = z), size = 4, colour = "Red") +
 #'   scale_shape_identity()
-#' s + geom_point(aes(shape = z), size = 4, colour = "Red", fill = "Black") +
+#' p + geom_point(aes(shape = z), size = 4, colour = "Red", fill = "Black") +
 #'   scale_shape_identity()
 NULL