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.

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)

See Also

GLCsim.


[Package Rglimclim version 1.3-2 Index]