openair: trendLevel – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

trendLevel

Description

The trendLevel function provides a way of rapidly showing a large amount of data in a condensed form. In one plot, the variation in the concentration of one pollutant can to shown as a function of three other categorical properties. The default version of the plot uses y = hour of day, x = month of year and type = year to provide information on trends, seasonal effects and diurnal variations. However, x, y and type and summarising statistics can all be modified to provide a range of other similar plots.

Usage

trendLevel(
  mydata,
  pollutant = "nox",
  x = "month",
  y = "hour",
  type = "year",
  rotate.axis = c(90, 0),
  n.levels = c(10, 10, 4),
  limits = c(0, 100),
  cols = "default",
  auto.text = TRUE,
  key.header = "use.stat.name",
  key.footer = pollutant,
  key.position = "right",
  key = TRUE,
  labels = NA,
  breaks = NA,
  statistic = c("mean", "max", "frequency"),
  stat.args = NULL,
  stat.safe.mode = TRUE,
  drop.unused.types = TRUE,
  col.na = "white",
  ...
)

Arguments

`mydata`	The openair data frame to use to generate the `trendLevel` plot.
`pollutant`	The name of the data series in `mydata` to sample to produce the `trendLevel` plot.
`x`	The name of the data series to use as the `trendLevel` x-axis. This is used with the `y` and `type` options to bin the data before applying `statistic` (see below). Other data series in `mydata` can also be used. (Note: `trendLevel` does not allow duplication in `x`, `y` and `type` options within a call.)
`y`	The names of the data series to use as the `trendLevel` y-axis and for additional conditioning, respectively. As `x` above.
`type`	See `y`.
`rotate.axis`	The rotation to be applied to `trendLevel` `x` and `y` axes. The default, `c(90, 0)`, rotates the x axis by 90 degrees but does not rotate the y axis. (Note: If only one value is supplied, this is applied to both axes; if more than two values are supplied, only the first two are used.)
`n.levels`	The number of levels to split `x`, `y` and `type` data into if numeric. The default, `c(10, 10, 4)`, cuts numeric `x` and `y` data into ten levels and numeric `type` data into four levels. (Notes: This option is ignored for date conditioning and factors. If less than three values are supplied, three values are determined by recursion; if more than three values are supplied, only the first three are used.)
`limits`	The colour scale range to use when generating the `trendLevel` plot.
`cols`	The colour set to use to colour the `trendLevel` surface. `cols` is passed to `openColours` for evaluation. See `?openColours` for more details.
`auto.text`	Automatic routine text formatting. `auto.text = TRUE` passes common `lattice` labelling terms (e.g. `xlab` for the x-axis, `ylab` for the y-axis and `main` for the title) to the plot via `quickText` to provide common text formatting. The alternative `auto.text = FALSE` turns this option off and passes any supplied labels to the plot without modification.
`key.header, key.footer`	Adds additional text labels above and/or below the scale key, respectively. For example, passing the options `key.header = "", key.footer = c("mean","nox")` adds the addition text as a scale footer. If enabled (`auto.text = TRUE`), these arguments are passed to the scale key (`drawOpenKey`) via `quickText` to handle formatting. The term `"get.stat.name"`, used as the default `key.header` setting, is reserved and automatically adds statistic function names or defaults to `"level"` when unnamed functions are requested via `statistic`.
`key.position`	Location where the scale key should be plotted. Allowed arguments currently include “top”, “right”, “bottom” and “left”.
`key`	Fine control of the scale key via `drawOpenKey`. See `?drawOpenKey` for further details.
`labels`	If a categorical colour scale is required then these labels will be used. Note there is one less label than break. For example, `labels = c("good", "bad", "very bad")`. `breaks` must also be supplied if labels are given.
`breaks`	If a categorical colour scale is required then these breaks will be used. For example, `breaks = c(0, 50, 100, 1000)`. In this case “good” corresponds to values berween 0 and 50 and so on. 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` must also be supplied.
`statistic`	The statistic method to be use to summarise locally binned `pollutant` measurements with. Three options are currently encoded: “mean” (default), “max” and “frequency”. (Note: Functions can also be sent directly via `statistic`. However, this option is still in development and should be used with caution. See Details below.)
`stat.args`	Additional options to be used with `statistic` if this is a function. The extra options should be supplied as a list of named parameters. (see Details below.)
`stat.safe.mode`	An addition protection applied when using functions direclty with `statistic` that most users can ignore. This option returns `NA` instead of running `statistic` on binned subsamples that are empty. Many common functions terminate with an error message when applied to an empty dataset. So, this option provides a mechanism to work with such functions. For a very few cases, e.g. for a function that counted missing entries, it might need to be set to `FALSE` (see Details below.)
`drop.unused.types`	Hide unused/empty `type` conditioning cases. Some conditioning options may generate empty cases for some data sets, e.g. a hour of the day when no measurements were taken. Empty `x` and `y` cases generate 'holes' in individual plots. However, empty `type` cases would produce blank panels if plotted. Therefore, the default, `TRUE`, excludes these empty panels from the plot. The alternative `FALSE` plots all `type` panels.
`col.na`	Colour to be used to show missing data.
`...`	Addition options are passed on to `cutData` for `type` handling and `levelplot` in `lattice` for finer control of the plot itself.

Details

trendLevel allows the use of third party summarising functions via the statistic option. Any additional function arguments not included within a function called using statistic should be supplied as a list of named parameters and sent using stat.args. For example, the encoded option statistic = "mean" is equivalent to statistic = mean, stat.args = list(na.rm = TRUE) or the R command mean(x, na.rm= TRUE). Many R functions and user's own code could be applied in a similar fashion, subject to the following restrictions: the first argument sent to the function must be the data series to be analysed; the name ‘x’ cannot be used for any of the extra options supplied in stat.args; and the function should return the required answer as a numeric or NA. Note: If the supplied function returns more than one answer, currently only the first of these is retained and used by trendLevel. All other returned information will be ignored without warning. If the function terminates with an error when it is sent an empty data series, the option stat.safe.mode should not be set to FALSE or trendLevel may fail. Note: The stat.safe.mode = TRUE option returns an NA without warning for empty data series.

Value

As well as generating the plot itself, trendLevel also returns an object of class “openair”. The object includes three main components: call, the command used to generate the plot; data, the data frame of summarised information used to make the plot; and plot, the plot itself. If retained, e.g. using output <- trendLevel(mydata), this output can be used to recover the data, reproduce or rework the original plot or undertake further analysis.

An openair output can be manipulated using a number of generic operations, including print, plot and summary.

Summary statistics can also be extracted directly using results, e.g. results(object) for output <- trendLevel(mydata).

Author(s)

Karl Ropkins and David Carslaw

Examples

#basic use
#default statistic = "mean"
trendLevel(mydata, pollutant = "nox")

#applying same as 'own' statistic
my.mean <- function(x) mean(x, na.rm = TRUE)
trendLevel(mydata, pollutant = "nox", statistic = my.mean)

#alternative for 'third party' statistic
#trendLevel(mydata, pollutant = "nox", statistic = mean,
#           stat.args = list(na.rm = TRUE))

## Not run: 
# example with categorical scale
trendLevel(mydata, pollutant = "no2",
border = "white", statistic = "max",
breaks = c(0, 50, 100, 500),
labels = c("low", "medium", "high"),
cols = c("forestgreen", "yellow", "red"))

## End(Not run)

openair

Tools for the Analysis of Air Pollution Data

v2.10-0

GPL (>= 2)

Authors

David Carslaw [aut, cre], Karl Ropkins [aut]

Initial release

2022-06-21