R: Methods for Rglimclim simulation objects

Rglimclim simulation objects {Rglimclim}

R Documentation

Methods for Rglimclim simulation objects

Description

Simulations produced by the GLCsim routine are stored in separate files, which may be large especially if daily data are stored. Information about each simulation is stored in a small R object of class GLCsim; the methods documented here are intended to provide the user with a quick means of summarising and visualising simulation results.

Usage

## S3 method for class 'GLCsim'
print(x, name=TRUE,...)
## S3 method for class 'GLCsim'
summary(object,which.variables,which.sites,which.regions,
                           which.timescales,thresholds,season.defs,...)
## S3 method for class 'summary.GLCsim'
print(x, ...)
## S3 method for class 'summary.GLCsim'
plot(x,imputation,quantiles,
                                which.variables,which.sites,which.regions,
                                which.timescales,which.stats,which.seasons,
                                plot.titles,ylabs,colours.sim="greyscale",
                                colour.obs="black",...)

Arguments

`x, object`	An object of class `GLCsim`, resulting from a call to `GLCsim` or `summary.GLCsim` (see below).
`name`	A logical variable indicating whether the `print` method will produce an informative title to the output.
`which.variables`	A vector selecting the variables for which to produce plots and summaries. If omitted, plots and summaries will be produced for all available variables. Note that the specification of `which.variables` differs between the `GLCsim` methods and the `summary.GLCsim` method (currently just `plot.summary.GLCsim`). For the former, `which.variables` should be a numeric vector of variable numbers, the numbering corresponding to that in the original data file from which the simulations were initialised. For the latter, `which.variables` should be a character vector of variable names as stored in the relevant `dimnames` attribute and revealed by the `print` method for the object.
`which.sites`	An optional character vector of 4-character site codes. If supplied, plots and summaries will be restricted to the corresponding sites; otherwise they will be produced for all sites.
`which.regions`	An optional vector selecting regions for which to produce plots or summaries. If omitted, plots and summaries will be produced for all available regions. Like `which.variables`, the specification differs between the `GLCsim` and `summary.GLCsim` methods: for the former, it should be a numeric vector of region numbers (0 corresponding to the whole area), and for the latter it should be a character vector of region names. Regions must be defined in the `siteinfo` component of the simulation object; use `read.regiondef` or `define.regions` to achieve this.
`which.timescales`	Either `"daily"`, `"monthly"` or `c("daily","monthly")`. This selects the simulation output files to be processed. If omitted, all available files will be processed.
`thresholds`	A numeric vector the same length as `which.variables`. If present and if the element corresponding to a particular variable is non-`NA`, the `summary` method will calculate the proportion of exceedances of the corresponding threshold for that variable, as well as the mean and standard deviation conditional on threshold exceedance.
`season.defs`	A list of numeric vectors, defining months to be grouped together to form "seasons" when processing monthly output files. If not specified, separate summaries are produced for each month of the year.
`...`	Other arguments to generic methods.
`imputation`	For the `plot` method, an optional object of class `summary.GLCsim` that is treated as containing summaries from a set of imputations conditioned on all available data. If supplied, an imputation envelope will be overlaid on the plots.
`quantiles`	For the `plot` methods, a vector of quantiles controlling which quantiles of simulated distributions will be plotted. Defaults to `c(0,0.01,0.05,0.1,0.25,0.5,0.75,0.9,0.95,0.99,1)`.
`which.stats`	For the `plot` methods, a character vector specifying the summary statistics to be plotted for daily data (if requested via `which.timescales`). These should exactly match the names of the statistics as output by the `summary` method, and as stored in the `dimnames` attribute of the corresponding elements of a `summary.GLCsim` object (see "Value" section below).
`which.seasons`	For the `plot` methods, a character vector specifying the names of the seasons for which plots are to be produced. Again, these names should match the `dimnames` from the corresponding `summary.GLCsim` object.
`plot.titles`	For the `plot` methods, a character vector of titles for the plots. It is the user's responsibility to ensure that the length of this vector matches the number of plots actually produced. If omitted, the routine will construct plot titles automatically.
`ylabs`	For the `plot` methods, a character vector of y-axis labels for the plots. Similar comments apply as for `plot.titles`.
`colours.sim`	Either `"greyscale"` (the default), `"colour"` or a vector of valid colour specifiers, of length `length(quantiles)-1`. These colours will be used to shade the simulated distributions. `"greyscale"` produces plots that are suitable for inclusion in printed material; `"colour"` uses a default colour scale generated using the `rainbow` command.
`colour.obs`	The colour to use for plotting an imputation envelope if required. Defaults to `"black"`.

Details

The print method for the GLCsim class produces a summary of the simulation settings: input file name, which variables were simulated, the simulation period and numbers of simulations, as well as details of which output has been stored and where the output files are located.

The summary method is used to produce summary statistics that can be plotted or used for further analysis. The objects that it produces are lists (see "Value" section below) that have their own summary.GLCsim class.

The print method for the summary.GLCsim class produces a concise printout of the summaries that have been calculated and can be useful for (e.g.) finding the relevant names that should be used in a call to the plot method for this class (i.e. the available choices for the which.variables, which.regions arguments etc.).

There is no plot method for objects of class GLCsim; plotting is done on objects of class summary.GLCsim (see "Value" section below). Usually, the most efficient way to plot results of a simulation is precompute all summary statistics via a single call to the summary method, and then to use multiple calls to plot.summary.GLCsim to produce plots for subsets of these statistics without requiring any further computations. It may be useful to know the order in which this plot method produces its plots: it loops over variables and, for each variable, first produces all plots for daily summary statistics (if requested) and then the plots for monthly or seasonal means. For the daily summary statistics, the routine first loops over all sites for which plots have been requested (and, within this, over all statistics that have been requested) and then over all regions. For monthly or seasonal means, the routine just loops over the seasons that have been defined.

If an imputation argument is supplied to the plot method, a band will be superimposed on the plots of simulated distributions, showing the range of values found within the imputation object. This is useful to assess whether the simulations can capture the observed behaviour, taking account of uncertainty in the observations due to missing values. It is worth noting that if the imputation object is derived from a simulation containing 39 imputations, then the resulting band will be a 95% confidence interval for the actual values of the quantities plotted (because if we could pool the actual value with the 39 imputations, there would be a 1/40 chance that the actual value would be the maximum of the pooled sample and a 1/40 chance that it would be the minimum).

Value

The print and plot methods produce NULL values.

The summary method produces a list object of class summary.GLCsim, with components Daily and Monthly (which are NULL unless the corresponding summaries have been selected via the which.timescales argument). The Daily component itself contains components Sites and Regions, each of which is a 5-dimensional array of summary statistics: the dimensions are Simulation (simulation number), Month, Site or Region, Variable and Statistic. The Monthly component is a 5-dimensional array of seasonal means for selected regions, with dimensions Simulation, Region, Variable, Year and Season (months); the individual dimnames for the Season (months) dimension are of the form (for example) "XXX, YYY, ZZZ" where XXX, YYY and ZZZ are elements of month.abb. Note that (a) the seasonal means are computed as a straight average of the corresponding monthly values (so they do not account for different numbers of days in each month) (b) if a season is defined via season.defs as, for example, c(12,1,2) then, for year YYYY, the routine will calculate the mean of each variable for month 12 in year YYYY and months 1 and 2 in year YYYY+1.

Note

Because the summary method produces objects with their own print method, the user cannot see the values of the summaries simply by calling print on a summary object. To see the contents of a summary.GLCsim object in its entirety, use unclass. Specific parts of the object can be accessed directly using the component names. This can be useful for extracting time series of summary statistics (particularly extremes) for subsequent analysis (see examples below).

A potential source of confusion with these routines is that the which.variables and which.regions are specified differently in the GLCsim and summary.GLCsim methods. In the GLCsim methods, they should be supplied as numeric vectors; in the summary.GLCsim method(s) they should be supplied as character vectors, corresponding to the required dimnames of the GLCsim object to which they are applied.

Author(s)

Richard Chandler (r.chandler@ucl.ac.uk)