Trend Heat Map

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 up to 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

trend_level(
  data,
  pollutant,
  x,
  y,
  facet = NULL,
  statistic = c("mean", "max", "frequency"),
  stat_args = NULL,
  stat_safemode = TRUE
)

Arguments

data

The openair data frame to use to generate the trendLevel plot.

pollutant

A column name identifying a pollutant concentration.

x, y, facet

The name of the data series with which to bin mydata. x and y form the x and y axes of the resulting plot, and facet is optionally used to separate the plot into separate panels. Duplication in x, y and facet are not permitted. If not representative of column names, the three arguments are passed to openair::cutData().

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_safemode

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.)

Value

A ggplot2::ggplot2 figure

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.

See also

Other time series and trend functions: trend_calendar(), trend_prop(), trend_variation()