From 1b6083979401a1e7ae9bd54c14d85f55048ef18a Mon Sep 17 00:00:00 2001 From: Teun van den Brand <49372158+teunbrand@users.noreply.github.com> Date: Tue, 27 Feb 2024 15:17:45 +0100 Subject: [PATCH] Improve layer documentation (#5127) * Explicit `...` argument for layers * Write more expanded docs for geom/stat/position * Describe stat/geom/position more * Link up non-default geom/stat params to docs * Document * Add topics to pkgdown * reoxygenate --- DESCRIPTION | 1 + R/docs_layer.R | 382 +++++++++++++++++++++++++++++++++++++ R/geom-bar.R | 3 +- R/geom-bin2d.R | 4 +- R/geom-boxplot.R | 4 +- R/geom-count.R | 4 +- R/geom-density.R | 4 +- R/geom-density2d.R | 4 +- R/geom-hex.R | 3 +- R/geom-histogram.R | 4 +- R/geom-point.R | 28 ++- R/geom-quantile.R | 4 +- R/geom-smooth.R | 4 +- R/geom-text.R | 13 +- R/geom-violin.R | 4 +- R/layer.R | 43 +++-- _pkgdown.yml | 3 + man/annotate.Rd | 29 ++- man/borders.Rd | 32 +++- man/geom_abline.Rd | 29 ++- man/geom_bar.Rd | 50 ++++- man/geom_bin_2d.Rd | 51 ++++- man/geom_blank.Rd | 61 ++++-- man/geom_boxplot.Rd | 51 ++++- man/geom_contour.Rd | 80 ++++++-- man/geom_count.Rd | 51 ++++- man/geom_density.Rd | 51 ++++- man/geom_density_2d.Rd | 20 +- man/geom_dotplot.Rd | 47 ++++- man/geom_errorbarh.Rd | 61 ++++-- man/geom_function.Rd | 80 ++++++-- man/geom_hex.Rd | 50 ++++- man/geom_histogram.Rd | 51 ++++- man/geom_jitter.Rd | 65 +++++-- man/geom_linerange.Rd | 65 +++++-- man/geom_map.Rd | 47 ++++- man/geom_path.Rd | 65 +++++-- man/geom_point.Rd | 65 +++++-- man/geom_polygon.Rd | 63 ++++-- man/geom_qq.Rd | 64 +++++-- man/geom_quantile.Rd | 51 ++++- man/geom_ribbon.Rd | 80 ++++++-- man/geom_rug.Rd | 65 +++++-- man/geom_segment.Rd | 65 +++++-- man/geom_smooth.Rd | 51 ++++- man/geom_spoke.Rd | 61 ++++-- man/geom_text.Rd | 64 +++++-- man/geom_tile.Rd | 65 +++++-- man/geom_violin.Rd | 51 ++++- man/ggsf.Rd | 78 ++++++-- man/layer.Rd | 54 ++++-- man/layer_geoms.Rd | 144 ++++++++++++++ man/layer_positions.Rd | 117 ++++++++++++ man/layer_sf.Rd | 47 +++-- man/layer_stats.Rd | 141 ++++++++++++++ man/stat_ecdf.Rd | 64 +++++-- man/stat_ellipse.Rd | 64 +++++-- man/stat_identity.Rd | 60 ++++-- man/stat_sf_coordinates.Rd | 62 ++++-- man/stat_summary.Rd | 64 +++++-- man/stat_summary_2d.Rd | 64 +++++-- man/stat_unique.Rd | 60 ++++-- 62 files changed, 2796 insertions(+), 516 deletions(-) create mode 100644 R/docs_layer.R create mode 100644 man/layer_geoms.Rd create mode 100644 man/layer_positions.Rd create mode 100644 man/layer_stats.Rd diff --git a/DESCRIPTION b/DESCRIPTION index 89b0a43129..709d400b76 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -121,6 +121,7 @@ Collate: 'coord-sf.R' 'coord-transform.R' 'data.R' + 'docs_layer.R' 'facet-.R' 'facet-grid-.R' 'facet-null.R' diff --git a/R/docs_layer.R b/R/docs_layer.R new file mode 100644 index 0000000000..108e126196 --- /dev/null +++ b/R/docs_layer.R @@ -0,0 +1,382 @@ +# Geoms ------------------------------------------------------------------- + +#' @title +#' Layer geometry display +#' +#' @description +#' In ggplot2, a plot in constructed by adding layers to it. A layer consists +#' of two important parts: the geometry (geoms), and statistical transformations +#' (stats). The 'geom' part of a layer is important because it determines the +#' looks of the data. Geoms determine *how* something is displayed, not *what* +#' is displayed. +#' +#' @details +#' # Specifying geoms +#' There are five ways in which the 'geom' part of a layer can be specified. +#' +#' ```r +#' # 1. The geom can have a layer constructor +#' geom_area() +#' +#' # 2. A stat can default to a particular geom +#' stat_density() # has `geom = "area"` as default +#' +#' # 3. It can be given to a stat as a string +#' stat_function(geom = "area") +#' +#' # 4. The ggproto object of a geom can be given +#' stat_bin(geom = GeomArea) +#' +#' # 5. It can be given to `layer()` directly +#' layer( +#' geom = "area", +#' stat = "smooth", +#' position = "identity" +#' ) +#' ``` +#' +#' Many of these ways are absolutely equivalent. Using +#' `stat_density(geom = "line")` is identical to using +#' `geom_line(stat = "density")`. Note that for [`layer()`], you need to +#' provide the `"position"` argument as well. To give geoms as a string, take +#' the function name, and remove the `geom_` prefix, such that `geom_point` +#' becomes `"point"`. +#' +#' Some of the more well known geoms that can be used for the `geom` argument +#' are: [`"point"`][geom_point()], [`"line"`][geom_line()], +#' [`"area"`][geom_area()], [`"bar"`][geom_bar()] and +#' [`"polygon"`][geom_polygon]. +#' +#' # Graphical display +#' A ggplot is build on top of the [grid][grid-package] package. This package +#' understands various graphical primitives, such as points, lines, rectangles +#' and polygons and their [positions][aes_position], as well as graphical +#' attributes, also termed aesthetics, such as +#' [colours, fills][aes_colour_fill_alpha], +#' [linewidths and linetypes][aes_linetype_size_shape]. The job of the geom part +#' of a layer, is to translate data to grid graphics that can be plotted. +#' +#' To see how aesthetics are specified, run `vignette("ggplot2-specs")`. To see +#' what geom uses what aesthetics, you can find the **Aesthetics** section in +#' their documentation, for example in [`?geom_line`][geom_line()]. +#' +#' While almost anything can be represented by polygons if you try hard enough, +#' it is not always convenient to do so manually. For this reason, the geoms +#' provide abstractions that take most of this hassle away. [`geom_ribbon()`] +#' for example is a special case of [`geom_polygon()`], where two sets of +#' y-positions have a shared x-position. In turn, [`geom_area()`] is a special +#' case of a ribbon, where one of the two sets of y-positions is set at 0. +#' +#' ```r +#' # A hassle to build a polygon +#' my_polygon <- data.frame( +#' x = c(economics$date, rev(economics$date)), +#' y = c(economics$uempmed, rev(economics$psavert)) +#' ) +#' ggplot(my_polygon, aes(x, y)) + +#' geom_polygon() +#' +#' # More succinctly +#' ggplot(economics, aes(date)) + +#' geom_ribbon(aes(ymin = uempmed, ymax = psavert)) +#' ``` +#' +#' In addition to abstraction, geoms sometimes also perform composition. +#' A boxplot is a particular arrangement of lines, rectangles and points that +#' people have agreed upon is a summary of some data, which is performed by +#' [`geom_boxplot()`]. +#' +#' ```r +#' Boxplot data +#' value <- fivenum(rnorm(100)) +#' df <- data.frame( +#' min = value[1], lower = value[2], middle = value[3], +#' upper = value[4], max = value[5] +#' ) +#' +#' # Drawing a boxplot manually +#' ggplot(df, aes(x = 1, xend = 1)) + +#' geom_rect( +#' aes( +#' xmin = 0.55, xmax = 1.45, +#' ymin = lower, ymax = upper +#' ), +#' colour = "black", fill = "white" +#' ) + +#' geom_segment( +#' aes( +#' x = 0.55, xend = 1.45, +#' y = middle, yend = middle +#' ), +#' size = 1 +#' ) + +#' geom_segment(aes(y = lower, yend = min)) + +#' geom_segment(aes(y = upper, yend = max)) +#' +#' # More succinctly +#' ggplot(df, aes(x = 1)) + +#' geom_boxplot( +#' aes(ymin = min, ymax = max, +#' lower = lower, upper = upper, +#' middle = middle), +#' stat = "identity" +#' ) +#' ``` +#' +#' # Under the hood +#' Internally, geoms are represented as [`ggproto`][ggproto()] classes that +#' occupy a slot in a layer. All these classes inherit from the parental +#' [`Geom`] ggproto object that orchestrates how geoms work. Briefly, geoms +#' are given the opportunity to draw the data of the layer as a whole, +#' a facet panel, or of individual groups. For more information on extending +#' geoms, see the **Creating a new geom** section after running +#' `vignette("extending-ggplot2")`. Additionally, see the **New geoms** section +#' of the [online book](https://ggplot2-book.org/extensions.html#new-geoms). +#' +#' @seealso +#' For an overview of all geom layers, see the +#' [online reference](https://ggplot2.tidyverse.org/reference/index.html#geoms). +#' +#' @family layer documentation +#' +#' @name layer_geoms +NULL + +# Stats ------------------------------------------------------------------- + +#' @title +#' Layer statistical transformations +#' +#' @description +#' In ggplot2, a plot is constructed by adding layers to it. A layer consists +#' of two important parts: the geometry (geoms), and statistical transformations +#' (stats). The 'stat' part of a layer is important because it performs a +#' computation on the data before it is displayed. Stats determine *what* is +#' displayed, not *how* it is displayed. +#' +#' For example, if you add [`stat_density()`] to a plot, a kernel density +#' estimation is performed, which can be displayed with the 'geom' part of a +#' layer. For many `geom_*()` functions, [`stat_identity()`] is used, +#' which performs no extra computation on the data. +#' +#' @details +#' # Specifying stats +#' There are five ways in which the 'stat' part of a layer can be specified. +#' +#' ```r +#' # 1. The stat can have a layer constructor +#' stat_density() +#' +#' # 2. A geom can default to a particular stat +#' geom_density() # has `stat = "density"` as default +#' +#' # 3. It can be given to a geom as a string +#' geom_line(stat = "density") +#' +#' # 4. The ggproto object of a stat can be given +#' geom_area(stat = StatDensity) +#' +#' # 5. It can be given to `layer()` directly: +#' layer( +#' geom = "line", +#' stat = "density", +#' position = "identity" +#' ) +#' ``` +#' +#' Many of these ways are absolutely equivalent. Using +#' `stat_density(geom = "line")` is identical to using +#' `geom_line(stat = "density")`. Note that for [`layer()`], you need to +#' provide the `"position"` argument as well. To give stats as a string, take +#' the function name, and remove the `stat_` prefix, such that `stat_bin` +#' becomes `"bin"`. +#' +#' Some of the more well known stats that can be used for the `stat` argument +#' are: [`"density"`][stat_density()], [`"bin"`][stat_bin()], +#' [`"count"`][stat_count()], [`"function"`][stat_function()] and +#' [`"smooth"`][stat_smooth()]. +#' +#' # Paired geoms and stats +#' Some geoms have paired stats. In some cases, like [`geom_density()`], it is +#' just a variant of another geom, [`geom_area()`], with slightly different +#' defaults. +#' +#' In other cases, the relationship is more complex. In the case of boxplots for +#' example, the stat and the geom have distinct roles. The role of the stat is +#' to compute the five-number summary of the data. In addition to just +#' displaying the box of the five-number summary, the geom also provides display +#' options for the outliers and widths of boxplots. In such cases, you cannot +#' freely exchange geoms and stats: using `stat_boxplot(geom = "line")` or +#' `geom_area(stat = "boxplot")` give errors. +#' +#' Some stats and geoms that are paired are: +#' * [`geom_violin()`] and [`stat_ydensity()`] +#' * [`geom_histogram()`] and [`stat_bin()`] +#' * [`geom_contour()`] and [`stat_contour()`] +#' * [`geom_function()`] and [`stat_function()`] +#' * [`geom_bin_2d()`] and [`stat_bin_2d()`] +#' * [`geom_boxplot()`] and [`stat_boxplot()`] +#' * [`geom_count()`] and [`stat_sum()`] +#' * [`geom_density()`] and [`stat_density()`] +#' * [`geom_density_2d()`] and [`stat_density_2d()`] +#' * [`geom_hex()`] and [`stat_binhex()`] +#' * [`geom_quantile()`] and [`stat_quantile()`] +#' * [`geom_smooth()`] and [`stat_smooth()`] +#' +#' # Using computed variables +#' As mentioned above, the role of stats is to perform computation on the data. +#' As a result, stats have 'computed variables' that determine compatibility +#' with geoms. These computed variables are documented in the +#' **Computed variables** sections of the documentation, for example in +#' [`?stat_bin`][stat_bin()]. While more thoroughly documented +#' in [`after_stat()`], it should briefly be mentioned that these computed stats +#' can be accessed in [`aes()`]. +#' +#' For example, the [`?stat_density`][stat_density()] documentation states that, +#' in addition to a variable called `density`, the stat computes a variable +#' named `count`. Instead of scaling such that the area integrates to 1, the +#' `count` variable scales the computed density such that the values +#' can be interpreted as counts. If `stat_density(aes(y = after_stat(count)))` +#' is used, we can display these count-scaled densities instead of the regular +#' densities. +#' +#' The computed variables offer flexibility in that arbitrary geom-stat pairings +#' can be made. While not necessarily recommended, [`geom_line()`] *can* be paired +#' with `stat = "boxplot"` if the line is instructed on how to use the boxplot +#' computed variables: +#' +#' ```r +#' ggplot(mpg, aes(factor(cyl))) + +#' geom_line( +#' # Stage gives 'displ' to the stat, and afterwards chooses 'middle' as +#' # the y-variable to display +#' aes(y = stage(displ, after_stat = middle), +#' # Regroup after computing the stats to display a single line +#' group = after_stat(1)), +#' stat = "boxplot" +#' ) +#' ``` +#' +#' # Under the hood +#' Internally, stats are represented as [`ggproto`][ggproto()] classes that +#' occupy a slot in a layer. All these classes inherit from the parental +#' [`Stat`] ggproto object that orchestrates how stats work. Briefly, stats +#' are given the opportunity to perform computation either on the layer as a +#' whole, a facet panel, or on individual groups. For more information on +#' extending stats, see the **Creating a new stat** section after +#' running `vignette("extending-ggplot2")`. Additionally, see the **New stats** +#' section of the +#' [online book](https://ggplot2-book.org/extensions.html#new-stats). +#' +#' @seealso +#' For an overview of all stat layers, see the +#' [online reference](https://ggplot2.tidyverse.org/reference/index.html#stats). +#' +#' How [computed aesthetics][after_stat()] work. +#' @family layer documentation +#' +#' @name layer_stats +NULL + +# Position ---------------------------------------------------------------- + +#' @title +#' Layer position adjustments +#' +#' @description +#' In ggplot2, a plot is constructed by adding layers to it. In addition to +#' [geoms][layer_geoms] and [stats][layer_stats], position adjustments are the +#' third required part of a layer. The 'position' part of a layer is responsible +#' for dodging, jittering and nudging groups of data to minimise their overlap, +#' or otherwise tweaking their positions. +#' +#' For example if you add `position = position_nudge(x = 1)` to a layer, you +#' can offset every x-position by 1. For many layers, the default position +#' adjustment is [`position_identity()`], which performs no adjustment. +#' +#' @details +#' # Specifying positions +#' There are 4 ways in which the 'position' part of a layer can be specified. +#' +#' ```r +#' 1. A layer can have default position adjustments +#' geom_jitter() # has `position = "jitter"` +#' +#' 2. It can be given to a layer as a string +#' geom_point(position = "jitter") +#' +#' 3. The position function can be used to pass extra arguments +#' geom_point(position = position_jitter(width = 1)) +#' +#' 4. It can be given to `layer()` directly +#' layer( +#' geom = "point", +#' stat = "identity", +#' position = "jitter" +#' ) +#' ``` +#' +#' These ways are not always equivalent. Some layers may not understand what +#' to do with a position adjustment, and require additional parameters passed +#' through the `position_*()` function, or may not work correctly. For +#' example [`position_dodge()`] requires non-overlapping x intervals, whereas +#' [`geom_point()`] doesn't have dimensions to calculate intervals for. To give +#' positions as a string, take the function name, and remove the `position_` +#' prefix, such that `position_fill` becomes `"fill"`. +#' +#' # Pairing geoms with positions +#' Some geoms work better with some positions than others. Below follows a brief +#' overview of geoms and position adjustments that work well together. +#' +#' ## Identity +#' [`position_identity()`] can work with virtually any geom. +#' +#' ## Dodging +#' [`position_dodge()`] pushes overlapping objects away from one another and +#' requires a `group` variable. [`position_dodge2()`] can work without group +#' variables and can handle variable widths. As a rule of thumb, layers where +#' groups occupy a range on the x-axis pair well with dodging. If layers have +#' no width, you may be required to specify it manually with +#' `position_dodge(width = ...)`. Some geoms that pair well with dodging are +#' [`geom_bar()`], [`geom_boxplot()`], [`geom_linerange()`], +#' [`geom_errorbar()`] and [`geom_text()`]. +#' +#' ## Jittering +#' [`position_jitter()`] adds a some random noise to every point, +#' which can help with overplotting. [`position_jitterdodge()`] does the same, +#' but also dodges the points. As a rule of thumb, jittering works best +#' when points have discrete x-positions. Jittering is most useful for +#' [`geom_point()`], but can also be used in [`geom_path()`] for example. +#' +#' ## Nudging +#' [`position_nudge()`] can add offsets to x- and y-positions. This can be +#' useful for discrete positions where you don't want to put an object +#' exactly in the middle. While most useful for [`geom_text()`], it can be +#' used with virtually all geoms. +#' +#' ## Stacking +#' [`position_stack()`] is useful for displaying data on top of one another. It +#' can be used for geoms that are usually anchored to the x-axis, for example +#' [`geom_bar()`], [`geom_area()`] or [`geom_histogram()`]. +#' +#' ## Filling +#' [`position_fill()`] can be used to give proportions at every x-position. Like +#' stacking, filling is most useful for geoms that are anchored to the x-axis, +#' like [`geom_bar()`], [`geom_area()`] or [`geom_histogram()`]. +#' +#' # Under the hood +#' Internally, positions are represented as [`ggproto`][ggproto()] classes that +#' occupy a slot in a layer. All these classes inherit from the parental +#' [`Position`] ggproto object that orchestrates how positions work. Briefly, +#' positions are given the opportunity to adjust the data of each facet panel. +#' For more information about extending positions, see the **New positions** +#' section of the +#' [online book](https://ggplot2-book.org/extensions.html#new-positions). +#' +#' @seealso +#' For an overview of all position adjustments, see the +#' [online reference](https://ggplot2.tidyverse.org/reference/index.html#position-adjustment). +#' @family layer documentation +#' +#' @name layer_positions +NULL diff --git a/R/geom-bar.R b/R/geom-bar.R index 7a3618d50b..e4611fbabb 100644 --- a/R/geom-bar.R +++ b/R/geom-bar.R @@ -48,7 +48,8 @@ #' @param width Bar width. By default, set to 90% of the [resolution()] of the #' data. #' @param geom,stat Override the default connection between `geom_bar()` and -#' `stat_count()`. +#' `stat_count()`. For more information about overriding these connections, +#' see how the [stat][layer_stats] and [geom][layer_geoms] arguments work. #' @examples #' # geom_bar is designed to make it easy to create bar charts that show #' # counts (or sums of weights) diff --git a/R/geom-bin2d.R b/R/geom-bin2d.R index c49a24fb1b..2fe756dc96 100644 --- a/R/geom-bin2d.R +++ b/R/geom-bin2d.R @@ -11,7 +11,9 @@ #' @inheritParams layer #' @inheritParams geom_point #' @param geom,stat Use to override the default connection between -#' `geom_bin_2d()` and `stat_bin_2d()`. +#' `geom_bin_2d()` and `stat_bin_2d()`. For more information about overriding +#' these connections, see how the [stat][layer_stats] and [geom][layer_geoms] +#' arguments work. #' @seealso [stat_bin_hex()] for hexagonal binning #' @examples #' d <- ggplot(diamonds, aes(x, y)) + xlim(4, 10) + ylim(4, 10) diff --git a/R/geom-boxplot.R b/R/geom-boxplot.R index 289c10cd97..f326cde4d5 100644 --- a/R/geom-boxplot.R +++ b/R/geom-boxplot.R @@ -32,7 +32,9 @@ #' @inheritParams layer #' @inheritParams geom_bar #' @param geom,stat Use to override the default connection between -#' `geom_boxplot()` and `stat_boxplot()`. +#' `geom_boxplot()` and `stat_boxplot()`. For more information about +#' overriding these connections, see how the [stat][layer_stats] and +#' [geom][layer_geoms] arguments work. #' @param outliers Whether to display (`TRUE`) or discard (`FALSE`) outliers #' from the plot. Hiding or discarding outliers can be useful when, for #' example, raw data points need to be displayed on top of the boxplot. diff --git a/R/geom-count.R b/R/geom-count.R index 977577265a..37b2e2922e 100644 --- a/R/geom-count.R +++ b/R/geom-count.R @@ -6,7 +6,9 @@ #' #' @eval rd_aesthetics("geom", "point") #' @param geom,stat Use to override the default connection between -#' `geom_count()` and `stat_sum()`. +#' `geom_count()` and `stat_sum()`. For more information about overriding +#' these connections, see how the [stat][layer_stats] and [geom][layer_geoms] +#' arguments work. #' @seealso For continuous `x` and `y`, use [geom_bin_2d()]. #' @inheritParams layer #' @inheritParams geom_point diff --git a/R/geom-density.R b/R/geom-density.R index 281f90eb0b..c71a9f98eb 100644 --- a/R/geom-density.R +++ b/R/geom-density.R @@ -14,7 +14,9 @@ #' @inheritParams geom_bar #' @inheritParams geom_ribbon #' @param geom,stat Use to override the default connection between -#' `geom_density()` and `stat_density()`. +#' `geom_density()` and `stat_density()`. For more information about +#' overriding these connections, see how the [stat][layer_stats] and +#' [geom][layer_geoms] arguments work. #' @export #' @examples #' ggplot(diamonds, aes(carat)) + diff --git a/R/geom-density2d.R b/R/geom-density2d.R index 9c21c5d298..e95a8b2c31 100644 --- a/R/geom-density2d.R +++ b/R/geom-density2d.R @@ -12,7 +12,9 @@ #' how contours are drawn; [geom_bin_2d()] for another way of dealing with #' overplotting. #' @param geom,stat Use to override the default connection between -#' `geom_density_2d()` and `stat_density_2d()`. +#' `geom_density_2d()` and `stat_density_2d()`. For more information at +#' overriding these connections, see how the [stat][layer_stats] and +#' [geom][layer_geoms] arguments work. #' @inheritParams layer #' @inheritParams geom_point #' @inheritParams geom_path diff --git a/R/geom-hex.R b/R/geom-hex.R index e3027096f1..6f9e9b4eb9 100644 --- a/R/geom-hex.R +++ b/R/geom-hex.R @@ -8,7 +8,8 @@ #' @eval rd_aesthetics("geom", "hex") #' @seealso [stat_bin_2d()] for rectangular binning #' @param geom,stat Override the default connection between `geom_hex()` and -#' `stat_bin_hex()`. +#' `stat_bin_hex()`. For more information about overriding these connections, +#' see how the [stat][layer_stats] and [geom][layer_geoms] arguments work. #' @export #' @inheritParams layer #' @inheritParams geom_point diff --git a/R/geom-histogram.R b/R/geom-histogram.R index 07685eaf19..dafc181f15 100644 --- a/R/geom-histogram.R +++ b/R/geom-histogram.R @@ -31,7 +31,9 @@ #' @inheritParams layer #' @inheritParams geom_bar #' @param geom,stat Use to override the default connection between -#' `geom_histogram()`/`geom_freqpoly()` and `stat_bin()`. +#' `geom_histogram()`/`geom_freqpoly()` and `stat_bin()`. For more information +#' at overriding these connections, see how the [stat][layer_stats] and +#' [geom][layer_geoms] arguments work. #' @examples #' ggplot(diamonds, aes(carat)) + #' geom_histogram() diff --git a/R/geom-point.R b/R/geom-point.R index 1b39a11d46..94d7fa248c 100644 --- a/R/geom-point.R +++ b/R/geom-point.R @@ -31,10 +31,30 @@ #' @inheritParams layer #' @param na.rm If `FALSE`, the default, missing values are removed with #' a warning. If `TRUE`, missing values are silently removed. -#' @param ... Other arguments passed on to [layer()]. These are -#' often aesthetics, used to set an aesthetic to a fixed value, like -#' `colour = "red"` or `size = 3`. They may also be parameters -#' to the paired geom/stat. +#' @param ... Other arguments passed on to [layer()]'s `params` argument. These +#' arguments broadly fall into one of 4 categories below. Notably, further +#' arguments to the `position` argument, or aesthetics that are required +#' can *not* be passed through `...`. Unknown arguments that are not part +#' of the 4 categories below are ignored. +#' * Static aesthetics that are not mapped to a scale, but are at a fixed +#' value and apply to the layer as a whole. For example, `colour = "red"` +#' or `linewidth = 3`. The geom's documentation has an **Aesthetics** +#' section that lists the available options. The 'required' aesthetics +#' cannot be passed on to the `params`. +#' * When constructing a layer using +#' a `stat_*()` function, the `...` argument can be used to pass on +#' parameters to the `geom` part of the layer. An example of this is +#' `stat_density(geom = "area", outline.type = "both")`. The geom's +#' documentation lists which parameters it can accept. +#' * Inversely, when constructing a layer using a +#' `geom_*()` function, the `...` argument can be used to pass on parameters +#' to the `stat` part of the layer. An example of this is +#' `geom_area(stat = "density", adjust = 0.5)`. The stat's documentation +#' lists which parameters it can accept. +#' * The `key_glyph` argument of [`layer()`] may also be passed on through +#' `...`. This can be one of the functions described as +#' [key glyphs][draw_key], to change the display of the layer in the legend. +#' #' @export #' @examples #' p <- ggplot(mtcars, aes(wt, mpg)) diff --git a/R/geom-quantile.R b/R/geom-quantile.R index 303316b50b..bb3ff581ab 100644 --- a/R/geom-quantile.R +++ b/R/geom-quantile.R @@ -11,7 +11,9 @@ #' @param method.args List of additional arguments passed on to the modelling #' function defined by `method`. #' @param geom,stat Use to override the default connection between -#' `geom_quantile()` and `stat_quantile()`. +#' `geom_quantile()` and `stat_quantile()`. For more information about +#' overriding these connections, see how the [stat][layer_stats] and +#' [geom][layer_geoms] arguments work. #' @examples #' m <- #' ggplot(mpg, aes(displ, 1 / hwy)) + diff --git a/R/geom-smooth.R b/R/geom-smooth.R index 0c599fdca9..535b8965a8 100644 --- a/R/geom-smooth.R +++ b/R/geom-smooth.R @@ -18,7 +18,9 @@ #' @inheritParams layer #' @inheritParams geom_bar #' @param geom,stat Use to override the default connection between -#' `geom_smooth()` and `stat_smooth()`. +#' `geom_smooth()` and `stat_smooth()`. For more information about overriding +#' these connections, see how the [stat][layer_stats] and [geom][layer_geoms] +#' arguments work. #' @seealso See individual modelling functions for more details: #' [lm()] for linear smooths, #' [glm()] for generalised linear smooths, and diff --git a/R/geom-text.R b/R/geom-text.R index c9ccb6595b..58c86cf234 100644 --- a/R/geom-text.R +++ b/R/geom-text.R @@ -44,9 +44,16 @@ #' @param nudge_x,nudge_y Horizontal and vertical adjustment to nudge labels by. #' Useful for offsetting text from points, particularly on discrete scales. #' Cannot be jointly specified with `position`. -#' @param position Position adjustment, either as a string, or the result of -#' a call to a position adjustment function. Cannot be jointly specified with -#' `nudge_x` or `nudge_y`. +#' @param position A position adjustment to use on the data for this layer. +#' Cannot be jointy specified with `nudge_x` or `nudge_y`. This +#' can be used in various ways, including to prevent overplotting and +#' improving the display. The `position` argument accepts the following: +#' * The result of calling a position function, such as `position_jitter()`. +#' * A string nameing the position adjustment. To give the position as a +#' string, strip the function name of the `position_` prefix. For example, +#' to use `position_jitter()`, give the position as `"jitter"`. +#' * For more information and other ways to specify the position, see the +#' [layer position][layer_positions] documentation. #' @param check_overlap If `TRUE`, text that overlaps previous text in the #' same layer will not be plotted. `check_overlap` happens at draw time and in #' the order of the data. Therefore data should be arranged by the label diff --git a/R/geom-violin.R b/R/geom-violin.R index 4b73100f5d..1c9d7a5b17 100644 --- a/R/geom-violin.R +++ b/R/geom-violin.R @@ -15,7 +15,9 @@ #' @param trim If `TRUE` (default), trim the tails of the violins #' to the range of the data. If `FALSE`, don't trim the tails. #' @param geom,stat Use to override the default connection between -#' `geom_violin()` and `stat_ydensity()`. +#' `geom_violin()` and `stat_ydensity()`. For more information about +#' overriding these connections, see how the [stat][layer_stats] and +#' [geom][layer_geoms] arguments work. #' @param bounds Known lower and upper bounds for estimated data. Default #' `c(-Inf, Inf)` means that there are no (finite) bounds. If any bound is #' finite, boundary effect of default density estimation will be corrected by diff --git a/R/layer.R b/R/layer.R index 02649348ac..2079b11576 100644 --- a/R/layer.R +++ b/R/layer.R @@ -23,17 +23,37 @@ #' the plot data. The return value must be a `data.frame`, and #' will be used as the layer data. A `function` can be created #' from a `formula` (e.g. `~ head(.x, 10)`). -#' @param geom The geometric object to use to display the data, either as a -#' `ggproto` `Geom` subclass or as a string naming the geom stripped of the -#' `geom_` prefix (e.g. `"point"` rather than `"geom_point"`) -#' @param stat The statistical transformation to use on the data for this -#' layer, either as a `ggproto` `Geom` subclass or as a string naming the -#' stat stripped of the `stat_` prefix (e.g. `"count"` rather than -#' `"stat_count"`) -#' @param position Position adjustment, either as a string naming the adjustment -#' (e.g. `"jitter"` to use `position_jitter`), or the result of a call to a -#' position adjustment function. Use the latter if you need to change the -#' settings of the adjustment. +#' +#' @param geom The geometric object to use to display the data for this layer. +#' When using a `stat_*()` function to construct a layer, the `geom` argument +#' can be used to override the default coupling between stats and geoms. The +#' `geom` argument accepts the following: +#' * A `Geom` ggproto subclass, for example `GeomPoint`. +#' * A string naming the geom. To give the geom as a string, strip the +#' function name of the `geom_` prefix. For example, to use `geom_point()`, +#' give the geom as `"point"`. +#' * For more information and other ways to specify the geom, see the +#' [layer geom][layer_geoms] documentation. +#' @param stat The statistical transformation to use on the data for this layer. +#' When using a `geom_*()` function to construct a layer, the `stat` +#' argument can be used the override the default coupling between geoms and +#' stats. The `stat` argument accepts the following: +#' * A `Stat` ggproto subclass, for example `StatCount`. +#' * A string naming the stat. To give the stat as a string, strip the +#' function name of the `stat_` prefix. For example, to use `stat_count()`, +#' give the stat as `"count"`. +#' * For more information and other ways to specify the stat, see the +#' [layer stat][layer_stats] documentation. +#' @param position A position adjustment to use on the data for this layer. This +#' can be used in various ways, including to prevent overplotting and +#' improving the display. The `position` argument accepts the following: +#' * The result of calling a position function, such as `position_jitter()`. +#' This method allows for passing extra arguments to the position. +#' * A string naming the position adjustment. To give the position as a +#' string, strip the function name of the `position_` prefix. For example, +#' to use `position_jitter()`, give the position as `"jitter"`. +#' * For more information and other ways to specify the position, see the +#' [layer position][layer_positions] documentation. #' @param show.legend logical. Should this layer be included in the legends? #' `NA`, the default, includes if any aesthetics are mapped. #' `FALSE` never includes, and `TRUE` always includes. @@ -52,6 +72,7 @@ #' @param layer_class The type of layer object to be constructed. This is #' intended for ggplot2 internal use only. #' @keywords internal +#' @family layer documentation #' @examples #' # geom calls are just a short cut for layer #' ggplot(mpg, aes(displ, hwy)) + geom_point() diff --git a/_pkgdown.yml b/_pkgdown.yml index 699e2df919..7982ecf2ad 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -50,6 +50,7 @@ reference: you will create layers using a `geom_` function, overriding the default position and stat if needed. contents: + - layer_geoms - starts_with("geom_") - subtitle: Stats @@ -58,6 +59,7 @@ reference: drawing attention to the statistical transformation rather than the visual appearance. The computed variables can be mapped using `after_stat()`. contents: + - layer_stats - stat_ecdf - stat_ellipse - stat_function @@ -74,6 +76,7 @@ reference: Override the default by using the `position` argument to the `geom_` or `stat_` function. contents: + - layer_positions - starts_with("position_") - subtitle: Annotations diff --git a/man/annotate.Rd b/man/annotate.Rd index a282c9eb09..798c2fa2df 100644 --- a/man/annotate.Rd +++ b/man/annotate.Rd @@ -24,10 +24,31 @@ annotate( \item{x, y, xmin, ymin, xmax, ymax, xend, yend}{positioning aesthetics - you must specify at least one of these.} -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} diff --git a/man/borders.Rd b/man/borders.Rd index a603a62633..1fcb3f2630 100644 --- a/man/borders.Rd +++ b/man/borders.Rd @@ -51,14 +51,30 @@ A \code{function} will be called with a single argument, the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} - \item{\code{stat}}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - \item{\code{position}}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} + \item{\code{stat}}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} + \item{\code{position}}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} \item{\code{show.legend}}{logical. Should this layer be included in the legends? \code{NA}, the default, includes if any aesthetics are mapped. \code{FALSE} never includes, and \code{TRUE} always includes. diff --git a/man/geom_abline.Rd b/man/geom_abline.Rd index 389685b8dc..987908022d 100644 --- a/man/geom_abline.Rd +++ b/man/geom_abline.Rd @@ -52,10 +52,31 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} diff --git a/man/geom_bar.Rd b/man/geom_bar.Rd index 123da5b98a..70c4b42437 100644 --- a/man/geom_bar.Rd +++ b/man/geom_bar.Rd @@ -66,15 +66,44 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{just}{Adjustment for column placement. Set to \code{0.5} by default, meaning that columns will be centered about axis breaks. Set to \code{0} or \code{1} to place @@ -105,7 +134,8 @@ that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[=borders]{borders()}}.} \item{geom, stat}{Override the default connection between \code{geom_bar()} and -\code{stat_count()}.} +\code{stat_count()}. For more information about overriding these connections, +see how the \link[=layer_stats]{stat} and \link[=layer_geoms]{geom} arguments work.} } \description{ There are two types of bar charts: \code{geom_bar()} and \code{geom_col()}. diff --git a/man/geom_bin_2d.Rd b/man/geom_bin_2d.Rd index ff6f279a69..5d8c0cc5b0 100644 --- a/man/geom_bin_2d.Rd +++ b/man/geom_bin_2d.Rd @@ -53,15 +53,44 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} @@ -78,7 +107,9 @@ that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[=borders]{borders()}}.} \item{geom, stat}{Use to override the default connection between -\code{geom_bin_2d()} and \code{stat_bin_2d()}.} +\code{geom_bin_2d()} and \code{stat_bin_2d()}. For more information about overriding +these connections, see how the \link[=layer_stats]{stat} and \link[=layer_geoms]{geom} +arguments work.} \item{bins}{numeric vector giving number of bins in both vertical and horizontal directions. Set to 30 by default.} diff --git a/man/geom_blank.Rd b/man/geom_blank.Rd index e9af7b0345..52f22374f6 100644 --- a/man/geom_blank.Rd +++ b/man/geom_blank.Rd @@ -35,20 +35,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{show.legend}{logical. Should this layer be included in the legends? \code{NA}, the default, includes if any aesthetics are mapped. diff --git a/man/geom_boxplot.Rd b/man/geom_boxplot.Rd index 4b88223a1c..31bc5fd1c2 100644 --- a/man/geom_boxplot.Rd +++ b/man/geom_boxplot.Rd @@ -63,15 +63,44 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{outliers}{Whether to display (\code{TRUE}) or discard (\code{FALSE}) outliers from the plot. Hiding or discarding outliers can be useful when, for @@ -122,7 +151,9 @@ that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[=borders]{borders()}}.} \item{geom, stat}{Use to override the default connection between -\code{geom_boxplot()} and \code{stat_boxplot()}.} +\code{geom_boxplot()} and \code{stat_boxplot()}. For more information about +overriding these connections, see how the \link[=layer_stats]{stat} and +\link[=layer_geoms]{geom} arguments work.} \item{coef}{Length of the whiskers as multiple of IQR. Defaults to 1.5.} } diff --git a/man/geom_contour.Rd b/man/geom_contour.Rd index 696f51f19a..2225885518 100644 --- a/man/geom_contour.Rd +++ b/man/geom_contour.Rd @@ -87,20 +87,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{bins}{Number of contour bins. Overridden by \code{breaks}.} @@ -137,9 +174,18 @@ rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[=borders]{borders()}}.} -\item{geom}{The geometric object to use to display the data, either as a -\code{ggproto} \code{Geom} subclass or as a string naming the geom stripped of the -\code{geom_} prefix (e.g. \code{"point"} rather than \code{"geom_point"})} +\item{geom}{The geometric object to use to display the data for this layer. +When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument +can be used to override the default coupling between stats and geoms. The +\code{geom} argument accepts the following: +\itemize{ +\item A \code{Geom} ggproto subclass, for example \code{GeomPoint}. +\item A string naming the geom. To give the geom as a string, strip the +function name of the \code{geom_} prefix. For example, to use \code{geom_point()}, +give the geom as \code{"point"}. +\item For more information and other ways to specify the geom, see the +\link[=layer_geoms]{layer geom} documentation. +}} } \description{ ggplot2 can not draw true 3D surfaces, but you can use \code{geom_contour()}, diff --git a/man/geom_count.Rd b/man/geom_count.Rd index 6be60a682d..038194b1b0 100644 --- a/man/geom_count.Rd +++ b/man/geom_count.Rd @@ -48,15 +48,44 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} @@ -73,7 +102,9 @@ that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[=borders]{borders()}}.} \item{geom, stat}{Use to override the default connection between -\code{geom_count()} and \code{stat_sum()}.} +\code{geom_count()} and \code{stat_sum()}. For more information about overriding +these connections, see how the \link[=layer_stats]{stat} and \link[=layer_geoms]{geom} +arguments work.} } \description{ This is a variant \code{\link[=geom_point]{geom_point()}} that counts the number of diff --git a/man/geom_density.Rd b/man/geom_density.Rd index d3ca242786..6523261553 100644 --- a/man/geom_density.Rd +++ b/man/geom_density.Rd @@ -57,15 +57,44 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} @@ -91,7 +120,9 @@ upper and lower lines, \code{"upper"}/\code{"lower"} draws the respective lines \code{"full"} draws a closed polygon around the area.} \item{geom, stat}{Use to override the default connection between -\code{geom_density()} and \code{stat_density()}.} +\code{geom_density()} and \code{stat_density()}. For more information about +overriding these connections, see how the \link[=layer_stats]{stat} and +\link[=layer_geoms]{geom} arguments work.} \item{bw}{The smoothing bandwidth to be used. If numeric, the standard deviation of the smoothing kernel. diff --git a/man/geom_density_2d.Rd b/man/geom_density_2d.Rd index be0fd547aa..68f1353262 100644 --- a/man/geom_density_2d.Rd +++ b/man/geom_density_2d.Rd @@ -91,10 +91,18 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} \item{...}{ Arguments passed on to \code{\link[=geom_contour]{geom_contour}} @@ -138,7 +146,9 @@ that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[=borders]{borders()}}.} \item{geom, stat}{Use to override the default connection between -\code{geom_density_2d()} and \code{stat_density_2d()}.} +\code{geom_density_2d()} and \code{stat_density_2d()}. For more information at +overriding these connections, see how the \link[=layer_stats]{stat} and +\link[=layer_geoms]{geom} arguments work.} \item{contour}{If \code{TRUE}, contour the results of the 2d density estimation.} diff --git a/man/geom_dotplot.Rd b/man/geom_dotplot.Rd index 3a3481006a..5b7c675b7c 100644 --- a/man/geom_dotplot.Rd +++ b/man/geom_dotplot.Rd @@ -47,15 +47,44 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{binwidth}{When \code{method} is "dotdensity", this specifies maximum bin width. When \code{method} is "histodot", this specifies bin width. diff --git a/man/geom_errorbarh.Rd b/man/geom_errorbarh.Rd index 7ad30aa6b7..81144c089a 100644 --- a/man/geom_errorbarh.Rd +++ b/man/geom_errorbarh.Rd @@ -36,20 +36,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} diff --git a/man/geom_function.Rd b/man/geom_function.Rd index be07031218..7525592dbd 100644 --- a/man/geom_function.Rd +++ b/man/geom_function.Rd @@ -39,20 +39,57 @@ mapping.} \item{data}{Ignored by \code{stat_function()}, do not use.} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} @@ -68,9 +105,18 @@ rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[=borders]{borders()}}.} -\item{geom}{The geometric object to use to display the data, either as a -\code{ggproto} \code{Geom} subclass or as a string naming the geom stripped of the -\code{geom_} prefix (e.g. \code{"point"} rather than \code{"geom_point"})} +\item{geom}{The geometric object to use to display the data for this layer. +When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument +can be used to override the default coupling between stats and geoms. The +\code{geom} argument accepts the following: +\itemize{ +\item A \code{Geom} ggproto subclass, for example \code{GeomPoint}. +\item A string naming the geom. To give the geom as a string, strip the +function name of the \code{geom_} prefix. For example, to use \code{geom_point()}, +give the geom as \code{"point"}. +\item For more information and other ways to specify the geom, see the +\link[=layer_geoms]{layer geom} documentation. +}} \item{fun}{Function to use. Either 1) an anonymous function in the base or rlang formula syntax (see \code{\link[rlang:as_function]{rlang::as_function()}}) diff --git a/man/geom_hex.Rd b/man/geom_hex.Rd index 9ea02ab6e8..580f2b5901 100644 --- a/man/geom_hex.Rd +++ b/man/geom_hex.Rd @@ -51,15 +51,44 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} @@ -76,7 +105,8 @@ that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[=borders]{borders()}}.} \item{geom, stat}{Override the default connection between \code{geom_hex()} and -\code{stat_bin_hex()}.} +\code{stat_bin_hex()}. For more information about overriding these connections, +see how the \link[=layer_stats]{stat} and \link[=layer_geoms]{geom} arguments work.} \item{bins}{numeric vector giving number of bins in both vertical and horizontal directions. Set to 30 by default.} diff --git a/man/geom_histogram.Rd b/man/geom_histogram.Rd index f1619d5213..63e8b1517b 100644 --- a/man/geom_histogram.Rd +++ b/man/geom_histogram.Rd @@ -72,15 +72,44 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} @@ -117,7 +146,9 @@ rare event that this fails it can be given explicitly by setting \code{orientati to either \code{"x"} or \code{"y"}. See the \emph{Orientation} section for more detail.} \item{geom, stat}{Use to override the default connection between -\code{geom_histogram()}/\code{geom_freqpoly()} and \code{stat_bin()}.} +\code{geom_histogram()}/\code{geom_freqpoly()} and \code{stat_bin()}. For more information +at overriding these connections, see how the \link[=layer_stats]{stat} and +\link[=layer_geoms]{geom} arguments work.} \item{center, boundary}{bin position specifiers. Only one, \code{center} or \code{boundary}, may be specified for a single plot. \code{center} specifies the diff --git a/man/geom_jitter.Rd b/man/geom_jitter.Rd index b90546891d..1eb8ed9a22 100644 --- a/man/geom_jitter.Rd +++ b/man/geom_jitter.Rd @@ -38,20 +38,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{width, height}{Amount of vertical and horizontal jitter. The jitter is added in both positive and negative directions, so the total spread diff --git a/man/geom_linerange.Rd b/man/geom_linerange.Rd index 499b43a9d7..d4baeca5e3 100644 --- a/man/geom_linerange.Rd +++ b/man/geom_linerange.Rd @@ -79,20 +79,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{fatten}{A multiplicative factor used to increase the size of the middle bar in \code{geom_crossbar()} and the middle point in diff --git a/man/geom_map.Rd b/man/geom_map.Rd index 63923151b7..19d45af22b 100644 --- a/man/geom_map.Rd +++ b/man/geom_map.Rd @@ -36,15 +36,44 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{map}{Data frame that contains the map coordinates. This will typically be created using \code{\link[=fortify]{fortify()}} on a spatial object. diff --git a/man/geom_path.Rd b/man/geom_path.Rd index bf1277fcf3..bb1b49aece 100644 --- a/man/geom_path.Rd +++ b/man/geom_path.Rd @@ -66,20 +66,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{lineend}{Line end style (round, butt, square).} diff --git a/man/geom_point.Rd b/man/geom_point.Rd index 6ce1d98b06..3640142069 100644 --- a/man/geom_point.Rd +++ b/man/geom_point.Rd @@ -36,20 +36,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} diff --git a/man/geom_polygon.Rd b/man/geom_polygon.Rd index 7d86e52d3d..36ebc4087d 100644 --- a/man/geom_polygon.Rd +++ b/man/geom_polygon.Rd @@ -37,25 +37,62 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} \item{rule}{Either \code{"evenodd"} or \code{"winding"}. If polygons with holes are being drawn (using the \code{subgroup} aesthetic) this argument defines how the hole coordinates are interpreted. See the examples in \code{\link[grid:grid.path]{grid::pathGrob()}} for an explanation.} -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} diff --git a/man/geom_qq.Rd b/man/geom_qq.Rd index 63c171e312..a4a58d4883 100644 --- a/man/geom_qq.Rd +++ b/man/geom_qq.Rd @@ -84,19 +84,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{geom}{The geometric object to use to display the data, either as a -\code{ggproto} \code{Geom} subclass or as a string naming the geom stripped of the -\code{geom_} prefix (e.g. \code{"point"} rather than \code{"geom_point"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{geom}{The geometric object to use to display the data for this layer. +When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument +can be used to override the default coupling between stats and geoms. The +\code{geom} argument accepts the following: +\itemize{ +\item A \code{Geom} ggproto subclass, for example \code{GeomPoint}. +\item A string naming the geom. To give the geom as a string, strip the +function name of the \code{geom_} prefix. For example, to use \code{geom_point()}, +give the geom as \code{"point"}. +\item For more information and other ways to specify the geom, see the +\link[=layer_geoms]{layer geom} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{distribution}{Distribution function to use, if x not specified} diff --git a/man/geom_quantile.Rd b/man/geom_quantile.Rd index 932cf0612a..b9d95b8942 100644 --- a/man/geom_quantile.Rd +++ b/man/geom_quantile.Rd @@ -55,15 +55,44 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{lineend}{Line end style (round, butt, square).} @@ -86,7 +115,9 @@ that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[=borders]{borders()}}.} \item{geom, stat}{Use to override the default connection between -\code{geom_quantile()} and \code{stat_quantile()}.} +\code{geom_quantile()} and \code{stat_quantile()}. For more information about +overriding these connections, see how the \link[=layer_stats]{stat} and +\link[=layer_geoms]{geom} arguments work.} \item{quantiles}{conditional quantiles of y to calculate and display} diff --git a/man/geom_ribbon.Rd b/man/geom_ribbon.Rd index 1dccb490ca..723485ee75 100644 --- a/man/geom_ribbon.Rd +++ b/man/geom_ribbon.Rd @@ -64,20 +64,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} @@ -102,9 +139,18 @@ the default plot specification, e.g. \code{\link[=borders]{borders()}}.} upper and lower lines, \code{"upper"}/\code{"lower"} draws the respective lines only. \code{"full"} draws a closed polygon around the area.} -\item{geom}{The geometric object to use to display the data, either as a -\code{ggproto} \code{Geom} subclass or as a string naming the geom stripped of the -\code{geom_} prefix (e.g. \code{"point"} rather than \code{"geom_point"})} +\item{geom}{The geometric object to use to display the data for this layer. +When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument +can be used to override the default coupling between stats and geoms. The +\code{geom} argument accepts the following: +\itemize{ +\item A \code{Geom} ggproto subclass, for example \code{GeomPoint}. +\item A string naming the geom. To give the geom as a string, strip the +function name of the \code{geom_} prefix. For example, to use \code{geom_point()}, +give the geom as \code{"point"}. +\item For more information and other ways to specify the geom, see the +\link[=layer_geoms]{layer geom} documentation. +}} } \description{ For each x value, \code{geom_ribbon()} displays a y interval defined diff --git a/man/geom_rug.Rd b/man/geom_rug.Rd index 1d0359b711..7f77b8751a 100644 --- a/man/geom_rug.Rd +++ b/man/geom_rug.Rd @@ -39,20 +39,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{outside}{logical that controls whether to move the rug tassels outside of the plot area. Default is off (FALSE). You will also need to use \code{coord_cartesian(clip = "off")}. When set to TRUE, also consider changing the sides argument to "tr". See examples.} diff --git a/man/geom_segment.Rd b/man/geom_segment.Rd index eb3892920b..7647d512a8 100644 --- a/man/geom_segment.Rd +++ b/man/geom_segment.Rd @@ -58,20 +58,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{arrow}{specification for arrow heads, as created by \code{\link[grid:arrow]{grid::arrow()}}.} diff --git a/man/geom_smooth.Rd b/man/geom_smooth.Rd index 93e08327f2..5546327c21 100644 --- a/man/geom_smooth.Rd +++ b/man/geom_smooth.Rd @@ -61,15 +61,44 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{method}{Smoothing method (function) to use, accepts either \code{NULL} or a character vector, e.g. \code{"lm"}, \code{"glm"}, \code{"gam"}, \code{"loess"} @@ -116,7 +145,9 @@ that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[=borders]{borders()}}.} \item{geom, stat}{Use to override the default connection between -\code{geom_smooth()} and \code{stat_smooth()}.} +\code{geom_smooth()} and \code{stat_smooth()}. For more information about overriding +these connections, see how the \link[=layer_stats]{stat} and \link[=layer_geoms]{geom} +arguments work.} \item{n}{Number of points at which to evaluate smoother.} diff --git a/man/geom_spoke.Rd b/man/geom_spoke.Rd index ea942a3d78..69d52e73b9 100644 --- a/man/geom_spoke.Rd +++ b/man/geom_spoke.Rd @@ -37,20 +37,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} diff --git a/man/geom_text.Rd b/man/geom_text.Rd index f9dfe385a6..e0fa69d0ee 100644 --- a/man/geom_text.Rd +++ b/man/geom_text.Rd @@ -60,19 +60,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string, or the result of -a call to a position adjustment function. Cannot be jointly specified with -\code{nudge_x} or \code{nudge_y}.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. +Cannot be jointy specified with \code{nudge_x} or \code{nudge_y}. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +\item A string nameing the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{parse}{If \code{TRUE}, the labels will be parsed into expressions and displayed as described in \code{?plotmath}.} diff --git a/man/geom_tile.Rd b/man/geom_tile.Rd index 00903da7f6..c8ff067065 100644 --- a/man/geom_tile.Rd +++ b/man/geom_tile.Rd @@ -65,20 +65,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{hjust, vjust}{horizontal and vertical justification of the grob. Each justification value should be a number between 0 and 1. Defaults to 0.5 diff --git a/man/geom_violin.Rd b/man/geom_violin.Rd index 45adedc4f3..9ed6d29557 100644 --- a/man/geom_violin.Rd +++ b/man/geom_violin.Rd @@ -61,15 +61,44 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{draw_quantiles}{If \code{not(NULL)} (default), draw horizontal lines at the given quantiles of the density estimate.} @@ -107,7 +136,9 @@ that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[=borders]{borders()}}.} \item{geom, stat}{Use to override the default connection between -\code{geom_violin()} and \code{stat_ydensity()}.} +\code{geom_violin()} and \code{stat_ydensity()}. For more information about +overriding these connections, see how the \link[=layer_stats]{stat} and +\link[=layer_geoms]{geom} arguments work.} \item{bw}{The smoothing bandwidth to be used. If numeric, the standard deviation of the smoothing kernel. diff --git a/man/ggsf.Rd b/man/ggsf.Rd index fca4f896d3..a26bb278f6 100644 --- a/man/ggsf.Rd +++ b/man/ggsf.Rd @@ -195,15 +195,31 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} @@ -220,10 +236,31 @@ rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[=borders]{borders()}}.} -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{parse}{If \code{TRUE}, the labels will be parsed into expressions and displayed as described in \code{?plotmath}.} @@ -250,9 +287,18 @@ the order of the data. Therefore data should be arranged by the label column before calling \code{geom_text()}. Note that this argument is not supported by \code{geom_label()}.} -\item{geom}{The geometric object to use to display the data, either as a -\code{ggproto} \code{Geom} subclass or as a string naming the geom stripped of the -\code{geom_} prefix (e.g. \code{"point"} rather than \code{"geom_point"})} +\item{geom}{The geometric object to use to display the data for this layer. +When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument +can be used to override the default coupling between stats and geoms. The +\code{geom} argument accepts the following: +\itemize{ +\item A \code{Geom} ggproto subclass, for example \code{GeomPoint}. +\item A string naming the geom. To give the geom as a string, strip the +function name of the \code{geom_} prefix. For example, to use \code{geom_point()}, +give the geom as \code{"point"}. +\item For more information and other ways to specify the geom, see the +\link[=layer_geoms]{layer geom} documentation. +}} } \description{ This set of geom, stat, and coord are used to visualise simple feature (sf) diff --git a/man/layer.Rd b/man/layer.Rd index f7dd21b542..f9b5022d77 100644 --- a/man/layer.Rd +++ b/man/layer.Rd @@ -20,14 +20,31 @@ layer( ) } \arguments{ -\item{geom}{The geometric object to use to display the data, either as a -\code{ggproto} \code{Geom} subclass or as a string naming the geom stripped of the -\code{geom_} prefix (e.g. \code{"point"} rather than \code{"geom_point"})} +\item{geom}{The geometric object to use to display the data for this layer. +When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument +can be used to override the default coupling between stats and geoms. The +\code{geom} argument accepts the following: +\itemize{ +\item A \code{Geom} ggproto subclass, for example \code{GeomPoint}. +\item A string naming the geom. To give the geom as a string, strip the +function name of the \code{geom_} prefix. For example, to use \code{geom_point()}, +give the geom as \code{"point"}. +\item For more information and other ways to specify the geom, see the +\link[=layer_geoms]{layer geom} documentation. +}} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} \item{data}{The data to be displayed in this layer. There are three options: @@ -49,10 +66,18 @@ from a \code{formula} (e.g. \code{~ head(.x, 10)}).} at the top level of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} \item{params}{Additional parameters to the \code{geom} and \code{stat}.} @@ -100,4 +125,11 @@ ggplot(mpg, aes(displ, hwy)) + ) } +\seealso{ +Other layer documentation: +\code{\link{layer_geoms}}, +\code{\link{layer_positions}}, +\code{\link{layer_stats}} +} +\concept{layer documentation} \keyword{internal} diff --git a/man/layer_geoms.Rd b/man/layer_geoms.Rd new file mode 100644 index 0000000000..26b75b2d9d --- /dev/null +++ b/man/layer_geoms.Rd @@ -0,0 +1,144 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/docs_layer.R +\name{layer_geoms} +\alias{layer_geoms} +\title{Layer geometry display} +\description{ +In ggplot2, a plot in constructed by adding layers to it. A layer consists +of two important parts: the geometry (geoms), and statistical transformations +(stats). The 'geom' part of a layer is important because it determines the +looks of the data. Geoms determine \emph{how} something is displayed, not \emph{what} +is displayed. +} +\section{Specifying geoms}{ +There are five ways in which the 'geom' part of a layer can be specified. + +\if{html}{\out{
}}\preformatted{# 1. The geom can have a layer constructor +geom_area() + +# 2. A stat can default to a particular geom +stat_density() # has `geom = "area"` as default + +# 3. It can be given to a stat as a string +stat_function(geom = "area") + +# 4. The ggproto object of a geom can be given +stat_bin(geom = GeomArea) + +# 5. It can be given to `layer()` directly +layer( + geom = "area", + stat = "smooth", + position = "identity" +) +}\if{html}{\out{
}} + +Many of these ways are absolutely equivalent. Using +\code{stat_density(geom = "line")} is identical to using +\code{geom_line(stat = "density")}. Note that for \code{\link[=layer]{layer()}}, you need to +provide the \code{"position"} argument as well. To give geoms as a string, take +the function name, and remove the \code{geom_} prefix, such that \code{geom_point} +becomes \code{"point"}. + +Some of the more well known geoms that can be used for the \code{geom} argument +are: \code{\link[=geom_point]{"point"}}, \code{\link[=geom_line]{"line"}}, +\code{\link[=geom_area]{"area"}}, \code{\link[=geom_bar]{"bar"}} and +\code{\link[=geom_polygon]{"polygon"}}. +} + +\section{Graphical display}{ +A ggplot is build on top of the \link[=grid-package]{grid} package. This package +understands various graphical primitives, such as points, lines, rectangles +and polygons and their \link[=aes_position]{positions}, as well as graphical +attributes, also termed aesthetics, such as +\link[=aes_colour_fill_alpha]{colours, fills}, +\link[=aes_linetype_size_shape]{linewidths and linetypes}. The job of the geom part +of a layer, is to translate data to grid graphics that can be plotted. + +To see how aesthetics are specified, run \code{vignette("ggplot2-specs")}. To see +what geom uses what aesthetics, you can find the \strong{Aesthetics} section in +their documentation, for example in \code{\link[=geom_line]{?geom_line}}. + +While almost anything can be represented by polygons if you try hard enough, +it is not always convenient to do so manually. For this reason, the geoms +provide abstractions that take most of this hassle away. \code{\link[=geom_ribbon]{geom_ribbon()}} +for example is a special case of \code{\link[=geom_polygon]{geom_polygon()}}, where two sets of +y-positions have a shared x-position. In turn, \code{\link[=geom_area]{geom_area()}} is a special +case of a ribbon, where one of the two sets of y-positions is set at 0. + +\if{html}{\out{
}}\preformatted{# A hassle to build a polygon +my_polygon <- data.frame( + x = c(economics$date, rev(economics$date)), + y = c(economics$uempmed, rev(economics$psavert)) +) +ggplot(my_polygon, aes(x, y)) + + geom_polygon() + +# More succinctly +ggplot(economics, aes(date)) + + geom_ribbon(aes(ymin = uempmed, ymax = psavert)) +}\if{html}{\out{
}} + +In addition to abstraction, geoms sometimes also perform composition. +A boxplot is a particular arrangement of lines, rectangles and points that +people have agreed upon is a summary of some data, which is performed by +\code{\link[=geom_boxplot]{geom_boxplot()}}. + +\if{html}{\out{
}}\preformatted{Boxplot data +value <- fivenum(rnorm(100)) +df <- data.frame( + min = value[1], lower = value[2], middle = value[3], + upper = value[4], max = value[5] +) + +# Drawing a boxplot manually +ggplot(df, aes(x = 1, xend = 1)) + + geom_rect( + aes( + xmin = 0.55, xmax = 1.45, + ymin = lower, ymax = upper + ), + colour = "black", fill = "white" + ) + + geom_segment( + aes( + x = 0.55, xend = 1.45, + y = middle, yend = middle + ), + size = 1 + ) + + geom_segment(aes(y = lower, yend = min)) + + geom_segment(aes(y = upper, yend = max)) + +# More succinctly +ggplot(df, aes(x = 1)) + + geom_boxplot( + aes(ymin = min, ymax = max, + lower = lower, upper = upper, + middle = middle), + stat = "identity" + ) +}\if{html}{\out{
}} +} + +\section{Under the hood}{ +Internally, geoms are represented as \code{\link[=ggproto]{ggproto}} classes that +occupy a slot in a layer. All these classes inherit from the parental +\code{\link{Geom}} ggproto object that orchestrates how geoms work. Briefly, geoms +are given the opportunity to draw the data of the layer as a whole, +a facet panel, or of individual groups. For more information on extending +geoms, see the \strong{Creating a new geom} section after running +\code{vignette("extending-ggplot2")}. Additionally, see the \strong{New geoms} section +of the \href{https://ggplot2-book.org/extensions.html#new-geoms}{online book}. +} + +\seealso{ +For an overview of all geom layers, see the +\href{https://ggplot2.tidyverse.org/reference/index.html#geoms}{online reference}. + +Other layer documentation: +\code{\link{layer}()}, +\code{\link{layer_positions}}, +\code{\link{layer_stats}} +} +\concept{layer documentation} diff --git a/man/layer_positions.Rd b/man/layer_positions.Rd new file mode 100644 index 0000000000..bc04bd8cab --- /dev/null +++ b/man/layer_positions.Rd @@ -0,0 +1,117 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/docs_layer.R +\name{layer_positions} +\alias{layer_positions} +\title{Layer position adjustments} +\description{ +In ggplot2, a plot is constructed by adding layers to it. In addition to +\link[=layer_geoms]{geoms} and \link[=layer_stats]{stats}, position adjustments are the +third required part of a layer. The 'position' part of a layer is responsible +for dodging, jittering and nudging groups of data to minimise their overlap, +or otherwise tweaking their positions. + +For example if you add \code{position = position_nudge(x = 1)} to a layer, you +can offset every x-position by 1. For many layers, the default position +adjustment is \code{\link[=position_identity]{position_identity()}}, which performs no adjustment. +} +\section{Specifying positions}{ +There are 4 ways in which the 'position' part of a layer can be specified. + +\if{html}{\out{
}}\preformatted{1. A layer can have default position adjustments +geom_jitter() # has `position = "jitter"` + +2. It can be given to a layer as a string +geom_point(position = "jitter") + +3. The position function can be used to pass extra arguments +geom_point(position = position_jitter(width = 1)) + +4. It can be given to `layer()` directly +layer( + geom = "point", + stat = "identity", + position = "jitter" +) +}\if{html}{\out{
}} + +These ways are not always equivalent. Some layers may not understand what +to do with a position adjustment, and require additional parameters passed +through the \verb{position_*()} function, or may not work correctly. For +example \code{\link[=position_dodge]{position_dodge()}} requires non-overlapping x intervals, whereas +\code{\link[=geom_point]{geom_point()}} doesn't have dimensions to calculate intervals for. To give +positions as a string, take the function name, and remove the \code{position_} +prefix, such that \code{position_fill} becomes \code{"fill"}. +} + +\section{Pairing geoms with positions}{ +Some geoms work better with some positions than others. Below follows a brief +overview of geoms and position adjustments that work well together. +\subsection{Identity}{ + +\code{\link[=position_identity]{position_identity()}} can work with virtually any geom. +} + +\subsection{Dodging}{ + +\code{\link[=position_dodge]{position_dodge()}} pushes overlapping objects away from one another and +requires a \code{group} variable. \code{\link[=position_dodge2]{position_dodge2()}} can work without group +variables and can handle variable widths. As a rule of thumb, layers where +groups occupy a range on the x-axis pair well with dodging. If layers have +no width, you may be required to specify it manually with +\code{position_dodge(width = ...)}. Some geoms that pair well with dodging are +\code{\link[=geom_bar]{geom_bar()}}, \code{\link[=geom_boxplot]{geom_boxplot()}}, \code{\link[=geom_linerange]{geom_linerange()}}, +\code{\link[=geom_errorbar]{geom_errorbar()}} and \code{\link[=geom_text]{geom_text()}}. +} + +\subsection{Jittering}{ + +\code{\link[=position_jitter]{position_jitter()}} adds a some random noise to every point, +which can help with overplotting. \code{\link[=position_jitterdodge]{position_jitterdodge()}} does the same, +but also dodges the points. As a rule of thumb, jittering works best +when points have discrete x-positions. Jittering is most useful for +\code{\link[=geom_point]{geom_point()}}, but can also be used in \code{\link[=geom_path]{geom_path()}} for example. +} + +\subsection{Nudging}{ + +\code{\link[=position_nudge]{position_nudge()}} can add offsets to x- and y-positions. This can be +useful for discrete positions where you don't want to put an object +exactly in the middle. While most useful for \code{\link[=geom_text]{geom_text()}}, it can be +used with virtually all geoms. +} + +\subsection{Stacking}{ + +\code{\link[=position_stack]{position_stack()}} is useful for displaying data on top of one another. It +can be used for geoms that are usually anchored to the x-axis, for example +\code{\link[=geom_bar]{geom_bar()}}, \code{\link[=geom_area]{geom_area()}} or \code{\link[=geom_histogram]{geom_histogram()}}. +} + +\subsection{Filling}{ + +\code{\link[=position_fill]{position_fill()}} can be used to give proportions at every x-position. Like +stacking, filling is most useful for geoms that are anchored to the x-axis, +like \code{\link[=geom_bar]{geom_bar()}}, \code{\link[=geom_area]{geom_area()}} or \code{\link[=geom_histogram]{geom_histogram()}}. +} +} + +\section{Under the hood}{ +Internally, positions are represented as \code{\link[=ggproto]{ggproto}} classes that +occupy a slot in a layer. All these classes inherit from the parental +\code{\link{Position}} ggproto object that orchestrates how positions work. Briefly, +positions are given the opportunity to adjust the data of each facet panel. +For more information about extending positions, see the \strong{New positions} +section of the +\href{https://ggplot2-book.org/extensions.html#new-positions}{online book}. +} + +\seealso{ +For an overview of all position adjustments, see the +\href{https://ggplot2.tidyverse.org/reference/index.html#position-adjustment}{online reference}. + +Other layer documentation: +\code{\link{layer}()}, +\code{\link{layer_geoms}}, +\code{\link{layer_stats}} +} +\concept{layer documentation} diff --git a/man/layer_sf.Rd b/man/layer_sf.Rd index b32d7ccc41..8da9547aed 100644 --- a/man/layer_sf.Rd +++ b/man/layer_sf.Rd @@ -18,14 +18,31 @@ layer_sf( ) } \arguments{ -\item{geom}{The geometric object to use to display the data, either as a -\code{ggproto} \code{Geom} subclass or as a string naming the geom stripped of the -\code{geom_} prefix (e.g. \code{"point"} rather than \code{"geom_point"})} +\item{geom}{The geometric object to use to display the data for this layer. +When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument +can be used to override the default coupling between stats and geoms. The +\code{geom} argument accepts the following: +\itemize{ +\item A \code{Geom} ggproto subclass, for example \code{GeomPoint}. +\item A string naming the geom. To give the geom as a string, strip the +function name of the \code{geom_} prefix. For example, to use \code{geom_point()}, +give the geom as \code{"point"}. +\item For more information and other ways to specify the geom, see the +\link[=layer_geoms]{layer geom} documentation. +}} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[=layer_stats]{layer stat} documentation. +}} \item{data}{The data to be displayed in this layer. There are three options: @@ -47,10 +64,18 @@ from a \code{formula} (e.g. \code{~ head(.x, 10)}).} at the top level of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} \item{params}{Additional parameters to the \code{geom} and \code{stat}.} diff --git a/man/layer_stats.Rd b/man/layer_stats.Rd new file mode 100644 index 0000000000..2115a0537e --- /dev/null +++ b/man/layer_stats.Rd @@ -0,0 +1,141 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/docs_layer.R +\name{layer_stats} +\alias{layer_stats} +\title{Layer statistical transformations} +\description{ +In ggplot2, a plot is constructed by adding layers to it. A layer consists +of two important parts: the geometry (geoms), and statistical transformations +(stats). The 'stat' part of a layer is important because it performs a +computation on the data before it is displayed. Stats determine \emph{what} is +displayed, not \emph{how} it is displayed. + +For example, if you add \code{\link[=stat_density]{stat_density()}} to a plot, a kernel density +estimation is performed, which can be displayed with the 'geom' part of a +layer. For many \verb{geom_*()} functions, \code{\link[=stat_identity]{stat_identity()}} is used, +which performs no extra computation on the data. +} +\section{Specifying stats}{ +There are five ways in which the 'stat' part of a layer can be specified. + +\if{html}{\out{
}}\preformatted{# 1. The stat can have a layer constructor +stat_density() + +# 2. A geom can default to a particular stat +geom_density() # has `stat = "density"` as default + +# 3. It can be given to a geom as a string +geom_line(stat = "density") + +# 4. The ggproto object of a stat can be given +geom_area(stat = StatDensity) + +# 5. It can be given to `layer()` directly: +layer( + geom = "line", + stat = "density", + position = "identity" +) +}\if{html}{\out{
}} + +Many of these ways are absolutely equivalent. Using +\code{stat_density(geom = "line")} is identical to using +\code{geom_line(stat = "density")}. Note that for \code{\link[=layer]{layer()}}, you need to +provide the \code{"position"} argument as well. To give stats as a string, take +the function name, and remove the \code{stat_} prefix, such that \code{stat_bin} +becomes \code{"bin"}. + +Some of the more well known stats that can be used for the \code{stat} argument +are: \code{\link[=stat_density]{"density"}}, \code{\link[=stat_bin]{"bin"}}, +\code{\link[=stat_count]{"count"}}, \code{\link[=stat_function]{"function"}} and +\code{\link[=stat_smooth]{"smooth"}}. +} + +\section{Paired geoms and stats}{ +Some geoms have paired stats. In some cases, like \code{\link[=geom_density]{geom_density()}}, it is +just a variant of another geom, \code{\link[=geom_area]{geom_area()}}, with slightly different +defaults. + +In other cases, the relationship is more complex. In the case of boxplots for +example, the stat and the geom have distinct roles. The role of the stat is +to compute the five-number summary of the data. In addition to just +displaying the box of the five-number summary, the geom also provides display +options for the outliers and widths of boxplots. In such cases, you cannot +freely exchange geoms and stats: using \code{stat_boxplot(geom = "line")} or +\code{geom_area(stat = "boxplot")} give errors. + +Some stats and geoms that are paired are: +\itemize{ +\item \code{\link[=geom_violin]{geom_violin()}} and \code{\link[=stat_ydensity]{stat_ydensity()}} +\item \code{\link[=geom_histogram]{geom_histogram()}} and \code{\link[=stat_bin]{stat_bin()}} +\item \code{\link[=geom_contour]{geom_contour()}} and \code{\link[=stat_contour]{stat_contour()}} +\item \code{\link[=geom_function]{geom_function()}} and \code{\link[=stat_function]{stat_function()}} +\item \code{\link[=geom_bin_2d]{geom_bin_2d()}} and \code{\link[=stat_bin_2d]{stat_bin_2d()}} +\item \code{\link[=geom_boxplot]{geom_boxplot()}} and \code{\link[=stat_boxplot]{stat_boxplot()}} +\item \code{\link[=geom_count]{geom_count()}} and \code{\link[=stat_sum]{stat_sum()}} +\item \code{\link[=geom_density]{geom_density()}} and \code{\link[=stat_density]{stat_density()}} +\item \code{\link[=geom_density_2d]{geom_density_2d()}} and \code{\link[=stat_density_2d]{stat_density_2d()}} +\item \code{\link[=geom_hex]{geom_hex()}} and \code{\link[=stat_binhex]{stat_binhex()}} +\item \code{\link[=geom_quantile]{geom_quantile()}} and \code{\link[=stat_quantile]{stat_quantile()}} +\item \code{\link[=geom_smooth]{geom_smooth()}} and \code{\link[=stat_smooth]{stat_smooth()}} +} +} + +\section{Using computed variables}{ +As mentioned above, the role of stats is to perform computation on the data. +As a result, stats have 'computed variables' that determine compatibility +with geoms. These computed variables are documented in the +\strong{Computed variables} sections of the documentation, for example in +\code{\link[=stat_bin]{?stat_bin}}. While more thoroughly documented +in \code{\link[=after_stat]{after_stat()}}, it should briefly be mentioned that these computed stats +can be accessed in \code{\link[=aes]{aes()}}. + +For example, the \code{\link[=stat_density]{?stat_density}} documentation states that, +in addition to a variable called \code{density}, the stat computes a variable +named \code{count}. Instead of scaling such that the area integrates to 1, the +\code{count} variable scales the computed density such that the values +can be interpreted as counts. If \code{stat_density(aes(y = after_stat(count)))} +is used, we can display these count-scaled densities instead of the regular +densities. + +The computed variables offer flexibility in that arbitrary geom-stat pairings +can be made. While not necessarily recommended, \code{\link[=geom_line]{geom_line()}} \emph{can} be paired +with \code{stat = "boxplot"} if the line is instructed on how to use the boxplot +computed variables: + +\if{html}{\out{
}}\preformatted{ggplot(mpg, aes(factor(cyl))) + + geom_line( + # Stage gives 'displ' to the stat, and afterwards chooses 'middle' as + # the y-variable to display + aes(y = stage(displ, after_stat = middle), + # Regroup after computing the stats to display a single line + group = after_stat(1)), + stat = "boxplot" + ) +}\if{html}{\out{
}} +} + +\section{Under the hood}{ +Internally, stats are represented as \code{\link[=ggproto]{ggproto}} classes that +occupy a slot in a layer. All these classes inherit from the parental +\code{\link{Stat}} ggproto object that orchestrates how stats work. Briefly, stats +are given the opportunity to perform computation either on the layer as a +whole, a facet panel, or on individual groups. For more information on +extending stats, see the \strong{Creating a new stat} section after +running \code{vignette("extending-ggplot2")}. Additionally, see the \strong{New stats} +section of the +\href{https://ggplot2-book.org/extensions.html#new-stats}{online book}. +} + +\seealso{ +For an overview of all stat layers, see the +\href{https://ggplot2.tidyverse.org/reference/index.html#stats}{online reference}. + +How \link[=after_stat]{computed aesthetics} work. + +Other layer documentation: +\code{\link{layer}()}, +\code{\link{layer_geoms}}, +\code{\link{layer_positions}} +} +\concept{layer documentation} diff --git a/man/stat_ecdf.Rd b/man/stat_ecdf.Rd index 74979bef48..afe248c5bb 100644 --- a/man/stat_ecdf.Rd +++ b/man/stat_ecdf.Rd @@ -38,19 +38,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{geom}{The geometric object to use to display the data, either as a -\code{ggproto} \code{Geom} subclass or as a string naming the geom stripped of the -\code{geom_} prefix (e.g. \code{"point"} rather than \code{"geom_point"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{geom}{The geometric object to use to display the data for this layer. +When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument +can be used to override the default coupling between stats and geoms. The +\code{geom} argument accepts the following: +\itemize{ +\item A \code{Geom} ggproto subclass, for example \code{GeomPoint}. +\item A string naming the geom. To give the geom as a string, strip the +function name of the \code{geom_} prefix. For example, to use \code{geom_point()}, +give the geom as \code{"point"}. +\item For more information and other ways to specify the geom, see the +\link[=layer_geoms]{layer geom} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{n}{if NULL, do not interpolate. If not NULL, this is the number of points to interpolate with.} diff --git a/man/stat_ellipse.Rd b/man/stat_ellipse.Rd index 534d62517a..5f175dfb87 100644 --- a/man/stat_ellipse.Rd +++ b/man/stat_ellipse.Rd @@ -39,19 +39,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{geom}{The geometric object to use to display the data, either as a -\code{ggproto} \code{Geom} subclass or as a string naming the geom stripped of the -\code{geom_} prefix (e.g. \code{"point"} rather than \code{"geom_point"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{geom}{The geometric object to use to display the data for this layer. +When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument +can be used to override the default coupling between stats and geoms. The +\code{geom} argument accepts the following: +\itemize{ +\item A \code{Geom} ggproto subclass, for example \code{GeomPoint}. +\item A string naming the geom. To give the geom as a string, strip the +function name of the \code{geom_} prefix. For example, to use \code{geom_point()}, +give the geom as \code{"point"}. +\item For more information and other ways to specify the geom, see the +\link[=layer_geoms]{layer geom} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{type}{The type of ellipse. The default \code{"t"} assumes a multivariate t-distribution, and diff --git a/man/stat_identity.Rd b/man/stat_identity.Rd index 2d6dc103a6..765410bbfb 100644 --- a/man/stat_identity.Rd +++ b/man/stat_identity.Rd @@ -35,19 +35,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{geom}{The geometric object to use to display the data, either as a -\code{ggproto} \code{Geom} subclass or as a string naming the geom stripped of the -\code{geom_} prefix (e.g. \code{"point"} rather than \code{"geom_point"})} +\item{geom}{The geometric object to use to display the data for this layer. +When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument +can be used to override the default coupling between stats and geoms. The +\code{geom} argument accepts the following: +\itemize{ +\item A \code{Geom} ggproto subclass, for example \code{GeomPoint}. +\item A string naming the geom. To give the geom as a string, strip the +function name of the \code{geom_} prefix. For example, to use \code{geom_point()}, +give the geom as \code{"point"}. +\item For more information and other ways to specify the geom, see the +\link[=layer_geoms]{layer geom} documentation. +}} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{show.legend}{logical. Should this layer be included in the legends? \code{NA}, the default, includes if any aesthetics are mapped. diff --git a/man/stat_sf_coordinates.Rd b/man/stat_sf_coordinates.Rd index 2d46e1696c..75656a44c1 100644 --- a/man/stat_sf_coordinates.Rd +++ b/man/stat_sf_coordinates.Rd @@ -39,14 +39,31 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{geom}{The geometric object to use to display the data, either as a -\code{ggproto} \code{Geom} subclass or as a string naming the geom stripped of the -\code{geom_} prefix (e.g. \code{"point"} rather than \code{"geom_point"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{geom}{The geometric object to use to display the data for this layer. +When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument +can be used to override the default coupling between stats and geoms. The +\code{geom} argument accepts the following: +\itemize{ +\item A \code{Geom} ggproto subclass, for example \code{GeomPoint}. +\item A string naming the geom. To give the geom as a string, strip the +function name of the \code{geom_} prefix. For example, to use \code{geom_point()}, +give the geom as \code{"point"}. +\item For more information and other ways to specify the geom, see the +\link[=layer_geoms]{layer geom} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} @@ -68,10 +85,31 @@ will be used. Note that the function may warn about the incorrectness of the result if the data is not projected, but you can ignore this except when you really care about the exact locations.} -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} } \description{ \code{stat_sf_coordinates()} extracts the coordinates from 'sf' objects and diff --git a/man/stat_summary.Rd b/man/stat_summary.Rd index 1be81178ef..8b52cc8449 100644 --- a/man/stat_summary.Rd +++ b/man/stat_summary.Rd @@ -69,19 +69,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{geom}{The geometric object to use to display the data, either as a -\code{ggproto} \code{Geom} subclass or as a string naming the geom stripped of the -\code{geom_} prefix (e.g. \code{"point"} rather than \code{"geom_point"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{geom}{The geometric object to use to display the data for this layer. +When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument +can be used to override the default coupling between stats and geoms. The +\code{geom} argument accepts the following: +\itemize{ +\item A \code{Geom} ggproto subclass, for example \code{GeomPoint}. +\item A string naming the geom. To give the geom as a string, strip the +function name of the \code{geom_} prefix. For example, to use \code{geom_point()}, +give the geom as \code{"point"}. +\item For more information and other ways to specify the geom, see the +\link[=layer_geoms]{layer geom} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{fun.data}{A function that is given the complete data and should return a data frame with variables \code{ymin}, \code{y}, and \code{ymax}.} diff --git a/man/stat_summary_2d.Rd b/man/stat_summary_2d.Rd index b7e1f433e9..4fcf667289 100644 --- a/man/stat_summary_2d.Rd +++ b/man/stat_summary_2d.Rd @@ -59,19 +59,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{geom}{The geometric object to use to display the data, either as a -\code{ggproto} \code{Geom} subclass or as a string naming the geom stripped of the -\code{geom_} prefix (e.g. \code{"point"} rather than \code{"geom_point"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} - -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{geom}{The geometric object to use to display the data for this layer. +When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument +can be used to override the default coupling between stats and geoms. The +\code{geom} argument accepts the following: +\itemize{ +\item A \code{Geom} ggproto subclass, for example \code{GeomPoint}. +\item A string naming the geom. To give the geom as a string, strip the +function name of the \code{geom_} prefix. For example, to use \code{geom_point()}, +give the geom as \code{"point"}. +\item For more information and other ways to specify the geom, see the +\link[=layer_geoms]{layer geom} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} + +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{bins}{numeric vector giving number of bins in both vertical and horizontal directions. Set to 30 by default.} diff --git a/man/stat_unique.Rd b/man/stat_unique.Rd index b9d58d67b6..9e0dc52ca5 100644 --- a/man/stat_unique.Rd +++ b/man/stat_unique.Rd @@ -36,19 +36,57 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{geom}{The geometric object to use to display the data, either as a -\code{ggproto} \code{Geom} subclass or as a string naming the geom stripped of the -\code{geom_} prefix (e.g. \code{"point"} rather than \code{"geom_point"})} +\item{geom}{The geometric object to use to display the data for this layer. +When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument +can be used to override the default coupling between stats and geoms. The +\code{geom} argument accepts the following: +\itemize{ +\item A \code{Geom} ggproto subclass, for example \code{GeomPoint}. +\item A string naming the geom. To give the geom as a string, strip the +function name of the \code{geom_} prefix. For example, to use \code{geom_point()}, +give the geom as \code{"point"}. +\item For more information and other ways to specify the geom, see the +\link[=layer_geoms]{layer geom} documentation. +}} -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[=layer_positions]{layer position} documentation. +}} -\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are -often aesthetics, used to set an aesthetic to a fixed value, like -\code{colour = "red"} or \code{size = 3}. They may also be parameters -to the paired geom/stat.} +\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These +arguments broadly fall into one of 4 categories below. Notably, further +arguments to the \code{position} argument, or aesthetics that are required +can \emph{not} be passed through \code{...}. Unknown arguments that are not part +of the 4 categories below are ignored. +\itemize{ +\item Static aesthetics that are not mapped to a scale, but are at a fixed +value and apply to the layer as a whole. For example, \code{colour = "red"} +or \code{linewidth = 3}. The geom's documentation has an \strong{Aesthetics} +section that lists the available options. The 'required' aesthetics +cannot be passed on to the \code{params}. +\item When constructing a layer using +a \verb{stat_*()} function, the \code{...} argument can be used to pass on +parameters to the \code{geom} part of the layer. An example of this is +\code{stat_density(geom = "area", outline.type = "both")}. The geom's +documentation lists which parameters it can accept. +\item Inversely, when constructing a layer using a +\verb{geom_*()} function, the \code{...} argument can be used to pass on parameters +to the \code{stat} part of the layer. An example of this is +\code{geom_area(stat = "density", adjust = 0.5)}. The stat's documentation +lists which parameters it can accept. +\item The \code{key_glyph} argument of \code{\link[=layer]{layer()}} may also be passed on through +\code{...}. This can be one of the functions described as +\link[=draw_key]{key glyphs}, to change the display of the layer in the legend. +}} \item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.}