openair (version 0.4-0)

trendLevel: 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 properties. The default version of the plot uses y = time 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", 
    xlab = x, ylab = y, typelab = NULL, 
    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 = NULL,
    statistic = c("mean", "max", "frequency"), stat.args = NULL, 
    stat.safe.mode = TRUE, drop.unused.types = TRUE,
    ...)

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). Allowed options currently include

y, type

The names of the data series to use as the trendLevel y-axis and for additional conditioning, respectively. As x above.

xlab, ylab, typelab

The x-axis, y-axis and type conditioning labels. All labels are passed via quickText to handle formatting if enabled (auto.text = TRUE). By default trendLevel uses x and y names as xlab and ylab, respectively

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 applie

n.levels

The number of levels to split x, y and type data into if it is numeric. The default, c(10, 10, 4), cuts numeric x and y data into ten levels and numeric type

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 allows labels (xlab, ylab, main, etc.) to be passed to the plot via quickText. auto.text = FALSE turns this option of

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

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.

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

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 fun

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'

...

Addition options passed to levelplot in lattice for evaluation. Note: trendLevel sets several levelplot options, and, therefore, checks and modifies some options before passing them on. For examp

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 summarise. See openair.generics for further details. Summary statistics can also be extracted directly using the $data operator, e.g. object$data for output <- trendLevel(mydata).

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.

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