R/shared-docs.R

In openair: Tools for the Analysis of Air Pollution Data

#' @name shared_openair_params
#' @title Shared openair parameters
#' @description This is a central place for describing common shared parameters.
#'   This ensures consistency across `openair`
#'
#' @param type Character string(s) defining how data should be split/conditioned
#'   before plotting. `"default"` produces a single panel using the entire
#'   dataset. Any other options will split the plot into different panels - a
#'   roughly square grid of panels if one `type` is given, or a 2D matrix of
#'   panels if two `types` are given. `type` is always passed to [cutData()],
#'   and can therefore be any of:
#'
#'   - A built-in type defined in [cutData()] (e.g., `"season"`, `"year"`,
#'   `"weekday"`, etc.). For example, `type = "season"` will split the plot into
#'   four panels, one for each season.
#'
#'   - The name of a numeric column in `mydata`, which will be split into
#'   `n.levels` quantiles (defaulting to 4).
#'
#'   - The name of a character or factor column in `mydata`, which will be used
#'   as-is. Commonly this could be a variable like `"site"` to ensure data from
#'   different monitoring sites are handled and presented separately. It could
#'   equally be any arbitrary column created by the user (e.g., whether a nearby
#'   possible pollutant source is active or not).
#'
#'   Most `openair` plotting functions can take two `type` arguments. If two are
#'   given, the first is used for the columns and the second for the rows.
#'
#' @param cols Colours to use for plotting. Can be a pre-set palette (e.g.,
#'   `"turbo"`, `"viridis"`, `"tol"`, `"Dark2"`, etc.) or a user-defined vector
#'   of R colours (e.g., `c("yellow", "green", "blue", "black")` - see
#'   [colours()] for a full list) or hex-codes (e.g., `c("#30123B", "#9CF649",
#'   "#7A0403")`). See [openColours()] for more details.
#'
#' @param date.breaks Number of major x-axis intervals to use. The function will
#'   try and choose a sensible number of dates/times as well as formatting the
#'   date/time appropriately to the range being considered. The user can
#'   override this behaviour by adjusting the value of `date.breaks` up or down.
#'
#' @param date.format This option controls the date format on the x-axis. A
#'   sensible format is chosen by default, but the user can set `date.format` to
#'   override this. For format types see [strptime()]. For example, to format
#'   the date like "Jan-2012" set `date.format = "\%b-\%Y"`.
#'
#' @param breaks,labels If a categorical colour scale is required then `breaks`
#'   should be specified. These should be provided as a numeric vector, e.g.,
#'   `breaks = c(0, 50, 100, 1000)`. Users should set the maximum value of
#'   `breaks` to exceed the maximum data value to ensure it is within the
#'   maximum final range, e.g., 100--1000 in this case. Labels will
#'   automatically be generated, but can be customised by passing a character
#'   vector to `labels`, e.g., `labels = c("good", "bad", "very bad")`. In this
#'   example, `0 - 50` will be `"good"` and so on. Note there is one less label
#'   than break.
#'
#' @param x.relation,y.relation This determines how the x- and y-axis scales are
#'   plotted. `"same"` ensures all panels use the same scale and `"free"` will
#'   use panel-specific scales. The latter is a useful setting when plotting
#'   data with very different values.
#'
#' @param angle.scale In radial plots (e.g., [polarPlot()]), the radial scale is
#'   drawn directly on the plot itself. While suitable defaults have been
#'   chosen, sometimes the placement of the scale may interfere with an
#'   interesting feature. `angle.scale` can take any value between `0` and `360`
#'   to place the scale at a different angle, or `FALSE` to move it to the side
#'   of the plots.
#'
#' @param windflow If `TRUE`, the vector-averaged wind speed and direction will
#'   be plotted using arrows. Alternatively, can be a list of arguments to
#'   control the appearance of the arrows (colour, linewidth, alpha value,
#'   etc.). See [windflowOpts()] for details.
#'
#' @param offset `offset` controls the size of the 'hole' in the middle and is
#'   expressed on a scale of `0` to `100`, where `0` is no hole and `100` is a
#'   hole that takes up the entire plotting area.
#'
#' @param key.position Location where the legend is to be placed. Allowed
#'   arguments include `"top"`, `"right"`, `"bottom"`, `"left"` and `"none"`,
#'   the last of which removes the legend entirely.
#'
#' @param key.title Used to set the title of the legend. The legend title is
#'   passed to [quickText()] if `auto.text = TRUE`.
#'
#' @param key.columns Number of columns to be used in a categorical legend. With
#'   many categories a single column can make to key too wide. The user can thus
#'   choose to use several columns by setting `key.columns` to be less than the
#'   number of categories.
#'
#' @param strip.position Location where the facet 'strips' are located when
#'   using `type`. When one `type` is provided, can be one of `"left"`,
#'   `"right"`, `"bottom"` or `"top"`. When two `type`s are provided, this
#'   argument defines whether the strips are "switched" and can take either
#'   `"x"`, `"y"`, or `"both"`. For example, `"x"` will switch the 'top' strip
#'   locations to the bottom of the plot.
#'
#' @param auto.text Either `TRUE` (default) or `FALSE`. If `TRUE` titles and
#'   axis labels will automatically try and format pollutant names and units
#'   properly, e.g., by subscripting the "2" in "NO2". Passed to [quickText()].
#'
#' @param plot When `openair` plots are created they are automatically printed
#'   to the active graphics device. `plot = FALSE` deactivates this behaviour.
#'   This may be useful when the plot *data* is of more interest, or the plot is
#'   required to appear later (e.g., later in a Quarto document, or to be saved
#'   to a file).
#'
#' @param key Deprecated; please use `key.position`. If `FALSE`, sets
#'   `key.position` to `"none"`.
#'
#' @aliases docs-shared-internal
#' @keywords internal
#' @aliases NULL
NULL