smoothTrend: Calculate smoothTrends

Description

Use non-parametric methods to calculate time series trends

Usage

smoothTrend(mydata,
pollutant = "nox",
deseason = FALSE,
type = "default",
statistic = "mean",
percentile = NA,
data.thresh = 0,
simulate = FALSE,
n = 200,
autocor = FALSE,
cols = "brewer1",
ylab = pollutant,
xlab = "year",
lty = 1,
lwd = 1,
pch = 1,
cex = 0.6,
key.columns = length(percentile),
main = "",
ci = TRUE,
alpha = 0.2,
date.breaks = 7,
auto.text = TRUE,...)

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

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.

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 (%) when
  aggregating 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

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.

ylab

y-axis label.

xlab

x-axis label.

lty

Line type to use, can be a vector of types if the option
    statistic = "percentile" is used e.g. lty = c(5, 1, 5).

lwd

Line width to use, can be a vector of widths if the option
    statistic = "percentile" is used e.g. lwd = c(1, 2,
      1).

pch

Plot symbol to use, can be a vector of symbols if the option
    statistic = "percentile" is used e.g. pch = c(1, 2,
      1). To remove symbols altogether use pch = NA.

cex

Plot symbol size, can be a vector of sizes if the option
    statistic = "percentile" is used e.g. cex = c(1, 2,
    4).

key.columns

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

main

Title of plot, if required.

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.

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.

...

Other graphical parameters e.g. pch = 16 for filled
    circles and to cutData.  For example, in the case
    of cutData the option hemisphere = "southern"

`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. 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. See openair.generics 
  for further details.

`Warning`

If the option deseason = TRUE is set and there
are missing data after aggregation to monthly values, missing months
will be linearly interpolated.

`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
mgcv package to find the most appropriate level of
smoothing. The function is particularly suited to situations where trends
are not monotonic (see discussion with MannKendall 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.

95% confidence intervals are shown by shading. Bootstrap estimates of
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`

MannKendall for an alternative method of
  calculating trends.

`Examples`

Run this code# 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))
Run the code above in your browser using DataLab