openair (version 0.3-13)

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,
    limits = c(0, 100), cols = "default", main = "", 
    strip = NULL, auto.text = TRUE, key.header = "use.stat.name",
    key.footer = pollutant, key.position = "right", key = NULL,
    statistic = c("mean", "max"), stat.args = NULL, 
    stat.safe.mode = TRUE, output = c("data", "graph"),
    ...)

Arguments

mydata

The openair data frame to be used to generate the trendLevel plot.

pollutant

The pollutant in mydata to be sampled to produce the trendLevel plot.

x

The dataseries 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 "hour", "mo

y

The dataseries to use as the trendLevel y-axis. As x above.

type

The dataseries to use for additional conditioning. 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, but does at

limits

The colour scale range to be uesd when generating the trendLevel plot.

cols

The colour set to be used to colour the trendLevel surface. cols is passed to openColours for evaluation.

main

The plot title. The option is passed via quickText to handle formatting if enabled (auto.text = TRUE).

strip

Fine control of typelab and associated plot strip. The option is passed to levelplot in lattice for evaluation. Default (NULL) allows trendLevel full control of strip. If enabled,

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. These arguments are passed to

key.position

Location where the scale key is to 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. Two options are currently encoded: "mean" (default) and "max". (Note: Functions can also be sent directly via stat

stat.args

Any additional args to used with statistic if this is a function. The extra args 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

output

Output mode. The default, output = "data", generates the trendLevel plot and returns the summary data. This can be retained using, e.g., my.ans <- trendLevel(mydata) and used in further analysis. The alternative setting (

...

Addition options, passed to levelplot in lattice for evaluation.

Value

• trendLevel return either a data frame of the summarised information plotted during the trendLevel call or the plot itself, depending on output settings (see above). In both cases the plot itself is produced as part if this operation.

Details

trendLevel allows the use of third party summarising functions via the statistic option. Any additional function arguments should be supplied as a list of named parameters as stat.args. For example, the encoded option statistic = "mean" is equivalent to statistic = mean, stat.args = list(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 send to the function must be the dataseries 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. If the function terminates with an error when it is sent an empty data series, the stat.safe.mode = TRUE can be used as this only evaluates populated data series. Note: The option returns an NA without warning for empty data series.

Examples

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

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