|
| 1 | +# Shared parameters ------------------------------------------------------- |
| 2 | + |
| 3 | +#' @name shared_layer_parameters |
| 4 | +#' @title Shared layer parameters |
| 5 | +#' @description |
| 6 | +#' This is a central place for describing typical layer parameters. |
| 7 | +#' It prevents cluttered definitions all over the place. |
| 8 | +#' |
| 9 | +#' @param mapping |
| 10 | +#' Set of aesthetic mappings created by [aes()]. If specified and `inherit.aes = |
| 11 | +#' TRUE` (the default), it is combined with the default mapping at the top level |
| 12 | +#' of the plot. You must supply `mapping` if there is no plot mapping. |
| 13 | +#' |
| 14 | +#' @param data |
| 15 | +#' The data to be displayed in this layer. There are three options: |
| 16 | +#' * `NULL` (default): the data is inherited from the plot data as specified |
| 17 | +#' in the call to [ggplot()]. |
| 18 | +#' * A `data.frame`, or other object, will override the plot data. All objects |
| 19 | +#' will be fortified to produce a data frame. See [fortify()] for which |
| 20 | +#' variables will be created. |
| 21 | +#' * A `function` will be called with a single argument, the plot data. The return |
| 22 | +#' value must be a `data.frame`, and will be used as the layer data. A |
| 23 | +#' `function` can be created from a `formula` (e.g. `~ head(.x, 10)`). |
| 24 | +#' |
| 25 | +#' @param geom |
| 26 | +#' The geometric object to use to display the data for this layer. When using a |
| 27 | +#' `stat_*()` function to construct a layer, the `geom` argument can be used to |
| 28 | +#' override the default coupling between stats and geoms. The `geom` argument |
| 29 | +#' accepts the following: |
| 30 | +#' * A `Geom` ggproto subclass, for example `GeomPoint`. |
| 31 | +#' * A string naming the geom. To give the geom as a string, strip the |
| 32 | +#' function name of the `geom_` prefix. For example, to use `geom_point()`, |
| 33 | +#' give the geom as `"point"`. |
| 34 | +#' * For more information and other ways to specify the geom, see the |
| 35 | +#' [layer geom][layer_geoms] documentation. |
| 36 | +#' |
| 37 | +#' @param stat |
| 38 | +#' The statistical transformation to use on the data for this layer. When using |
| 39 | +#' a `geom_*()` function to construct a layer, the `stat` argument can be used |
| 40 | +#' to override the default coupling between geoms and stats. The `stat` argument |
| 41 | +#' accepts the following: |
| 42 | +#' * A `Stat` ggproto subclass, for example `StatCount`. |
| 43 | +#' * A string naming the stat. To give the stat as a string, strip the |
| 44 | +#' function name of the `stat_` prefix. For example, to use `stat_count()`, |
| 45 | +#' give the stat as `"count"`. |
| 46 | +#' * For more information and other ways to specify the stat, see the |
| 47 | +#' [layer stat][layer_stats] documentation. |
| 48 | +#' |
| 49 | +#' @param position |
| 50 | +#' A position adjustment to use on the data for this layer. This can be used in |
| 51 | +#' various ways, including to prevent overplotting and improving the display. |
| 52 | +#' The `position` argument accepts the following: |
| 53 | +#' * The result of calling a position function, such as `position_jitter()`. |
| 54 | +#' This method allows for passing extra arguments to the position. |
| 55 | +#' * A string naming the position adjustment. To give the position as a |
| 56 | +#' string, strip the function name of the `position_` prefix. For example, to |
| 57 | +#' use `position_jitter()`, give the position as `"jitter"`. |
| 58 | +#' * For more information and other ways to specify the position, see the |
| 59 | +#' [layer position][layer_positions] documentation. |
| 60 | +#' |
| 61 | +#' @param na.rm |
| 62 | +#' If `FALSE`, the default, missing values are removed with a warning. If |
| 63 | +#' `TRUE`, missing values are silently removed. |
| 64 | +#' |
| 65 | +#' @param show.legend |
| 66 | +#' Logical. Should this layer be included in the legends? `NA`, the default, |
| 67 | +#' includes if any aesthetics are mapped. `FALSE` never includes, and `TRUE` |
| 68 | +#' always includes. It can also be a named logical vector to finely select the |
| 69 | +#' aesthetics to display. To include legend keys for all levels, even when no |
| 70 | +#' data exists, use `TRUE`. If `NA`, all levels are shown in legend, but |
| 71 | +#' unobserved levels are omitted. |
| 72 | +#' |
| 73 | +#' @param inherit.aes |
| 74 | +#' If `FALSE`, overrides the default aesthetics, rather than combining with |
| 75 | +#' them. This is most useful for helper functions that define both data and |
| 76 | +#' aesthetics and shouldn't inherit behaviour from the default plot |
| 77 | +#' specification, e.g. [annotation_borders()]. |
| 78 | +#' |
| 79 | +#' @param ... |
| 80 | +#' Other arguments passed on to [layer()]'s `params` argument. These arguments |
| 81 | +#' broadly fall into one of 4 categories below. Notably, further arguments to |
| 82 | +#' the `position` argument, or aesthetics that are required can |
| 83 | +#' *not* be passed through `...`. Unknown arguments that are not part of the 4 |
| 84 | +#' categories below are ignored. |
| 85 | +#' * Static aesthetics that are not mapped to a scale, but are at a fixed |
| 86 | +#' value and apply to the layer as a whole. For example, `colour = "red"` or |
| 87 | +#' `linewidth = 3`. The geom's documentation has an **Aesthetics** section |
| 88 | +#' that lists the available options. The 'required' aesthetics cannot be |
| 89 | +#' passed on to the `params`. Please note that while passing unmapped |
| 90 | +#' aesthetics as vectors is technically possible, the order and required |
| 91 | +#' length is not guaranteed to be parallel to the input data. |
| 92 | +#' * When constructing a layer using |
| 93 | +#' a `stat_*()` function, the `...` argument can be used to pass on parameters |
| 94 | +#' to the `geom` part of the layer. An example of this is |
| 95 | +#' `stat_density(geom = "area", outline.type = "both")`. The geom's |
| 96 | +#' documentation lists which parameters it can accept. |
| 97 | +#' * Inversely, when constructing a layer using a |
| 98 | +#' `geom_*()` function, the `...` argument can be used to pass on parameters |
| 99 | +#' to the `stat` part of the layer. An example of this is |
| 100 | +#' `geom_area(stat = "density", adjust = 0.5)`. The stat's documentation lists |
| 101 | +#' which parameters it can accept. |
| 102 | +#' * The `key_glyph` argument of [`layer()`] may also be passed on through |
| 103 | +#' `...`. This can be one of the functions described as |
| 104 | +#' [key glyphs][draw_key], to change the display of the layer in the legend. |
| 105 | +#' |
| 106 | +#' @param lineend |
| 107 | +#' Line end style, one of `"round"`, `"butt"` or `"square"`. |
| 108 | +#' |
| 109 | +#' @param linejoin |
| 110 | +#' Line join style, one of `"round"`, `"mitre"` or `"bevel"`. |
| 111 | +#' |
| 112 | +#' @param linemitre |
| 113 | +#' Line mitre limit, a number greater than 1. |
| 114 | +#' |
| 115 | +#' @param arrow |
| 116 | +#' Arrow specification. Can be created by [grid::arrow()] or `NULL` to not draw |
| 117 | +#' an arrow. |
| 118 | +#' |
| 119 | +#' @param arrow.fill |
| 120 | +#' Fill colour to use for closed arrowheads. `NULL` means use `colour` |
| 121 | +#' aesthetic. |
| 122 | +#' |
| 123 | +#' @param orientation |
| 124 | +#' The orientation of the layer. The default (`NA`) automatically determines the |
| 125 | +#' orientation from the aesthetic mapping. In the rare event that this fails it |
| 126 | +#' can be given explicitly by setting `orientation` to either `"x"` or `"y"`. |
| 127 | +#' See the *Orientation* section for more detail. |
| 128 | +#' |
| 129 | +#' @section Orientation: |
| 130 | +#' This geom treats each axis differently and, thus, can have two |
| 131 | +#' orientations. Often the orientation is easy to deduce from a combination of |
| 132 | +#' the given mappings and the types of positional scales in use. Thus, ggplot2 |
| 133 | +#' will by default try to guess which orientation the layer should have. Under |
| 134 | +#' rare circumstances, the orientation is ambiguous and guessing may fail. In |
| 135 | +#' that case the orientation can be specified directly using the `orientation` |
| 136 | +#' parameter, which can be either `"x"` or `"y"`. The value gives the axis that |
| 137 | +#' the geom should run along, `"x"` being the default orientation you would |
| 138 | +#' expect for the geom. |
| 139 | +#' |
| 140 | +#' @keywords internal |
| 141 | +#' @aliases NULL |
| 142 | +NULL |
| 143 | + |
1 | 144 | # Geoms ------------------------------------------------------------------- |
2 | 145 |
|
3 | 146 | #' @title |
|
0 commit comments