openair (version 1.5)

smoothTrend: Calculate nonparametric smooth trends

Description

Use non-parametric methods to calculate time series trends

Usage

smoothTrend(mydata, pollutant = "nox", deseason = FALSE, type = "default",
  statistic = "mean", avg.time = "month", percentile = NA,
  data.thresh = 0, simulate = FALSE, n = 200, autocor = FALSE,
  cols = "brewer1", shade = "grey95", xlab = "year",
  y.relation = "same", ref.x = NULL, ref.y = NULL,
  key.columns = length(percentile), name.pol = pollutant, ci = TRUE,
  alpha = 0.2, date.breaks = 7, auto.text = TRUE, k = NULL, ...)

Arguments

mydata

A data frame containing the field date and at least one other parameter for which a trend test is required; typically (but not necessarily) a pollutant.

pollutant

The parameter for which a trend test is required. Mandatory.

deseason

Should the data be de-deasonalized first? If TRUE the function stl is used (seasonal trend decomposition using loess). Note that if TRUE missing data are first linearly interpolated because stl cannot

type

type determines how the data are split i.e. conditioned, and then plotted. The default is will produce a single plot using the entire data. Type can be one of the built-in types as detailed in cutData e.g. season

statistic

Statistic used for calculating monthly values. Default is mean, but can also be percentile. See timeAverage for more details.

avg.time

Can be month (the default), season or year. Determines the time over which data should be averaged. Note that for year, six or more years are required. For season the

percentile

Percentile value(s) to use if statistic = "percentile" is chosen. Can be a vector of numbers e.g. percentile = c(5, 50, 95) will plot the 5th, 50th and 95th percentile values together on the same plot.

data.thresh

The data capture threshold to use (the data using avg.time. A value of zero means that all available data will be used in a particular period regardless if of the number of values available. Conversely, a value of 100 will mean that all dat

simulate

Should simulations be carried out to determine the Mann-Kendall tau and p-value. The default is FALSE. If TRUE, bootstrap simulations are undertaken, which also account for autocorrelation.

n

Number of bootstrap simulations if simulate = TRUE.

autocor

Should autocorrelation be considered in the trend uncertainty estimates? The default is FALSE. Generally, accounting for autocorrelation increases the uncertainty of the trend estimate sometimes by a large amount.

cols

Colours to use. Can be a vector of colours e.g. cols = c("black", "green") or pre-defined openair colours --- see openColours for more details.

shade

The colour used for marking alternate years. Use white or transparent to remove shading.

xlab

x-axis label, by default year.

y.relation

This determines how the y-axis scale is plotted. "same" ensures all panels use the same scale and "free" will use panel-specfic scales. The latter is a useful setting when plotting data with very different values. ref.x See ref.y for det

ref.x

See ref.y.

ref.y

A list with details of the horizontal lines to be added representing reference line(s). For example, ref.y = list(h = 50, lty = 5) will add a dashed horizontal line at 50. Several lines can be plotted e.g. ref.y = list(h = c(50, 100

key.columns

Number of columns used if a key is drawn when using the option statistic = "percentile".

name.pol

Names to be given to the pollutant(s). This is useful if you want to give a fuller description of the variables, maybe also including subscripts etc.

ci

Should confidence intervals be plotted? The default is FALSE.

alpha

The alpha transparency of shaded confidence intervals - if plotted. A value of 0 is fully transparent and 1 is fully opaque.

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. This does not always work as desired automatically. The user can

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.

k

This is the smoothing parameter used by the gam function in package mgcv. By default it is not used and the amount of smoothing is optimised automatically. However, sometimes it is useful to set the smoothing amount manually u

...

Other graphical parameters are passed onto cutData and lattice:xyplot. For example, smoothTrend passes the option hemisphere = "southern" on to cutData to provide southern (rather than de

Value

• As well as generating the plot itself, smoothTrend 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. Note that data is a list of two data frames: data (the original data) and fit (the smooth fit that has details of the fit and teh uncertainties). If retained, e.g. using output <- smoothTrend(mydata, "nox"), 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.

Details

The smoothTrend function provides a flexible way of estimating the trend in the concentration of a pollutant or other variable. Monthly mean values are calculated from an hourly (or higher resolution) or daily time series. There is the option to deseasonalise the data if there is evidence of a seasonal cycle. smoothTrend uses a Generalized Additive Model (GAM) from the gam package to find the most appropriate level of smoothing. The function is particularly suited to situations where trends are not monotonic (see discussion with TheilSen for more details on this). The smoothTrend function is particularly useful as an exploratory technique e.g. to check how linear or non-linear trends are. 95of the confidence intervals are also available through the simulate option. Residual resampling is used. Trends can be considered in a very wide range of ways, controlled by setting type - see examples below.

See Also

TheilSen for an alternative method of calculating trends.

Examples

# load example data from package
data(mydata)

# trend plot for nox
smoothTrend(mydata, pollutant = "nox")

# trend plot by each of 8 wind sectors
smoothTrend(mydata, pollutant = "o3", type = "wd", ylab = "o3 (ppb)")

# several pollutants, no plotting symbol
smoothTrend(mydata, pollutant = c("no2", "o3", "pm10", "pm25"), pch = NA)

# percentiles
smoothTrend(mydata, pollutant = "o3", statistic = "percentile",
percentile = 95)

# several percentiles with control over lines used
smoothTrend(mydata, pollutant = "o3", statistic = "percentile",
percentile = c(5, 50, 95), lwd = c(1, 2, 1), lty = c(5, 1, 5))