diff --git a/R/annotation.R b/R/annotation.R index f56494c43c..1569b3b4d7 100644 --- a/R/annotation.R +++ b/R/annotation.R @@ -18,8 +18,7 @@ #' @param geom name of geom to use for annotation #' @param x,y,xmin,ymin,xmax,ymax,xend,yend positioning aesthetics - #' you must specify at least one of these. -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @seealso #' The `r link_book("custom annotations section", "annotations#sec-custom-annotations")` #' @export diff --git a/R/geom-abline.R b/R/geom-abline.R index a47a9dd86a..dea2808936 100644 --- a/R/geom-abline.R +++ b/R/geom-abline.R @@ -31,8 +31,7 @@ NULL #' #' @seealso See [geom_segment()] for a more general approach to #' adding straight line segments to a plot. -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @param mapping Set of aesthetic mappings created by [aes()]. #' @param xintercept,yintercept,slope,intercept Parameters that control the #' position of the line. If these are set, `data`, `mapping` and diff --git a/R/geom-bar.R b/R/geom-bar.R index 42d4d1db2b..219223cda4 100644 --- a/R/geom-bar.R +++ b/R/geom-bar.R @@ -66,7 +66,7 @@ GeomBar <- ggproto( #' [position_fill()] shows relative proportions at each `x` by stacking the #' bars and then standardising each bar to have the same height. #' -#' @eval rd_orientation() +#' @inheritSection shared_layer_parameters Orientation #' #' @aesthetics GeomBar #' @aesthetics GeomCol @@ -76,12 +76,7 @@ GeomBar <- ggproto( #' [position_dodge()] and [position_dodge2()] for creating side-by-side #' bar charts. #' @export -#' @inheritParams layer -#' @inheritParams geom_point -#' @param orientation The orientation of the layer. The default (`NA`) -#' automatically determines the orientation from the aesthetic mapping. In the -#' rare event that this fails it can be given explicitly by setting `orientation` -#' to either `"x"` or `"y"`. See the *Orientation* section for more detail. +#' @inheritParams shared_layer_parameters #' @param just Adjustment for column placement. Set to `0.5` by default, meaning #' that columns will be centered about axis breaks. Set to `0` or `1` to place #' columns to the left/right of axis breaks. Note that this argument may have @@ -90,8 +85,6 @@ GeomBar <- ggproto( #' @param geom,stat Override the default connection between `geom_bar()` and #' `stat_count()`. For more information about overriding these connections, #' see how the [stat][layer_stats] and [geom][layer_geoms] arguments work. -#' @param lineend Line end style (round, butt, square). -#' @param linejoin Line join style (round, mitre, bevel). #' @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 2e937a9d70..dba95a3cf9 100644 --- a/R/geom-bin2d.R +++ b/R/geom-bin2d.R @@ -17,14 +17,11 @@ GeomBin2d <- ggproto("GeomBin2d", GeomTile) #' @aesthetics GeomBin2d #' #' @export -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @param geom,stat Use to override the default connection between #' `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. -#' @param lineend Line end style (round, butt, square). -#' @param linejoin Line join style (round, mitre, bevel). #' @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-blank.R b/R/geom-blank.R index 72b5b1e265..04fcee42ae 100644 --- a/R/geom-blank.R +++ b/R/geom-blank.R @@ -5,8 +5,7 @@ #' more details. #' #' @export -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @examples #' ggplot(mtcars, aes(wt, mpg)) #' # Nothing to see here! diff --git a/R/geom-boxplot.R b/R/geom-boxplot.R index 78bdbacc30..1490f80557 100644 --- a/R/geom-boxplot.R +++ b/R/geom-boxplot.R @@ -4,7 +4,7 @@ #' It visualises five summary statistics (the median, two hinges #' and two whiskers), and all "outlying" points individually. #' -#' @eval rd_orientation() +#' @inheritSection shared_layer_parameters Orientation #' #' @section Summary statistics: #' The lower and upper hinges correspond to the first and third quartiles @@ -29,8 +29,7 @@ #' @seealso [geom_quantile()] for continuous `x`, #' [geom_violin()] for a richer display of the distribution, and #' [geom_jitter()] for a useful technique for small data. -#' @inheritParams layer -#' @inheritParams geom_bar +#' @inheritParams shared_layer_parameters #' @param geom,stat Use to override the default connection between #' `geom_boxplot()` and `stat_boxplot()`. For more information about #' overriding these connections, see how the [stat][layer_stats] and diff --git a/R/geom-contour.R b/R/geom-contour.R index f6791fd4dc..1ff050fad5 100644 --- a/R/geom-contour.R +++ b/R/geom-contour.R @@ -36,9 +36,7 @@ GeomContourFilled <- ggproto("GeomContourFilled", GeomPolygon) #' #' @aesthetics GeomContour #' @aesthetics GeomContourFilled -#' @inheritParams layer -#' @inheritParams geom_point -#' @inheritParams geom_path +#' @inheritParams shared_layer_parameters #' @param binwidth The width of the contour bins. Overridden by `bins`. #' @param bins Number of contour bins. Overridden by `breaks`. #' @param breaks One of: diff --git a/R/geom-count.R b/R/geom-count.R index 9288033bde..1c27c5f334 100644 --- a/R/geom-count.R +++ b/R/geom-count.R @@ -13,8 +13,7 @@ NULL #' 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 +#' @inheritParams shared_layer_parameters #' @export #' @examples #' ggplot(mpg, aes(cty, hwy)) + diff --git a/R/geom-density.R b/R/geom-density.R index d1964c07fe..1d1fde37b8 100644 --- a/R/geom-density.R +++ b/R/geom-density.R @@ -21,13 +21,12 @@ GeomDensity <- ggproto( #' the histogram. This is a useful alternative to the histogram for continuous #' data that comes from an underlying smooth distribution. #' -#' @eval rd_orientation() +#' @inheritSection shared_layer_parameters Orientation #' @aesthetics GeomDensity #' @seealso See [geom_histogram()], [geom_freqpoly()] for #' other methods of displaying continuous distribution. #' See [geom_violin()] for a compact density display. -#' @inheritParams layer -#' @inheritParams geom_bar +#' @inheritParams shared_layer_parameters #' @inheritParams geom_ribbon #' @param geom,stat Use to override the default connection between #' `geom_density()` and `stat_density()`. For more information about diff --git a/R/geom-density2d.R b/R/geom-density2d.R index 0197e2698e..9dc762ec35 100644 --- a/R/geom-density2d.R +++ b/R/geom-density2d.R @@ -15,9 +15,7 @@ #' `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 +#' @inheritParams shared_layer_parameters #' @param contour_var Character string identifying the variable to contour #' by. Can be one of `"density"`, `"ndensity"`, or `"count"`. See the section #' on computed variables for details. diff --git a/R/geom-dotplot.R b/R/geom-dotplot.R index 89def6a9ac..1115171294 100644 --- a/R/geom-dotplot.R +++ b/R/geom-dotplot.R @@ -29,8 +29,7 @@ #' ndensity = 'density, scaled to maximum of 1, if method is `"histodot"`.' #' ) #' -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @param stackdir which direction to stack the dots. "up" (default), #' "down", "center", "centerwhole" (centered, but with dots aligned) #' @param stackratio how close to stack the dots. Default is 1, where dots diff --git a/R/geom-function.R b/R/geom-function.R index ba595da7c3..b8939bce57 100644 --- a/R/geom-function.R +++ b/R/geom-function.R @@ -30,8 +30,7 @@ GeomFunction <- ggproto("GeomFunction", GeomPath, #' #' @aesthetics GeomFunction #' @param data Ignored by `stat_function()`, do not use. -#' @inheritParams layer -#' @inheritParams geom_path +#' @inheritParams shared_layer_parameters #' @examples #' #' # geom_function() is useful for overlaying functions diff --git a/R/geom-hex.R b/R/geom-hex.R index 0e67b49ad9..9cef38c47c 100644 --- a/R/geom-hex.R +++ b/R/geom-hex.R @@ -80,11 +80,7 @@ GeomHex <- ggproto("GeomHex", Geom, #' `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 -#' @param lineend Line end style (round, butt, square). -#' @param linejoin Line join style (round, mitre, bevel). -#' @param linemitre Line mitre limit (number greater than 1). +#' @inheritParams shared_layer_parameters #' @export #' @examples #' d <- ggplot(diamonds, aes(carat, price)) diff --git a/R/geom-histogram.R b/R/geom-histogram.R index a922a54dd7..90778d85a8 100644 --- a/R/geom-histogram.R +++ b/R/geom-histogram.R @@ -27,15 +27,14 @@ #' `scale_x_binned()` with [geom_bar()]. This method by default plots tick marks #' in between each bar. #' -#' @eval rd_orientation() +#' @inheritSection shared_layer_parameters Orientation #' #' @section Aesthetics: #' `geom_histogram()` uses the same aesthetics as [geom_bar()]; #' `geom_freqpoly()` uses the same aesthetics as [geom_line()]. #' #' @export -#' @inheritParams layer -#' @inheritParams geom_bar +#' @inheritParams shared_layer_parameters #' @param geom,stat Use to override the default connection between #' `geom_histogram()`/`geom_freqpoly()` and `stat_bin()`. For more information #' at overriding these connections, see how the [stat][layer_stats] and diff --git a/R/geom-jitter.R b/R/geom-jitter.R index 1f4b3e99c9..28492e9025 100644 --- a/R/geom-jitter.R +++ b/R/geom-jitter.R @@ -6,8 +6,7 @@ #' overplotting caused by discreteness in smaller datasets. #' #' @aesthetics GeomPoint -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @inheritParams position_jitter #' @seealso #' [geom_point()] for regular, unjittered points, diff --git a/R/geom-linerange.R b/R/geom-linerange.R index 0d67908ec8..e8d7f0985d 100644 --- a/R/geom-linerange.R +++ b/R/geom-linerange.R @@ -42,7 +42,7 @@ GeomLinerange <- ggproto( #' Various ways of representing a vertical interval defined by `x`, #' `ymin` and `ymax`. Each case draws a single graphical object. #' -#' @eval rd_orientation() +#' @inheritSection shared_layer_parameters Orientation #' #' @aesthetics GeomLinerange #' Note that `geom_pointrange()` also understands `size` for the size of the points. @@ -53,8 +53,7 @@ GeomLinerange <- ggproto( #' [stat_summary()] for examples of these guys in use, #' [geom_smooth()] for continuous analogue #' @export -#' @inheritParams layer -#' @inheritParams geom_bar +#' @inheritParams shared_layer_parameters #' @examples #' # Create a simple example dataset #' df <- data.frame( diff --git a/R/geom-map.R b/R/geom-map.R index 026bb94e6b..7ee19ec821 100644 --- a/R/geom-map.R +++ b/R/geom-map.R @@ -15,8 +15,7 @@ NULL #' typically be created using [fortify()] on a spatial object. #' It must contain columns `x` or `long`, `y` or #' `lat`, and `region` or `id`. -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @examples #' # First, a made-up example containing a few polygons, to explain #' # how `geom_map()` works. It requires two data frames: diff --git a/R/geom-path.R b/R/geom-path.R index 98c2f731d1..fe51e97b86 100644 --- a/R/geom-path.R +++ b/R/geom-path.R @@ -178,17 +178,10 @@ GeomStep <- ggproto( #' An alternative parameterisation is [geom_segment()], where each line #' corresponds to a single case which provides the start and end coordinates. #' -#' @eval rd_orientation() +#' @inheritSection shared_layer_parameters Orientation #' #' @aesthetics GeomPath -#' @inheritParams layer -#' @inheritParams geom_bar -#' @param lineend Line end style (round, butt, square). -#' @param linejoin Line join style (round, mitre, bevel). -#' @param linemitre Line mitre limit (number greater than 1). -#' @param arrow Arrow specification, as created by [grid::arrow()]. -#' @param arrow.fill fill colour to use for the arrow head (if closed). `NULL` -#' means use `colour` aesthetic. +#' @inheritParams shared_layer_parameters #' @seealso #' [geom_polygon()]: Filled paths (polygons); #' [geom_segment()]: Line segments diff --git a/R/geom-point.R b/R/geom-point.R index f03d1a9917..6df965d51f 100644 --- a/R/geom-point.R +++ b/R/geom-point.R @@ -67,34 +67,7 @@ GeomPoint <- ggproto( #' #' @aesthetics GeomPoint #' The `fill` aesthetic only applies to shapes 21-25. -#' @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()]'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`. Please note that while passing -#' unmapped aesthetics as vectors is technically possible, the order and -#' required length is not guaranteed to be parallel to the input data. -#' * 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. +#' @inheritParams shared_layer_parameters #' #' @export #' @examples diff --git a/R/geom-polygon.R b/R/geom-polygon.R index 8fe3f5753f..fcbbe22711 100644 --- a/R/geom-polygon.R +++ b/R/geom-polygon.R @@ -105,11 +105,7 @@ GeomPolygon <- ggproto("GeomPolygon", Geom, #' [geom_path()] for an unfilled polygon, #' [geom_ribbon()] for a polygon anchored on the x-axis #' @export -#' @inheritParams layer -#' @inheritParams geom_point -#' @param lineend Line end style (round, butt, square). -#' @param linejoin Line join style (round, mitre, bevel). -#' @param linemitre Line mitre limit (number greater than 1). +#' @inheritParams shared_layer_parameters #' @param rule Either `"evenodd"` or `"winding"`. If polygons with holes are #' being drawn (using the `subgroup` aesthetic) this argument defines how the #' hole coordinates are interpreted. See the examples in [grid::pathGrob()] for diff --git a/R/geom-quantile.R b/R/geom-quantile.R index 99d569538f..191cdbf8d3 100644 --- a/R/geom-quantile.R +++ b/R/geom-quantile.R @@ -18,9 +18,7 @@ GeomQuantile <- ggproto( #' #' @aesthetics GeomQuantile #' @export -#' @inheritParams layer -#' @inheritParams geom_point -#' @inheritParams geom_path +#' @inheritParams shared_layer_parameters #' @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 diff --git a/R/geom-ribbon.R b/R/geom-ribbon.R index 8816b44d9b..2072c3abc3 100644 --- a/R/geom-ribbon.R +++ b/R/geom-ribbon.R @@ -241,16 +241,14 @@ GeomArea <- ggproto("GeomArea", GeomRibbon, #' of x-coordinates. To turn off this interpolation, `stat = "identity"` can #' be used instead. #' -#' @eval rd_orientation() +#' @inheritSection shared_layer_parameters Orientation #' #' @aesthetics GeomRibbon #' @seealso #' [geom_bar()] for discrete intervals (bars), #' [geom_linerange()] for discrete intervals (lines), #' [geom_polygon()] for general polygons -#' @inheritParams layer -#' @inheritParams geom_bar -#' @param linemitre Line mitre limit (number greater than 1). +#' @inheritParams shared_layer_parameters #' @param outline.type Type of the outline of the area; `"both"` draws both the #' upper and lower lines, `"upper"`/`"lower"` draws the respective lines only. #' `"full"` draws a closed polygon around the area. diff --git a/R/geom-rug.R b/R/geom-rug.R index 2f2b37cd2d..dc46583a4d 100644 --- a/R/geom-rug.R +++ b/R/geom-rug.R @@ -133,14 +133,12 @@ GeomRug <- ggproto("GeomRug", Geom, #' any data points under the default settings. #' #' @aesthetics GeomRug -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @param sides A string that controls which sides of the plot the rugs appear on. #' It can be set to a string containing any of `"trbl"`, for top, right, #' bottom, and left. #' @param 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 `coord_cartesian(clip = "off")`. When set to TRUE, also consider changing the sides argument to "tr". See examples. #' @param length A [grid::unit()] object that sets the length of the rug lines. Use scale expansion to avoid overplotting of data. -#' @param lineend Line end style (round, butt, square). #' @export #' @examples #' p <- ggplot(mtcars, aes(wt, mpg)) + diff --git a/R/geom-segment.R b/R/geom-segment.R index 77ca127a44..adcf7633ab 100644 --- a/R/geom-segment.R +++ b/R/geom-segment.R @@ -65,13 +65,7 @@ GeomSegment <- ggproto( #' need to connect points across multiple cases. #' #' @aesthetics GeomSegment -#' @inheritParams layer -#' @inheritParams geom_point -#' @param arrow specification for arrow heads, as created by [grid::arrow()]. -#' @param arrow.fill fill colour to use for the arrow head (if closed). `NULL` -#' means use `colour` aesthetic. -#' @param lineend Line end style (round, butt, square). -#' @param linejoin Line join style (round, mitre, bevel). +#' @inheritParams shared_layer_parameters #' @seealso [geom_path()] and [geom_line()] for multi- #' segment lines and paths. #' @seealso [geom_spoke()] for a segment parameterised by a location diff --git a/R/geom-sf.R b/R/geom-sf.R index 177c30f933..4575a28484 100644 --- a/R/geom-sf.R +++ b/R/geom-sf.R @@ -285,7 +285,7 @@ GeomSf <- ggproto("GeomSf", Geom, #' @export #' @rdname ggsf -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters geom_sf <- function(mapping = aes(), data = NULL, stat = "sf", position = "identity", na.rm = FALSE, show.legend = NA, inherit.aes = TRUE, ...) { diff --git a/R/geom-smooth.R b/R/geom-smooth.R index a022807b16..89fcb2dcdb 100644 --- a/R/geom-smooth.R +++ b/R/geom-smooth.R @@ -74,11 +74,10 @@ GeomSmooth <- ggproto( #' `glm()`, where the normal confidence band is constructed on the link #' scale and then back-transformed to the response scale. #' -#' @eval rd_orientation() +#' @inheritSection shared_layer_parameters Orientation #' #' @aesthetics GeomSmooth -#' @inheritParams layer -#' @inheritParams geom_bar +#' @inheritParams shared_layer_parameters #' @param geom,stat Use to override the default connection between #' `geom_smooth()` and `stat_smooth()`. For more information about overriding #' these connections, see how the [stat][layer_stats] and [geom][layer_geoms] diff --git a/R/geom-spoke.R b/R/geom-spoke.R index 71ac416482..fd61c7efa7 100644 --- a/R/geom-spoke.R +++ b/R/geom-spoke.R @@ -23,8 +23,7 @@ GeomSpoke <- ggproto( #' The angles start from east and increase counterclockwise. #' #' @aesthetics GeomSpoke -#' @inheritParams layer -#' @inheritParams geom_segment +#' @inheritParams shared_layer_parameters #' @export #' @examples #' df <- expand.grid(x = 1:10, y=1:10) diff --git a/R/geom-text.R b/R/geom-text.R index 406067856e..e22deb0012 100644 --- a/R/geom-text.R +++ b/R/geom-text.R @@ -90,8 +90,7 @@ GeomText <- ggproto( #' `"outward"`. Inward always aligns text towards the center, and outward #' aligns it away from the center. #' -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @param parse If `TRUE`, the labels will be parsed into expressions and #' displayed as described in `?plotmath`. #' @param check_overlap If `TRUE`, text that overlaps previous text in the diff --git a/R/geom-tile.R b/R/geom-tile.R index 85673eddce..c42a63c8ae 100644 --- a/R/geom-tile.R +++ b/R/geom-tile.R @@ -57,9 +57,7 @@ GeomTile <- ggproto( #' @aesthetics GeomRect #' `geom_tile()` understands only the `x`/`width` and `y`/`height` combinations. #' Note that `geom_raster()` ignores `colour`. -#' @inheritParams layer -#' @inheritParams geom_point -#' @inheritParams geom_segment +#' @inheritParams shared_layer_parameters #' @export #' #' @details diff --git a/R/geom-violin.R b/R/geom-violin.R index 5ba06844f3..821b0de426 100644 --- a/R/geom-violin.R +++ b/R/geom-violin.R @@ -5,11 +5,10 @@ #' violin plot is a mirrored density plot displayed in the same way as a #' boxplot. #' -#' @eval rd_orientation() +#' @inheritSection shared_layer_parameters Orientation #' #' @aesthetics GeomViolin -#' @inheritParams layer -#' @inheritParams geom_bar +#' @inheritParams shared_layer_parameters #' @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 diff --git a/R/layer.R b/R/layer.R index 179f519441..2b2bd5f785 100644 --- a/R/layer.R +++ b/R/layer.R @@ -1,3 +1,144 @@ +#' @name shared_layer_parameters +#' @title Shared layer parameters +#' @description +#' This is a central place for describing typical layer parameters. +#' It prevents cluttered definitions all over the place. +#' +#' @param mapping +#' Set of aesthetic mappings created by [aes()]. If specified and `inherit.aes = +#' TRUE` (the default), it is combined with the default mapping at the top level +#' of the plot. You must supply `mapping` if there is no plot mapping. +#' +#' @param data +#' The data to be displayed in this layer. There are three options: +#' * `NULL` (default): the data is inherited from the plot data as specified +#' in the call to [ggplot()]. +#' * A `data.frame`, or other object, will override the plot data. All objects +#' will be fortified to produce a data frame. See [fortify()] for which +#' variables will be created. +#' * A `function` will be called with a single argument, 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 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 +#' to 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 na.rm +#' If `FALSE`, the default, missing values are removed with a warning. If +#' `TRUE`, missing values are silently removed. +#' +#' @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. It can also be a named logical vector to finely select the +#' aesthetics to display. To include legend keys for all levels, even when no +#' data exists, use `TRUE`. If `NA`, all levels are shown in legend, but +#' unobserved levels are omitted. +#' +#' @param inherit.aes +#' If `FALSE`, overrides the default aesthetics, 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. [annotation_borders()]. +#' +#' @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`. Please note that while passing unmapped +#' aesthetics as vectors is technically possible, the order and required +#' length is not guaranteed to be parallel to the input data. +#' * 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. +#' +#' @param lineend +#' Line end style, one of `"round"`, `"butt"` or `"square"`. +#' +#' @param linejoin +#' Line join style, one of `"round"`, `"mitre"` or `"bevel"`. +#' +#' @param linemitre +#' Line mitre limit, a number greater than 1. +#' +#' @param arrow +#' Arrow specification. Can be created by [grid::arrow()] or `NULL` to not draw +#' an arrow. +#' +#' @param arrow.fill +#' Fill colour to use for closed arrowheads. `NULL` means use `colour` +#' aesthetic. +#' +#' @param orientation +#' The orientation of the layer. The default (`NA`) automatically determines the +#' orientation from the aesthetic mapping. In the rare event that this fails it +#' can be given explicitly by setting `orientation` to either `"x"` or `"y"`. +#' See the *Orientation* section for more detail. +#' +#' @section Orientation: +#' This geom treats each axis differently and, thus, can thus have two +#' orientations. Often the orientation is easy to deduce from a combination of +#' the given mappings and the types of positional scales in use. Thus, ggplot2 +#' will by default try to guess which orientation the layer should have. Under +#' rare circumstances, the orientation is ambiguous and guessing may fail. In +#' that case the orientation can be specified directly using the `orientation` +#' parameter, which can be either `"x"` or `"y"`. The value gives the axis that +#' the geom should run along, `"x"` being the default orientation you would +#' expect for the geom. +#' +#' @keywords internal +#' @aliases NULL +NULL + #' Create a new layer #' #' A layer is a combination of data, stat and geom with a potential position @@ -5,66 +146,7 @@ #' calls but it can also be created directly using this function. #' #' @export -#' @param mapping Set of aesthetic mappings created by [aes()]. If specified and -#' `inherit.aes = TRUE` (the default), it is combined with the default mapping -#' at the top level of the plot. You must supply `mapping` if there is no plot -#' mapping. -#' @param data The data to be displayed in this layer. There are three -#' options: -#' -#' If `NULL`, the default, the data is inherited from the plot -#' data as specified in the call to [ggplot()]. -#' -#' A `data.frame`, or other object, will override the plot -#' data. All objects will be fortified to produce a data frame. See -#' [fortify()] for which variables will be created. -#' -#' A `function` will be called with a single argument, -#' 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 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 to 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. -#' It can also be a named logical vector to finely select the aesthetics to -#' display. To include legend keys for all levels, even -#' when no data exists, use `TRUE`. If `NA`, all levels are shown in legend, -#' but unobserved levels are omitted. -#' @param inherit.aes If `FALSE`, overrides the default aesthetics, -#' 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. [annotation_borders()]. +#' @inheritParams shared_layer_parameters #' @param check.aes,check.param If `TRUE`, the default, will check that #' supplied parameters and aesthetics are understood by the `geom` or #' `stat`. Use `FALSE` to suppress the checks. diff --git a/R/stat-align.R b/R/stat-align.R index c0807382c7..5ff057c2f9 100644 --- a/R/stat-align.R +++ b/R/stat-align.R @@ -83,8 +83,7 @@ StatAlign <- ggproto( } ) -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @export #' @rdname geom_ribbon stat_align <- make_constructor( diff --git a/R/stat-boxplot.R b/R/stat-boxplot.R index ef893a6f0c..cfc137d4c3 100644 --- a/R/stat-boxplot.R +++ b/R/stat-boxplot.R @@ -99,7 +99,7 @@ StatBoxplot <- ggproto("StatBoxplot", Stat, #' @rdname geom_boxplot #' @param coef Length of the whiskers as multiple of IQR. Defaults to 1.5. -#' @inheritParams stat_identity +#' @inheritParams shared_layer_parameters #' @export #' @eval rd_computed_vars( #' .details = "`stat_boxplot()` provides the following variables, some of diff --git a/R/stat-connect.R b/R/stat-connect.R index a2a73590bd..d7a75c62b2 100644 --- a/R/stat-connect.R +++ b/R/stat-connect.R @@ -105,8 +105,7 @@ StatConnect <- ggproto( #' #' Connect successive points with lines of different shapes. #' -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @param connection A specification of how two points are connected. Can be one #' of the folloing: #' * A string giving a named connection. These options are: diff --git a/R/stat-contour.R b/R/stat-contour.R index ca984909fa..83385f8e06 100644 --- a/R/stat-contour.R +++ b/R/stat-contour.R @@ -84,7 +84,7 @@ StatContourFilled <- ggproto( } ) -#' @inheritParams stat_identity +#' @inheritParams shared_layer_parameters #' @inheritParams geom_contour #' @export #' @aesthetics StatContour diff --git a/R/stat-ecdf.R b/R/stat-ecdf.R index 6d1084d719..16ea1a64c2 100644 --- a/R/stat-ecdf.R +++ b/R/stat-ecdf.R @@ -65,8 +65,7 @@ StatEcdf <- ggproto( #' this case, the ECDF is incremented by `weight / sum(weight)` instead of #' `1 / length(x)` for each observation. #' -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @param na.rm If `FALSE` (the default), removes missing values with #' a warning. If `TRUE` silently removes missing values. #' @param n if NULL, do not interpolate. If not NULL, this is the number diff --git a/R/stat-ellipse.R b/R/stat-ellipse.R index dfd8c698d3..daa8417d9c 100644 --- a/R/stat-ellipse.R +++ b/R/stat-ellipse.R @@ -43,8 +43,7 @@ StatEllipse <- ggproto( #' representing the euclidean distance from the center. #' This ellipse probably won't appear circular unless `coord_fixed()` is applied. #' @param segments The number of segments to be used in drawing the ellipse. -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @aesthetics StatEllipse #' @export #' @examples diff --git a/R/stat-identity.R b/R/stat-identity.R index bf71163a9d..cafcc9f6c5 100644 --- a/R/stat-identity.R +++ b/R/stat-identity.R @@ -13,8 +13,7 @@ StatIdentity <- ggproto( #' #' The identity statistic leaves the data unchanged. #' -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @export #' @examples #' p <- ggplot(mtcars, aes(wt, mpg)) diff --git a/R/stat-manual.R b/R/stat-manual.R index d7ead2f189..822499cf53 100644 --- a/R/stat-manual.R +++ b/R/stat-manual.R @@ -21,8 +21,7 @@ StatManual <- ggproto( #' `stat_manual()` takes a function that computes a data transformation for #' every group. #' -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @param fun Function that takes a data frame as input and returns a data #' frame or data frame-like list as output. The default (`identity()`) returns #' the data unchanged. diff --git a/R/stat-qq.R b/R/stat-qq.R index b97796bd78..663d491bbd 100644 --- a/R/stat-qq.R +++ b/R/stat-qq.R @@ -39,8 +39,7 @@ StatQq <- ggproto( #' @param distribution Distribution function to use, if x not specified #' @param dparams Additional parameters passed on to `distribution` #' function. -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @eval rd_computed_vars( #' .details = "\\cr Variables computed by `stat_qq()`:", #' sample = "Sample quantiles.", diff --git a/R/stat-quantilemethods.R b/R/stat-quantilemethods.R index 4999aa7304..c89dfd5a59 100644 --- a/R/stat-quantilemethods.R +++ b/R/stat-quantilemethods.R @@ -66,8 +66,7 @@ StatQuantile <- ggproto( #' @param formula formula relating y variables to x variables #' @param method Quantile regression method to use. Available options are `"rq"` (for #' [`quantreg::rq()`]) and `"rqss"` (for [`quantreg::rqss()`]). -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @eval rd_computed_vars( #' quantile = "Quantile of distribution." #' ) diff --git a/R/stat-sf-coordinates.R b/R/stat-sf-coordinates.R index b54c8f6376..f7512924a4 100644 --- a/R/stat-sf-coordinates.R +++ b/R/stat-sf-coordinates.R @@ -48,8 +48,7 @@ #' } #' #' @export -#' @inheritParams stat_identity -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @param fun.geometry #' A function that takes a `sfc` object and returns a `sfc_POINT` with the #' same length as the input. If `NULL`, `function(x) sf::st_point_on_surface(sf::st_zm(x))` diff --git a/R/stat-sf.R b/R/stat-sf.R index cf0b55c0ec..3e7b487da8 100644 --- a/R/stat-sf.R +++ b/R/stat-sf.R @@ -58,7 +58,7 @@ StatSf <- ggproto("StatSf", Stat, #' @export #' @rdname ggsf -#' @inheritParams stat_identity +#' @inheritParams shared_layer_parameters stat_sf <- function(mapping = NULL, data = NULL, geom = "rect", position = "identity", na.rm = FALSE, show.legend = NA, inherit.aes = TRUE, ...) { diff --git a/R/stat-sum.R b/R/stat-sum.R index c764cbc14f..89af8168e6 100644 --- a/R/stat-sum.R +++ b/R/stat-sum.R @@ -20,8 +20,7 @@ StatSum <- ggproto( } ) -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @eval rd_computed_vars( #' n = "Number of observations at position.", #' prop = "Percent of points in that panel at that position." diff --git a/R/stat-summary-2d.R b/R/stat-summary-2d.R index 847cb68bfc..312b775189 100644 --- a/R/stat-summary-2d.R +++ b/R/stat-summary-2d.R @@ -86,8 +86,7 @@ StatSummary2d <- ggproto( #' } #' @seealso [stat_summary_hex()] for hexagonal summarization. #' [stat_bin_2d()] for the binning options. -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @inheritParams stat_bin_2d #' @param drop drop if the output of `fun` is `NA`. #' @param fun function for summary. diff --git a/R/stat-summary.R b/R/stat-summary.R index 789f867da9..c3e32a2ea7 100644 --- a/R/stat-summary.R +++ b/R/stat-summary.R @@ -5,13 +5,13 @@ #' [stat_bin()]: instead of just counting, they can compute any #' aggregate. #' -#' @eval rd_orientation() +#' @inheritSection shared_layer_parameters Orientation #' #' @aesthetics StatSummary #' @seealso [geom_errorbar()], [geom_pointrange()], #' [geom_linerange()], [geom_crossbar()] for geoms to #' display summarised data -#' @inheritParams stat_identity +#' @inheritParams shared_layer_parameters #' @section Summary functions: #' You can either supply summary functions individually (`fun`, #' `fun.max`, `fun.min`), or as a single function (`fun.data`): diff --git a/R/stat-unique.R b/R/stat-unique.R index 0fa45cf5eb..46d19d0b7b 100644 --- a/R/stat-unique.R +++ b/R/stat-unique.R @@ -13,8 +13,7 @@ StatUnique <- ggproto( #' #' @aesthetics StatUnique #' @export -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @examples #' ggplot(mtcars, aes(vs, am)) + #' geom_point(alpha = 0.1) diff --git a/R/stat-ydensity.R b/R/stat-ydensity.R index 0828df91f1..109a6556d5 100644 --- a/R/stat-ydensity.R +++ b/R/stat-ydensity.R @@ -128,8 +128,7 @@ StatYdensity <- ggproto( dropped_aes = "weight" ) -#' @inheritParams layer -#' @inheritParams geom_point +#' @inheritParams shared_layer_parameters #' @inheritParams stat_density #' @param scale if "area" (default), all violins have the same area (before trimming #' the tails). If "count", areas are scaled proportionally to the number of diff --git a/R/utilities-help.R b/R/utilities-help.R index d0c0a15576..2c89b87df4 100644 --- a/R/utilities-help.R +++ b/R/utilities-help.R @@ -87,19 +87,8 @@ rd_match_docpage <- function(aes) { } rd_orientation <- function() { - c( - "@section Orientation: ", - paste( - 'This geom treats each axis differently and, thus, can thus have two orientations.', - 'Often the orientation is easy to deduce from a combination of the given', - 'mappings and the types of positional scales in use. Thus, ggplot2 will by', - 'default try to guess which orientation the layer should have. Under rare', - 'circumstances, the orientation is ambiguous and guessing may fail. In that', - 'case the orientation can be specified directly using the \\code{orientation} parameter,', - 'which can be either \\code{"x"} or \\code{"y"}. The value gives the axis that the geom', - 'should run along, \\code{"x"} being the default orientation you would expect for the geom.' - ) - ) + # This function is vestigial. It exists only not to break dependencies. + "@inheritSection ggplot2::shared_layer_parameters Orientation" } #' Format 'Computed variables' section diff --git a/man/annotate.Rd b/man/annotate.Rd index c5117fa236..e74358741f 100644 --- a/man/annotate.Rd +++ b/man/annotate.Rd @@ -24,36 +24,36 @@ 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()}}'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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} } \description{ This function adds geoms to a plot, but unlike a typical geom function, diff --git a/man/annotation_borders.Rd b/man/annotation_borders.Rd index 4133e0693e..ccf384d8a1 100644 --- a/man/annotation_borders.Rd +++ b/man/annotation_borders.Rd @@ -32,35 +32,27 @@ polygons, see \code{\link[maps:map]{maps::map()}} for details.} \item{...}{ Arguments passed on to \code{\link[=geom_polygon]{geom_polygon}} \describe{ - \item{\code{lineend}}{Line end style (round, butt, square).} - \item{\code{linejoin}}{Line join style (round, mitre, bevel).} - \item{\code{linemitre}}{Line mitre limit (number greater than 1).} \item{\code{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{\code{mapping}}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - \item{\code{data}}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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. -When using a \verb{geom_*()} function to construct a layer, the \code{stat} -argument can be used to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: + \item{\code{mapping}}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + \item{\code{data}}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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. When using +a \verb{geom_*()} function to construct a layer, the \code{stat} argument can be used +to 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 @@ -69,31 +61,33 @@ 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: + \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"}. +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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} - \item{\code{inherit.aes}}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} - \item{\code{na.rm}}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} + \item{\code{na.rm}}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} + \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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} + \item{\code{inherit.aes}}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} + \item{\code{lineend}}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} + \item{\code{linejoin}}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} + \item{\code{linemitre}}{Line mitre limit, a number greater than 1.} }} } \description{ diff --git a/man/geom_abline.Rd b/man/geom_abline.Rd index 06392312b7..eb89d007b7 100644 --- a/man/geom_abline.Rd +++ b/man/geom_abline.Rd @@ -45,25 +45,22 @@ geom_vline( \arguments{ \item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\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 +to 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 @@ -73,59 +70,58 @@ give the stat as \code{"count"}. \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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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.} - -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} - -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} - -\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: +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} + +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} + +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} + +\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"}. +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. }} diff --git a/man/geom_bar.Rd b/man/geom_bar.Rd index c6573959ae..cbb9d4a490 100644 --- a/man/geom_bar.Rd +++ b/man/geom_bar.Rd @@ -47,62 +47,57 @@ stat_count( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -114,34 +109,33 @@ columns to the left/right of axis breaks. Note that this argument may have unintended behaviour when used with alternative positions, e.g. \code{position_dodge()}.} -\item{lineend}{Line end style (round, butt, square).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} -\item{linejoin}{Line join style (round, mitre, bevel).} +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Override the default connection between \code{geom_bar()} and \code{stat_count()}. For more information about overriding these connections, see how the \link[=layer_stats]{stat} and \link[=layer_geoms]{geom} arguments work.} -\item{orientation}{The orientation of the layer. The default (\code{NA}) -automatically determines the orientation from the aesthetic mapping. In the -rare event that this fails it can be given explicitly by setting \code{orientation} -to either \code{"x"} or \code{"y"}. See the \emph{Orientation} section for more detail.} +\item{orientation}{The orientation of the layer. The default (\code{NA}) automatically determines the +orientation from the aesthetic mapping. In the rare event that this fails it +can be given explicitly by setting \code{orientation} to either \code{"x"} or \code{"y"}. +See the \emph{Orientation} section for more detail.} } \description{ There are two types of bar charts: \code{geom_bar()} and \code{geom_col()}. @@ -169,11 +163,6 @@ side-to-side, use \code{\link[=position_dodge]{position_dodge()}} or \code{\link \code{\link[=position_fill]{position_fill()}} shows relative proportions at each \code{x} by stacking the bars and then standardising each bar to have the same height. } -\section{Orientation}{ - -This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the \code{orientation} parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that the geom should run along, \code{"x"} being the default orientation you would expect for the geom. -} - \section{Computed variables}{ These are calculated by the 'stat' part of layers and can be accessed with \link[=aes_eval]{delayed evaluation}. @@ -183,6 +172,19 @@ These are calculated by the 'stat' part of layers and can be accessed with \link } } +\section{Orientation}{ + +This geom treats each axis differently and, thus, can thus have two +orientations. Often the orientation is easy to deduce from a combination of +the given mappings and the types of positional scales in use. Thus, ggplot2 +will by default try to guess which orientation the layer should have. Under +rare circumstances, the orientation is ambiguous and guessing may fail. In +that case the orientation can be specified directly using the \code{orientation} +parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that +the geom should run along, \code{"x"} being the default orientation you would +expect for the geom. +} + \examples{ # geom_bar is designed to make it easy to create bar charts that show # counts (or sums of weights) diff --git a/man/geom_bin_2d.Rd b/man/geom_bin_2d.Rd index 4d77521fcf..8525b163f8 100644 --- a/man/geom_bin_2d.Rd +++ b/man/geom_bin_2d.Rd @@ -39,86 +39,80 @@ stat_bin_2d( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} -\item{linejoin}{Line join style (round, mitre, bevel).} +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Use to override the default connection between \code{geom_bin_2d()} and \code{stat_bin_2d()}. For more information about overriding diff --git a/man/geom_blank.Rd b/man/geom_blank.Rd index 51606bb14b..ab0527dd99 100644 --- a/man/geom_blank.Rd +++ b/man/geom_blank.Rd @@ -15,30 +15,25 @@ geom_blank( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\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 +to 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 @@ -48,59 +43,58 @@ give the stat as \code{"count"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. -\code{FALSE} never includes, and \code{TRUE} always includes. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ The blank geom draws nothing, but can be a useful way of ensuring common diff --git a/man/geom_boxplot.Rd b/man/geom_boxplot.Rd index 9556904fd3..cb17ed5ffe 100644 --- a/man/geom_boxplot.Rd +++ b/man/geom_boxplot.Rd @@ -59,62 +59,57 @@ stat_boxplot( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -159,26 +154,25 @@ Staples mark the ends of the whiskers with a line.} square-roots of the number of observations in the groups (possibly weighted, using the \code{weight} aesthetic).} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{orientation}{The orientation of the layer. The default (\code{NA}) -automatically determines the orientation from the aesthetic mapping. In the -rare event that this fails it can be given explicitly by setting \code{orientation} -to either \code{"x"} or \code{"y"}. See the \emph{Orientation} section for more detail.} +\item{orientation}{The orientation of the layer. The default (\code{NA}) automatically determines the +orientation from the aesthetic mapping. In the rare event that this fails it +can be given explicitly by setting \code{orientation} to either \code{"x"} or \code{"y"}. +See the \emph{Orientation} section for more detail.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Use to override the default connection between \code{geom_boxplot()} and \code{stat_boxplot()}. For more information about @@ -196,11 +190,6 @@ and two whiskers), and all "outlying" points individually. In the unlikely event you specify both US and UK spellings of colour, the US spelling will take precedence. } -\section{Orientation}{ - -This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the \code{orientation} parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that the geom should run along, \code{"x"} being the default orientation you would expect for the geom. -} - \section{Summary statistics}{ The lower and upper hinges correspond to the first and third quartiles @@ -236,6 +225,19 @@ These are calculated by the 'stat' part of layers and can be accessed with \link } } +\section{Orientation}{ + +This geom treats each axis differently and, thus, can thus have two +orientations. Often the orientation is easy to deduce from a combination of +the given mappings and the types of positional scales in use. Thus, ggplot2 +will by default try to guess which orientation the layer should have. Under +rare circumstances, the orientation is ambiguous and guessing may fail. In +that case the orientation can be specified directly using the \code{orientation} +parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that +the geom should run along, \code{"x"} being the default orientation you would +expect for the geom. +} + \examples{ p <- ggplot(mpg, aes(class, hwy)) p + geom_boxplot() diff --git a/man/geom_contour.Rd b/man/geom_contour.Rd index c1b4461a15..b79b9f7cb7 100644 --- a/man/geom_contour.Rd +++ b/man/geom_contour.Rd @@ -73,30 +73,25 @@ stat_contour_filled( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 +to 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 @@ -106,42 +101,42 @@ give the stat as \code{"count"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -162,42 +157,42 @@ and returns breaks as output. A function can be created from a formula Overrides \code{binwidth} and \code{bins}. By default, this is a vector of length ten with \code{\link[=pretty]{pretty()}} breaks.} -\item{arrow}{Arrow specification, as created by \code{\link[grid:arrow]{grid::arrow()}}.} +\item{arrow}{Arrow specification. Can be created by \code{\link[grid:arrow]{grid::arrow()}} or \code{NULL} to not draw +an arrow.} -\item{arrow.fill}{fill colour to use for the arrow head (if closed). \code{NULL} -means use \code{colour} aesthetic.} +\item{arrow.fill}{Fill colour to use for closed arrowheads. \code{NULL} means use \code{colour} +aesthetic.} -\item{lineend}{Line end style (round, butt, square).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} -\item{linejoin}{Line join style (round, mitre, bevel).} +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} -\item{linemitre}{Line mitre limit (number greater than 1).} +\item{linemitre}{Line mitre limit, a number greater than 1.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \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{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: +\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 diff --git a/man/geom_count.Rd b/man/geom_count.Rd index 50493992df..1250870c5c 100644 --- a/man/geom_count.Rd +++ b/man/geom_count.Rd @@ -28,82 +28,76 @@ stat_sum( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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.} - -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} - -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} + +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} + +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Use to override the default connection between \code{geom_count()} and \code{stat_sum()}. For more information about overriding diff --git a/man/geom_density.Rd b/man/geom_density.Rd index 30ec7391c7..55d85c75cb 100644 --- a/man/geom_density.Rd +++ b/man/geom_density.Rd @@ -39,62 +39,57 @@ stat_density( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -104,37 +99,36 @@ lists which parameters it can accept. upper and lower lines, \code{"upper"}/\code{"lower"} draws the respective lines only. \code{"full"} draws a closed polygon around the area.} -\item{lineend}{Line end style (round, butt, square).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} -\item{linejoin}{Line join style (round, mitre, bevel).} +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} -\item{linemitre}{Line mitre limit (number greater than 1).} +\item{linemitre}{Line mitre limit, a number greater than 1.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Use to override the default connection between \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{orientation}{The orientation of the layer. The default (\code{NA}) -automatically determines the orientation from the aesthetic mapping. In the -rare event that this fails it can be given explicitly by setting \code{orientation} -to either \code{"x"} or \code{"y"}. See the \emph{Orientation} section for more detail.} +\item{orientation}{The orientation of the layer. The default (\code{NA}) automatically determines the +orientation from the aesthetic mapping. In the rare event that this fails it +can be given explicitly by setting \code{orientation} to either \code{"x"} or \code{"y"}. +See the \emph{Orientation} section for more detail.} \item{bw}{The smoothing bandwidth to be used. If numeric, the standard deviation of the smoothing kernel. @@ -170,11 +164,6 @@ Computes and draws kernel density estimate, which is a smoothed version of the histogram. This is a useful alternative to the histogram for continuous data that comes from an underlying smooth distribution. } -\section{Orientation}{ - -This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the \code{orientation} parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that the geom should run along, \code{"x"} being the default orientation you would expect for the geom. -} - \section{Computed variables}{ These are calculated by the 'stat' part of layers and can be accessed with \link[=aes_eval]{delayed evaluation}. @@ -188,6 +177,19 @@ These are calculated by the 'stat' part of layers and can be accessed with \link } } +\section{Orientation}{ + +This geom treats each axis differently and, thus, can thus have two +orientations. Often the orientation is easy to deduce from a combination of +the given mappings and the types of positional scales in use. Thus, ggplot2 +will by default try to guess which orientation the layer should have. Under +rare circumstances, the orientation is ambiguous and guessing may fail. In +that case the orientation can be specified directly using the \code{orientation} +parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that +the geom should run along, \code{"x"} being the default orientation you would +expect for the geom. +} + \examples{ ggplot(diamonds, aes(carat)) + geom_density() diff --git a/man/geom_density_2d.Rd b/man/geom_density_2d.Rd index 95b9cc3bac..3ec2860104 100644 --- a/man/geom_density_2d.Rd +++ b/man/geom_density_2d.Rd @@ -71,35 +71,30 @@ stat_density_2d_filled( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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"}. +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. }} @@ -125,27 +120,26 @@ ten with \code{\link[=pretty]{pretty()}} breaks.} by. Can be one of \code{"density"}, \code{"ndensity"}, or \code{"count"}. See the section on computed variables for details.} -\item{lineend}{Line end style (round, butt, square).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} -\item{linejoin}{Line join style (round, mitre, bevel).} +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} -\item{linemitre}{Line mitre limit (number greater than 1).} +\item{linemitre}{Line mitre limit, a number greater than 1.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Use to override the default connection between \code{geom_density_2d()} and \code{stat_density_2d()}. For more information at diff --git a/man/geom_dotplot.Rd b/man/geom_dotplot.Rd index ff8972de22..0ea33fbe82 100644 --- a/man/geom_dotplot.Rd +++ b/man/geom_dotplot.Rd @@ -27,62 +27,57 @@ geom_dotplot( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -124,21 +119,20 @@ for dodging.} \item{drop}{If TRUE, remove all bins with zero counts} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} - -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} - -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} + +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} + +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ In a dot plot, the width of a dot corresponds to the bin width diff --git a/man/geom_function.Rd b/man/geom_function.Rd index 379aa7a382..e40c9f7ce8 100644 --- a/man/geom_function.Rd +++ b/man/geom_function.Rd @@ -37,17 +37,15 @@ stat_function( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} \item{data}{Ignored by \code{stat_function()}, do not use.} -\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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\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 +to 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 @@ -57,78 +55,78 @@ give the stat as \code{"count"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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}{Arrow specification, as created by \code{\link[grid:arrow]{grid::arrow()}}.} +\item{arrow}{Arrow specification. Can be created by \code{\link[grid:arrow]{grid::arrow()}} or \code{NULL} to not draw +an arrow.} -\item{arrow.fill}{fill colour to use for the arrow head (if closed). \code{NULL} -means use \code{colour} aesthetic.} +\item{arrow.fill}{Fill colour to use for closed arrowheads. \code{NULL} means use \code{colour} +aesthetic.} -\item{lineend}{Line end style (round, butt, square).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} -\item{linejoin}{Line join style (round, mitre, bevel).} +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} -\item{linemitre}{Line mitre limit (number greater than 1).} +\item{linemitre}{Line mitre limit, a number greater than 1.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} -\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: +\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 diff --git a/man/geom_hex.Rd b/man/geom_hex.Rd index fce589bbff..b15fcd0b71 100644 --- a/man/geom_hex.Rd +++ b/man/geom_hex.Rd @@ -34,88 +34,82 @@ stat_bin_hex( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} -\item{linejoin}{Line join style (round, mitre, bevel).} +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} -\item{linemitre}{Line mitre limit (number greater than 1).} +\item{linemitre}{Line mitre limit, a number greater than 1.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Override the default connection between \code{geom_hex()} and \code{stat_bin_hex()}. For more information about overriding these connections, diff --git a/man/geom_histogram.Rd b/man/geom_histogram.Rd index b298a092a2..7a1c07ebd9 100644 --- a/man/geom_histogram.Rd +++ b/man/geom_histogram.Rd @@ -55,82 +55,76 @@ stat_bin( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{binwidth}{The width of the bins. Can be specified as a numeric value or as a function that takes x after scale transformation as input and @@ -146,14 +140,14 @@ bin width of a time variable is the number of seconds.} \item{bins}{Number of bins. Overridden by \code{binwidth}. Defaults to 30.} -\item{orientation}{The orientation of the layer. The default (\code{NA}) -automatically determines the orientation from the aesthetic mapping. In the -rare event that this fails it can be given explicitly by setting \code{orientation} -to either \code{"x"} or \code{"y"}. See the \emph{Orientation} section for more detail.} +\item{orientation}{The orientation of the layer. The default (\code{NA}) automatically determines the +orientation from the aesthetic mapping. In the rare event that this fails it +can be given explicitly by setting \code{orientation} to either \code{"x"} or \code{"y"}. +See the \emph{Orientation} section for more detail.} -\item{lineend}{Line end style (round, butt, square).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} -\item{linejoin}{Line join style (round, mitre, bevel).} +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} \item{geom, stat}{Use to override the default connection between \code{geom_histogram()}/\code{geom_freqpoly()} and \code{stat_bin()}. For more information @@ -215,11 +209,6 @@ In addition to \code{geom_histogram()}, you can create a histogram plot by using \code{scale_x_binned()} with \code{\link[=geom_bar]{geom_bar()}}. This method by default plots tick marks in between each bar. } -\section{Orientation}{ - -This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the \code{orientation} parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that the geom should run along, \code{"x"} being the default orientation you would expect for the geom. -} - \section{Aesthetics}{ \code{geom_histogram()} uses the same aesthetics as \code{\link[=geom_bar]{geom_bar()}}; @@ -245,6 +234,19 @@ These are calculated by the 'stat' part of layers and can be accessed with \link } } +\section{Orientation}{ + +This geom treats each axis differently and, thus, can thus have two +orientations. Often the orientation is easy to deduce from a combination of +the given mappings and the types of positional scales in use. Thus, ggplot2 +will by default try to guess which orientation the layer should have. Under +rare circumstances, the orientation is ambiguous and guessing may fail. In +that case the orientation can be specified directly using the \code{orientation} +parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that +the geom should run along, \code{"x"} being the default orientation you would +expect for the geom. +} + \examples{ ggplot(diamonds, aes(carat)) + geom_histogram() diff --git a/man/geom_jitter.Rd b/man/geom_jitter.Rd index 909192bca8..9f38a9c9ab 100644 --- a/man/geom_jitter.Rd +++ b/man/geom_jitter.Rd @@ -18,30 +18,25 @@ geom_jitter( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\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 +to 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 @@ -51,42 +46,42 @@ give the stat as \code{"count"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -101,21 +96,20 @@ jitter values will occupy 80\% of the implied bins. Categorical data is aligned on the integers, so a width or height of 0.5 will spread the data so it's not possible to see the distinction between the categories.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ The jitter geom is a convenient shortcut for diff --git a/man/geom_linerange.Rd b/man/geom_linerange.Rd index d064de5ebe..921777d5cf 100644 --- a/man/geom_linerange.Rd +++ b/man/geom_linerange.Rd @@ -73,30 +73,25 @@ geom_pointrange( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\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 +to 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 @@ -106,42 +101,42 @@ give the stat as \code{"count"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -157,28 +152,27 @@ data's aesthetics.} used to increase the size of the middle bar in \code{geom_crossbar()} and the middle point in \code{geom_pointrange()}.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{orientation}{The orientation of the layer. The default (\code{NA}) -automatically determines the orientation from the aesthetic mapping. In the -rare event that this fails it can be given explicitly by setting \code{orientation} -to either \code{"x"} or \code{"y"}. See the \emph{Orientation} section for more detail.} +\item{orientation}{The orientation of the layer. The default (\code{NA}) automatically determines the +orientation from the aesthetic mapping. In the rare event that this fails it +can be given explicitly by setting \code{orientation} to either \code{"x"} or \code{"y"}. +See the \emph{Orientation} section for more detail.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} -\item{lineend}{Line end style (round, butt, square).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} } \description{ Various ways of representing a vertical interval defined by \code{x}, @@ -190,7 +184,15 @@ Various ways of representing a vertical interval defined by \code{x}, } \section{Orientation}{ -This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the \code{orientation} parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that the geom should run along, \code{"x"} being the default orientation you would expect for the geom. +This geom treats each axis differently and, thus, can thus have two +orientations. Often the orientation is easy to deduce from a combination of +the given mappings and the types of positional scales in use. Thus, ggplot2 +will by default try to guess which orientation the layer should have. Under +rare circumstances, the orientation is ambiguous and guessing may fail. In +that case the orientation can be specified directly using the \code{orientation} +parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that +the geom should run along, \code{"x"} being the default orientation you would +expect for the geom. } \examples{ diff --git a/man/geom_map.Rd b/man/geom_map.Rd index 0f2081f451..ca94ad5d7d 100644 --- a/man/geom_map.Rd +++ b/man/geom_map.Rd @@ -16,30 +16,25 @@ geom_map( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 +to 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 @@ -49,29 +44,29 @@ give the stat as \code{"count"}. \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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -82,21 +77,20 @@ typically be created using \code{\link[=fortify]{fortify()}} on a spatial object It must contain columns \code{x} or \code{long}, \code{y} or \code{lat}, and \code{region} or \code{id}.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} - -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} - -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} + +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} + +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ Display polygons as a map. This is meant as annotation, so it does not diff --git a/man/geom_path.Rd b/man/geom_path.Rd index 6e22325673..4c237f91f4 100644 --- a/man/geom_path.Rd +++ b/man/geom_path.Rd @@ -58,30 +58,25 @@ geom_step( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\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 +to 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 @@ -91,78 +86,78 @@ give the stat as \code{"count"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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}{Arrow specification, as created by \code{\link[grid:arrow]{grid::arrow()}}.} +\item{arrow}{Arrow specification. Can be created by \code{\link[grid:arrow]{grid::arrow()}} or \code{NULL} to not draw +an arrow.} -\item{arrow.fill}{fill colour to use for the arrow head (if closed). \code{NULL} -means use \code{colour} aesthetic.} +\item{arrow.fill}{Fill colour to use for closed arrowheads. \code{NULL} means use \code{colour} +aesthetic.} -\item{lineend}{Line end style (round, butt, square).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} -\item{linejoin}{Line join style (round, mitre, bevel).} +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} -\item{linemitre}{Line mitre limit (number greater than 1).} +\item{linemitre}{Line mitre limit, a number greater than 1.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} -\item{orientation}{The orientation of the layer. The default (\code{NA}) -automatically determines the orientation from the aesthetic mapping. In the -rare event that this fails it can be given explicitly by setting \code{orientation} -to either \code{"x"} or \code{"y"}. See the \emph{Orientation} section for more detail.} +\item{orientation}{The orientation of the layer. The default (\code{NA}) automatically determines the +orientation from the aesthetic mapping. In the rare event that this fails it +can be given explicitly by setting \code{orientation} to either \code{"x"} or \code{"y"}. +See the \emph{Orientation} section for more detail.} \item{direction}{direction of stairs: 'vh' for vertical then horizontal, 'hv' for horizontal then vertical, or 'mid' for step half-way between @@ -179,11 +174,6 @@ connected together. An alternative parameterisation is \code{\link[=geom_segment]{geom_segment()}}, where each line corresponds to a single case which provides the start and end coordinates. } -\section{Orientation}{ - -This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the \code{orientation} parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that the geom should run along, \code{"x"} being the default orientation you would expect for the geom. -} - \section{Missing value handling}{ \code{geom_path()}, \code{geom_line()}, and \code{geom_step()} handle \code{NA} as follows: @@ -197,6 +187,19 @@ the \code{NA} is removed silently, without warning. } } +\section{Orientation}{ + +This geom treats each axis differently and, thus, can thus have two +orientations. Often the orientation is easy to deduce from a combination of +the given mappings and the types of positional scales in use. Thus, ggplot2 +will by default try to guess which orientation the layer should have. Under +rare circumstances, the orientation is ambiguous and guessing may fail. In +that case the orientation can be specified directly using the \code{orientation} +parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that +the geom should run along, \code{"x"} being the default orientation you would +expect for the geom. +} + \examples{ # geom_line() is suitable for time series ggplot(economics, aes(date, unemploy)) + geom_line() diff --git a/man/geom_point.Rd b/man/geom_point.Rd index 91bc77da3d..7175de4249 100644 --- a/man/geom_point.Rd +++ b/man/geom_point.Rd @@ -16,30 +16,25 @@ geom_point( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 +to 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 @@ -49,62 +44,61 @@ give the stat as \code{"count"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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.} - -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} - -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} + +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} + +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ The point geom is used to create scatterplots. The scatterplot is most diff --git a/man/geom_polygon.Rd b/man/geom_polygon.Rd index 9058d19259..56164e7f27 100644 --- a/man/geom_polygon.Rd +++ b/man/geom_polygon.Rd @@ -20,30 +20,25 @@ geom_polygon( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 +to 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 @@ -53,42 +48,42 @@ give the stat as \code{"count"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -99,27 +94,26 @@ 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{lineend}{Line end style (round, butt, square).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} -\item{linejoin}{Line join style (round, mitre, bevel).} +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} -\item{linemitre}{Line mitre limit (number greater than 1).} +\item{linemitre}{Line mitre limit, a number greater than 1.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ Polygons are very similar to paths (as drawn by \code{\link[=geom_path]{geom_path()}}) diff --git a/man/geom_qq.Rd b/man/geom_qq.Rd index b24151e50e..5eea2f4138 100644 --- a/man/geom_qq.Rd +++ b/man/geom_qq.Rd @@ -64,30 +64,25 @@ stat_qq( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 @@ -97,42 +92,42 @@ give the geom as \code{"point"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -149,21 +144,20 @@ defaults to \code{c(.25, .75)}.} \item{fullrange}{Should the q-q line span the full range of the plot, or just the data} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} - -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} - -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} + +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} + +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ \code{geom_qq()} and \code{stat_qq()} produce quantile-quantile plots. \code{geom_qq_line()} and diff --git a/man/geom_quantile.Rd b/man/geom_quantile.Rd index 94c7af770b..f26a4bcdc2 100644 --- a/man/geom_quantile.Rd +++ b/man/geom_quantile.Rd @@ -37,93 +37,88 @@ stat_quantile( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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}{Arrow specification, as created by \code{\link[grid:arrow]{grid::arrow()}}.} +\item{arrow}{Arrow specification. Can be created by \code{\link[grid:arrow]{grid::arrow()}} or \code{NULL} to not draw +an arrow.} -\item{arrow.fill}{fill colour to use for the arrow head (if closed). \code{NULL} -means use \code{colour} aesthetic.} +\item{arrow.fill}{Fill colour to use for closed arrowheads. \code{NULL} means use \code{colour} +aesthetic.} -\item{lineend}{Line end style (round, butt, square).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} -\item{linejoin}{Line join style (round, mitre, bevel).} +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} -\item{linemitre}{Line mitre limit (number greater than 1).} +\item{linemitre}{Line mitre limit, a number greater than 1.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Use to override the default connection between \code{geom_quantile()} and \code{stat_quantile()}. For more information about diff --git a/man/geom_ribbon.Rd b/man/geom_ribbon.Rd index 9e98df0e4e..cd5605195f 100644 --- a/man/geom_ribbon.Rd +++ b/man/geom_ribbon.Rd @@ -50,30 +50,25 @@ stat_align( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 +to 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 @@ -83,82 +78,81 @@ give the stat as \code{"count"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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{orientation}{The orientation of the layer. The default (\code{NA}) -automatically determines the orientation from the aesthetic mapping. In the -rare event that this fails it can be given explicitly by setting \code{orientation} -to either \code{"x"} or \code{"y"}. See the \emph{Orientation} section for more detail.} +\item{orientation}{The orientation of the layer. The default (\code{NA}) automatically determines the +orientation from the aesthetic mapping. In the rare event that this fails it +can be given explicitly by setting \code{orientation} to either \code{"x"} or \code{"y"}. +See the \emph{Orientation} section for more detail.} -\item{lineend}{Line end style (round, butt, square).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} -\item{linejoin}{Line join style (round, mitre, bevel).} +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} -\item{linemitre}{Line mitre limit (number greater than 1).} +\item{linemitre}{Line mitre limit, a number greater than 1.} \item{outline.type}{Type of the outline of the area; \code{"both"} draws both the upper and lower lines, \code{"upper"}/\code{"lower"} draws the respective lines only. \code{"full"} draws a closed polygon around the area.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} - -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} - -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} - -\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: +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} + +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} + +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} + +\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 @@ -187,7 +181,15 @@ be used instead. } \section{Orientation}{ -This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the \code{orientation} parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that the geom should run along, \code{"x"} being the default orientation you would expect for the geom. +This geom treats each axis differently and, thus, can thus have two +orientations. Often the orientation is easy to deduce from a combination of +the given mappings and the types of positional scales in use. Thus, ggplot2 +will by default try to guess which orientation the layer should have. Under +rare circumstances, the orientation is ambiguous and guessing may fail. In +that case the orientation can be specified directly using the \code{orientation} +parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that +the geom should run along, \code{"x"} being the default orientation you would +expect for the geom. } \examples{ diff --git a/man/geom_rug.Rd b/man/geom_rug.Rd index 2efd6e4796..c8424c8399 100644 --- a/man/geom_rug.Rd +++ b/man/geom_rug.Rd @@ -20,30 +20,25 @@ geom_rug( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 +to 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 @@ -53,48 +48,48 @@ give the stat as \code{"count"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} \item{sides}{A string that controls which sides of the plot the rugs appear on. It can be set to a string containing any of \code{"trbl"}, for top, right, @@ -104,21 +99,20 @@ bottom, and left.} \item{length}{A \code{\link[grid:unit]{grid::unit()}} object that sets the length of the rug lines. Use scale expansion to avoid overplotting of data.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} - -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} - -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} + +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} + +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ A rug plot is a compact visualisation designed to supplement a 2d display diff --git a/man/geom_segment.Rd b/man/geom_segment.Rd index 00fbfeca85..3c63aa6ef4 100644 --- a/man/geom_segment.Rd +++ b/man/geom_segment.Rd @@ -38,30 +38,25 @@ geom_curve( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 +to 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 @@ -71,71 +66,71 @@ give the stat as \code{"count"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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()}}.} +\item{arrow}{Arrow specification. Can be created by \code{\link[grid:arrow]{grid::arrow()}} or \code{NULL} to not draw +an arrow.} -\item{arrow.fill}{fill colour to use for the arrow head (if closed). \code{NULL} -means use \code{colour} aesthetic.} +\item{arrow.fill}{Fill colour to use for closed arrowheads. \code{NULL} means use \code{colour} +aesthetic.} -\item{lineend}{Line end style (round, butt, square).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} -\item{linejoin}{Line join style (round, mitre, bevel).} +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{curvature}{A numeric value giving the amount of curvature. Negative values produce left-hand curves, positive values diff --git a/man/geom_smooth.Rd b/man/geom_smooth.Rd index 2ce488a9d1..e6b31c7a8a 100644 --- a/man/geom_smooth.Rd +++ b/man/geom_smooth.Rd @@ -42,62 +42,57 @@ stat_smooth( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -128,26 +123,25 @@ observations and \code{formula = y ~ s(x, bs = "cs")} otherwise.} \item{se}{Display confidence band around smooth? (\code{TRUE} by default, see \code{level} to control.)} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{orientation}{The orientation of the layer. The default (\code{NA}) -automatically determines the orientation from the aesthetic mapping. In the -rare event that this fails it can be given explicitly by setting \code{orientation} -to either \code{"x"} or \code{"y"}. See the \emph{Orientation} section for more detail.} +\item{orientation}{The orientation of the layer. The default (\code{NA}) automatically determines the +orientation from the aesthetic mapping. In the rare event that this fails it +can be given explicitly by setting \code{orientation} to either \code{"x"} or \code{"y"}. +See the \emph{Orientation} section for more detail.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Use to override the default connection between \code{geom_smooth()} and \code{stat_smooth()}. For more information about overriding @@ -189,11 +183,6 @@ exceptions are \code{loess()}, which uses a t-based approximation, and \code{glm()}, where the normal confidence band is constructed on the link scale and then back-transformed to the response scale. } -\section{Orientation}{ - -This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the \code{orientation} parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that the geom should run along, \code{"x"} being the default orientation you would expect for the geom. -} - \section{Computed variables}{ These are calculated by the 'stat' part of layers and can be accessed with \link[=aes_eval]{delayed evaluation}. \code{stat_smooth()} provides the following variables, some of which depend on the orientation: @@ -205,6 +194,19 @@ These are calculated by the 'stat' part of layers and can be accessed with \link } } +\section{Orientation}{ + +This geom treats each axis differently and, thus, can thus have two +orientations. Often the orientation is easy to deduce from a combination of +the given mappings and the types of positional scales in use. Thus, ggplot2 +will by default try to guess which orientation the layer should have. Under +rare circumstances, the orientation is ambiguous and guessing may fail. In +that case the orientation can be specified directly using the \code{orientation} +parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that +the geom should run along, \code{"x"} being the default orientation you would +expect for the geom. +} + \examples{ ggplot(mpg, aes(displ, hwy)) + geom_point() + diff --git a/man/geom_spoke.Rd b/man/geom_spoke.Rd index 3afed67cca..721766a6f6 100644 --- a/man/geom_spoke.Rd +++ b/man/geom_spoke.Rd @@ -21,30 +21,25 @@ geom_spoke( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 +to 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 @@ -54,71 +49,71 @@ give the stat as \code{"count"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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()}}.} +\item{arrow}{Arrow specification. Can be created by \code{\link[grid:arrow]{grid::arrow()}} or \code{NULL} to not draw +an arrow.} -\item{arrow.fill}{fill colour to use for the arrow head (if closed). \code{NULL} -means use \code{colour} aesthetic.} +\item{arrow.fill}{Fill colour to use for closed arrowheads. \code{NULL} means use \code{colour} +aesthetic.} -\item{lineend}{Line end style (round, butt, square).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} -\item{linejoin}{Line join style (round, mitre, bevel).} +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ This is a polar parameterisation of \code{\link[=geom_segment]{geom_segment()}}. It is diff --git a/man/geom_text.Rd b/man/geom_text.Rd index 7362a52ca4..069aba43d3 100644 --- a/man/geom_text.Rd +++ b/man/geom_text.Rd @@ -40,30 +40,25 @@ geom_text( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 +to 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 @@ -73,42 +68,42 @@ give the stat as \code{"count"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -136,21 +131,20 @@ alias for \code{text.colour}.} (\code{"mm"}, default), points (\code{"pt"}), centimetres (\code{"cm"}), inches (\code{"in"}), or picas (\code{"pc"}).} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} - -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} - -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} + +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} + +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{check_overlap}{If \code{TRUE}, text that overlaps previous text in the same layer will not be plotted. \code{check_overlap} happens at draw time and in diff --git a/man/geom_tile.Rd b/man/geom_tile.Rd index 3305e7397f..972a98ff31 100644 --- a/man/geom_tile.Rd +++ b/man/geom_tile.Rd @@ -47,30 +47,25 @@ geom_tile( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 +to 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 @@ -80,42 +75,42 @@ give the stat as \code{"count"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -128,25 +123,24 @@ lists which parameters it can accept. justification value should be a number between 0 and 1. Defaults to 0.5 for both, centering each pixel over its data location.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} -\item{lineend}{Line end style (round, butt, square).} +\item{lineend}{Line end style, one of \code{"round"}, \code{"butt"} or \code{"square"}.} -\item{linejoin}{Line join style (round, mitre, bevel).} +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} } \description{ \code{geom_rect()} and \code{geom_tile()} do the same thing, but are diff --git a/man/geom_violin.Rd b/man/geom_violin.Rd index 571329a598..cba7d21064 100644 --- a/man/geom_violin.Rd +++ b/man/geom_violin.Rd @@ -46,62 +46,57 @@ stat_ydensity( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -128,26 +123,25 @@ specification of drawing quantiles.} the tails). If "count", areas are scaled proportionally to the number of observations. If "width", all violins have the same maximum width.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{orientation}{The orientation of the layer. The default (\code{NA}) -automatically determines the orientation from the aesthetic mapping. In the -rare event that this fails it can be given explicitly by setting \code{orientation} -to either \code{"x"} or \code{"y"}. See the \emph{Orientation} section for more detail.} +\item{orientation}{The orientation of the layer. The default (\code{NA}) automatically determines the +orientation from the aesthetic mapping. In the rare event that this fails it +can be given explicitly by setting \code{orientation} to either \code{"x"} or \code{"y"}. +See the \emph{Orientation} section for more detail.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Use to override the default connection between \code{geom_violin()} and \code{stat_ydensity()}. For more information about @@ -182,11 +176,6 @@ blend of \code{\link[=geom_boxplot]{geom_boxplot()}} and \code{\link[=geom_densi violin plot is a mirrored density plot displayed in the same way as a boxplot. } -\section{Orientation}{ - -This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the \code{orientation} parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that the geom should run along, \code{"x"} being the default orientation you would expect for the geom. -} - \section{Computed variables}{ These are calculated by the 'stat' part of layers and can be accessed with \link[=aes_eval]{delayed evaluation}. @@ -201,6 +190,19 @@ These are calculated by the 'stat' part of layers and can be accessed with \link } } +\section{Orientation}{ + +This geom treats each axis differently and, thus, can thus have two +orientations. Often the orientation is easy to deduce from a combination of +the given mappings and the types of positional scales in use. Thus, ggplot2 +will by default try to guess which orientation the layer should have. Under +rare circumstances, the orientation is ambiguous and guessing may fail. In +that case the orientation can be specified directly using the \code{orientation} +parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that +the geom should run along, \code{"x"} being the default orientation you would +expect for the geom. +} + \examples{ p <- ggplot(mtcars, aes(factor(cyl), mpg)) p + geom_violin() diff --git a/man/ggsf.Rd b/man/ggsf.Rd index 3343c6bbdc..15e6e6c089 100644 --- a/man/ggsf.Rd +++ b/man/ggsf.Rd @@ -185,30 +185,25 @@ legend, the plot title, or the plot margins.} their respective directions. \code{"xy"} can be used to reverse both directions.} -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 +to 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 @@ -218,21 +213,21 @@ give the stat as \code{"count"}. \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: +\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"}. +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.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} \item{show.legend}{logical. Should this layer be included in the legends? \code{NA}, the default, includes if any aesthetics are mapped. @@ -241,34 +236,34 @@ a warning. If \code{TRUE}, missing values are silently removed.} You can also set this to one of "polygon", "line", and "point" to override the default legend.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} -\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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -304,10 +299,10 @@ 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 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: +\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 diff --git a/man/layer.Rd b/man/layer.Rd index f4b9bfb13f..307b0e419d 100644 --- a/man/layer.Rd +++ b/man/layer.Rd @@ -21,10 +21,10 @@ layer( ) } \arguments{ -\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: +\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 @@ -34,10 +34,10 @@ give the geom as \code{"point"}. \link[=layer_geoms]{layer geom} documentation. }} -\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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\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 +to 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 @@ -47,57 +47,51 @@ give the stat as \code{"count"}. \link[=layer_stats]{layer stat} documentation. }} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\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: +\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"}. +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}.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{check.aes, check.param}{If \code{TRUE}, the default, will check that supplied parameters and aesthetics are understood by the \code{geom} or \code{stat}. Use \code{FALSE} to suppress the checks.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} \item{key_glyph}{A legend key drawing function or a string providing the function name minus the \code{draw_key_} prefix. See \link{draw_key} for details.} diff --git a/man/layer_sf.Rd b/man/layer_sf.Rd index e9a11604e8..13cd8f402c 100644 --- a/man/layer_sf.Rd +++ b/man/layer_sf.Rd @@ -18,10 +18,10 @@ layer_sf( ) } \arguments{ -\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: +\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 @@ -31,10 +31,10 @@ give the geom as \code{"point"}. \link[=layer_geoms]{layer geom} documentation. }} -\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 to override the default coupling between geoms and -stats. The \code{stat} argument accepts the following: +\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 +to 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 @@ -44,57 +44,51 @@ give the stat as \code{"count"}. \link[=layer_stats]{layer stat} documentation. }} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\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: +\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"}. +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}.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{check.aes, check.param}{If \code{TRUE}, the default, will check that supplied parameters and aesthetics are understood by the \code{geom} or \code{stat}. Use \code{FALSE} to suppress the checks.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} } \description{ The \code{layer_sf()} function is a variant of \code{\link[=layer]{layer()}} meant to be used by diff --git a/man/shared_layer_parameters.Rd b/man/shared_layer_parameters.Rd new file mode 100644 index 0000000000..001af03c19 --- /dev/null +++ b/man/shared_layer_parameters.Rd @@ -0,0 +1,137 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/layer.R +\name{shared_layer_parameters} +\title{Shared layer parameters} +\arguments{ +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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. When using +a \verb{geom_*()} function to construct a layer, the \code{stat} argument can be used +to 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.} + +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} + +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} + +\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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. +\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, one of \code{"round"}, \code{"butt"} or \code{"square"}.} + +\item{linejoin}{Line join style, one of \code{"round"}, \code{"mitre"} or \code{"bevel"}.} + +\item{linemitre}{Line mitre limit, a number greater than 1.} + +\item{arrow}{Arrow specification. Can be created by \code{\link[grid:arrow]{grid::arrow()}} or \code{NULL} to not draw +an arrow.} + +\item{arrow.fill}{Fill colour to use for closed arrowheads. \code{NULL} means use \code{colour} +aesthetic.} + +\item{orientation}{The orientation of the layer. The default (\code{NA}) automatically determines the +orientation from the aesthetic mapping. In the rare event that this fails it +can be given explicitly by setting \code{orientation} to either \code{"x"} or \code{"y"}. +See the \emph{Orientation} section for more detail.} +} +\description{ +This is a central place for describing typical layer parameters. +It prevents cluttered definitions all over the place. +} +\section{Orientation}{ + +This geom treats each axis differently and, thus, can thus have two +orientations. Often the orientation is easy to deduce from a combination of +the given mappings and the types of positional scales in use. Thus, ggplot2 +will by default try to guess which orientation the layer should have. Under +rare circumstances, the orientation is ambiguous and guessing may fail. In +that case the orientation can be specified directly using the \code{orientation} +parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that +the geom should run along, \code{"x"} being the default orientation you would +expect for the geom. +} + +\keyword{internal} diff --git a/man/stat_connect.Rd b/man/stat_connect.Rd index 12ad9a608a..b8e78c0d81 100644 --- a/man/stat_connect.Rd +++ b/man/stat_connect.Rd @@ -17,30 +17,25 @@ stat_connect( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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 @@ -50,42 +45,42 @@ give the geom as \code{"point"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -107,21 +102,20 @@ at location (0, 0) and point B at location (1, 1). At least one of these two points is expected to be included in the coordinates. }} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ Connect successive points with lines of different shapes. diff --git a/man/stat_ecdf.Rd b/man/stat_ecdf.Rd index 3380ac1cc7..8073cf0770 100644 --- a/man/stat_ecdf.Rd +++ b/man/stat_ecdf.Rd @@ -18,30 +18,25 @@ stat_ecdf( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 @@ -51,42 +46,42 @@ give the geom as \code{"point"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -101,18 +96,17 @@ and (Inf, 1)} \item{na.rm}{If \code{FALSE} (the default), removes missing values with a warning. If \code{TRUE} silently removes missing values.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} - -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} + +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ The empirical cumulative distribution function (ECDF) provides an alternative diff --git a/man/stat_ellipse.Rd b/man/stat_ellipse.Rd index 0d3014b344..8e0651be63 100644 --- a/man/stat_ellipse.Rd +++ b/man/stat_ellipse.Rd @@ -19,30 +19,25 @@ stat_ellipse( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 @@ -52,42 +47,42 @@ give the geom as \code{"point"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -105,21 +100,20 @@ or, if \code{type="euclid"}, the radius of the circle to be drawn.} \item{segments}{The number of segments to be used in drawing the ellipse.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} - -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} - -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} + +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} + +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ The method for calculating the ellipses has been modified from diff --git a/man/stat_identity.Rd b/man/stat_identity.Rd index 9c1640e2b4..e73e256df6 100644 --- a/man/stat_identity.Rd +++ b/man/stat_identity.Rd @@ -16,30 +16,25 @@ stat_identity( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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 @@ -49,62 +44,61 @@ give the geom as \code{"point"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ The identity statistic leaves the data unchanged. diff --git a/man/stat_manual.Rd b/man/stat_manual.Rd index 5c00a0ea89..2689626479 100644 --- a/man/stat_manual.Rd +++ b/man/stat_manual.Rd @@ -18,30 +18,25 @@ stat_manual( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 @@ -51,42 +46,42 @@ give the geom as \code{"point"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -98,21 +93,20 @@ the data unchanged.} \item{args}{A list of arguments to pass to the function given in \code{fun}.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} - -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} - -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} + +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} + +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ \code{stat_manual()} takes a function that computes a data transformation for diff --git a/man/stat_sf_coordinates.Rd b/man/stat_sf_coordinates.Rd index 3173fa8e86..3b4931b62d 100644 --- a/man/stat_sf_coordinates.Rd +++ b/man/stat_sf_coordinates.Rd @@ -19,30 +19,25 @@ stat_sf_coordinates( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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 @@ -52,34 +47,33 @@ give the geom as \code{"point"}. \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: +\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"}. +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.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{fun.geometry}{A function that takes a \code{sfc} object and returns a \code{sfc_POINT} with the same length as the input. If \code{NULL}, \code{function(x) sf::st_point_on_surface(sf::st_zm(x))} @@ -87,29 +81,29 @@ 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()}}'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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. diff --git a/man/stat_summary.Rd b/man/stat_summary.Rd index ad45350819..67a8e592c4 100644 --- a/man/stat_summary.Rd +++ b/man/stat_summary.Rd @@ -49,30 +49,25 @@ stat_summary( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 @@ -82,42 +77,42 @@ give the geom as \code{"point"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -149,26 +144,25 @@ bin width of a time variable is the number of seconds.} \item{breaks}{Alternatively, you can supply a numeric vector giving the bin boundaries. Overrides \code{binwidth} and \code{bins}.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{orientation}{The orientation of the layer. The default (\code{NA}) -automatically determines the orientation from the aesthetic mapping. In the -rare event that this fails it can be given explicitly by setting \code{orientation} -to either \code{"x"} or \code{"y"}. See the \emph{Orientation} section for more detail.} +\item{orientation}{The orientation of the layer. The default (\code{NA}) automatically determines the +orientation from the aesthetic mapping. In the rare event that this fails it +can be given explicitly by setting \code{orientation} to either \code{"x"} or \code{"y"}. +See the \emph{Orientation} section for more detail.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} \item{fun.ymin, fun.y, fun.ymax}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use the versions specified above instead.} @@ -179,11 +173,6 @@ operates on binned \code{x} or \code{y}. They are more flexible versions of \code{\link[=stat_bin]{stat_bin()}}: instead of just counting, they can compute any aggregate. } -\section{Orientation}{ - -This geom treats each axis differently and, thus, can thus have two orientations. Often the orientation is easy to deduce from a combination of the given mappings and the types of positional scales in use. Thus, ggplot2 will by default try to guess which orientation the layer should have. Under rare circumstances, the orientation is ambiguous and guessing may fail. In that case the orientation can be specified directly using the \code{orientation} parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that the geom should run along, \code{"x"} being the default orientation you would expect for the geom. -} - \section{Summary functions}{ You can either supply summary functions individually (\code{fun}, @@ -213,6 +202,19 @@ If no aggregation functions are supplied, will default to \code{\link[=mean_se]{mean_se()}}. } +\section{Orientation}{ + +This geom treats each axis differently and, thus, can thus have two +orientations. Often the orientation is easy to deduce from a combination of +the given mappings and the types of positional scales in use. Thus, ggplot2 +will by default try to guess which orientation the layer should have. Under +rare circumstances, the orientation is ambiguous and guessing may fail. In +that case the orientation can be specified directly using the \code{orientation} +parameter, which can be either \code{"x"} or \code{"y"}. The value gives the axis that +the geom should run along, \code{"x"} being the default orientation you would +expect for the geom. +} + \examples{ d <- ggplot(mtcars, aes(cyl, mpg)) + geom_point() d + stat_summary(fun.data = "mean_cl_boot", colour = "red", linewidth = 2, size = 3) diff --git a/man/stat_summary_2d.Rd b/man/stat_summary_2d.Rd index 41517514cc..b21bf0aa1a 100644 --- a/man/stat_summary_2d.Rd +++ b/man/stat_summary_2d.Rd @@ -43,30 +43,25 @@ stat_summary_hex( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} - -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{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: +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} + +\item{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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 @@ -76,42 +71,42 @@ give the geom as \code{"point"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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. @@ -154,21 +149,20 @@ if \code{0} is outside the range of the data. Alternatively, this same alignment can be specified with \code{binwidth = 1} and \code{boundary = 0.5}, even if \code{0.5} is outside the range of the data.} -\item{na.rm}{If \code{FALSE}, the default, missing values are removed with -a warning. If \code{TRUE}, missing values are silently removed.} - -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} - -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} + +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} + +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ \code{stat_summary_2d()} is a 2d variation of \code{\link[=stat_summary]{stat_summary()}}. diff --git a/man/stat_unique.Rd b/man/stat_unique.Rd index 62fa19b03e..02e354aded 100644 --- a/man/stat_unique.Rd +++ b/man/stat_unique.Rd @@ -16,30 +16,25 @@ stat_unique( ) } \arguments{ -\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and -\code{inherit.aes = TRUE} (the default), it is combined with the default mapping -at the top level of the plot. You must supply \code{mapping} if there is no plot -mapping.} +\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level +of the plot. You must supply \code{mapping} if there is no plot mapping.} -\item{data}{The data to be displayed in this layer. There are three -options: - -If \code{NULL}, the default, the data is inherited from the plot -data as specified in the call to \code{\link[=ggplot]{ggplot()}}. - -A \code{data.frame}, or other object, will override the plot -data. All objects will be fortified to produce a data frame. See -\code{\link[=fortify]{fortify()}} for which variables will be created. - -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{data}{The data to be displayed in this layer. There are three options: +\itemize{ +\item \code{NULL} (default): the data is inherited from the plot data as specified +in the call to \code{\link[=ggplot]{ggplot()}}. +\item A \code{data.frame}, or other object, will override the plot data. All objects +will be fortified to produce a data frame. See \code{\link[=fortify]{fortify()}} for which +variables will be created. +\item 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{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: +\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 @@ -49,62 +44,61 @@ give the geom as \code{"point"}. \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: +\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"}. +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. +\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}. Please note that while passing -unmapped aesthetics as vectors is technically possible, the order and -required length is not guaranteed to be parallel to the input data. +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}. Please note that while passing unmapped +aesthetics as vectors is technically possible, the order and required +length is not guaranteed to be parallel to the input data. \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 +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. +\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.} +\item{na.rm}{If \code{FALSE}, the default, missing values are removed with a warning. If +\code{TRUE}, missing values are silently removed.} -\item{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. -It can also be a named logical vector to finely select the aesthetics to -display. To include legend keys for all levels, even -when no data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, -but unobserved levels are omitted.} +\item{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. It can also be a named logical vector to finely select the +aesthetics to display. To include legend keys for all levels, even when no +data exists, use \code{TRUE}. If \code{NA}, all levels are shown in legend, but +unobserved levels are omitted.} -\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, -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[=annotation_borders]{annotation_borders()}}.} +\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, 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[=annotation_borders]{annotation_borders()}}.} } \description{ Remove duplicates