add.summary: Summary statistics and plot methods for runjags class objects

In runjags: Interface Utilities, Model Templates, Parallel Computing Methods and Additional Distributions for MCMC Models in JAGS

Summary statistics and plot methods for runjags class objects

Description

Objects of class runjags-class have specialised options available for print, plot and summary. These allow various options for controlling how the output is presented, including sub-selection of variables of interest (using partial matching).

Usage

add.summary(
  runjags.object,
  vars = NA,
  mutate = NA,
  psrf.target = 1.05,
  normalise.mcmc = TRUE,
  modeest.opts = list(),
  confidence = c(0.95),
  autocorr.lags = c(10),
  custom = NULL,
  silent.jags = runjags.getOption("silent.jags"),
  plots = runjags.getOption("predraw.plots"),
  plot.type = c("trace", "ecdf", "histogram", "autocorr", "key", "crosscorr"),
  col = NA,
  summary.iters = 20000,
  trace.iters = 1000,
  separate.chains = FALSE,
  trace.options = list(),
  density.options = list(),
  histogram.options = list(),
  ecdfplot.options = list(),
  acplot.options = list()
)

## S3 method for class 'runjags'
summary(object, ...)

## S3 method for class 'runjags'
plot(
  x,
  plot.type = c("trace", "ecdf", "histogram", "autocorr", "crosscorr"),
  vars = NA,
  layout = runjags.getOption("plot.layout"),
  new.windows = runjags.getOption("new.windows"),
  file = "",
  mutate = NULL,
  col = NA,
  trace.iters = NA,
  separate.chains = NA,
  trace.options = NA,
  density.options = NA,
  histogram.options = NA,
  ecdfplot.options = NA,
  acplot.options = NA,
  ...
)

## S3 method for class 'runjags'
print(x, vars = NA, digits = 5, ...)

## S3 method for class 'runjagsplots'
print(
  x,
  layout = runjags.getOption("plot.layout"),
  new.windows = runjags.getOption("new.windows"),
  file = "",
  ...
)

## S3 method for class 'runjagsplots'
plot(
  x,
  layout = runjags.getOption("plot.layout"),
  new.windows = runjags.getOption("new.windows"),
  file = "",
  ...
)

Arguments

runjags.object	an object of class runjags-class.
vars	an optional character vector of variable names. If supplied, only variable names in the object supplied with a partial match to anything in 'vars' will be used. Note that regular expressions are not allowed, but the caret (^) token can be used to specify the match at the start of a variable name, and a quoted vars will be matched exactly. Default NA meaning all variables available are returned.
mutate	either a function or a list with first element a function and remaining elements arguments to this function. This can be used to add new variables to the posterior chains that are derived from the directly monitored variables in JAGS. This allows the variables to be summarised or extracted as part of the MCMC objects as if they had been calculated in JAGS, but without the computational or storage overheads associated with calculating them in JAGS directly. The plot, summary and as.mcmc methods for runjags objects will automatically extract the mutated variables along with the directly monitored variables.
psrf.target	the desired cutoff for 'convergence' as determined Gelman and Rubin's convergence diagnostic (see gelman.diag). This is somewhat arbitrary, but 1.05 is a commonly used figure.
normalise.mcmc	an option test transformations of the monitored variable for improved normality, which is an assumption of the Gelman and Rubin statistic. Setting this option to FALSE will likely cause problems with calculating the psrf for highly skewed variables.
modeest.opts	arguments to be passed to the mlv function to calculate the mode of continuous variables. Ignored if the mode.continuous option in runjags.options is set to FALSE.
confidence	a numeric vector of probabilities (between 0 and 1) on which to base confidence interval calculations.
autocorr.lags	a numeric vector of integers on which to base the autocorrelation diagnostic. See also the autocorr plot type.
custom	a custom function which takes a numeric object as input and outputs a single summary statistic. This statistic will be included with the others in the print and summary method outputs.
silent.jags	option to suppress feedback text produced by the summary function when summary statistics must be recalculated.
plots	option to pre-draw the plots given by plot.type to facilitate more convinient assessment of convergence after the model has finished running, at the expense of requiring a larger object to stored. The default value uses the option given in runjags.options
plot.type	a character vector of plots to produce, from 'trace', 'density', 'ecdf', 'histogram', 'autocorr', 'crosscorr', 'key' or 'all'. These are all based on the equivalent plots from the lattice package with some modifications.
col	a vector of colours to use for the different chains. This will be used for all plot types (where relevant), including the 'key' plot which functions to label the chain numbers of the various colours. The default uses the standard lattice colour palatte for up to 7 chains, with a rainbow palette used for larger numbers of chains, and combined chains shown in dark grey.
summary.iters	the number of iterations to thin the chains to before calculating summary statistics (including all plots except the trace plot). Setting too high a value will cause a long delay while calculating these statistics.
trace.iters	the number of iterations to thin the chains to before producing traceplots. Setting too high a value will cause large file sizes and delays displaying the trace plots.
separate.chains	option to display each plot separately for different chains (except crosscorr and key). If FALSE, either the separate chains will be shown on the same plot (for trace, density, and ecdf) or as a single plot with combined chains (for histogram and autocorr).
trace.options	a list of arguments to be passed to the underlying plot function that creates the trace plots. A colour specification should be specified using the 'col' argument above to ensure that this is the same across plot types.
density.options	a list of arguments to be passed to the underlying plot function that creates the density plots. A colour specification should be specified using the 'col' argument above to ensure that this is the same across plot types.
histogram.options	a list of arguments to be passed to the underlying plot function that creates the histogram plots. A colour specification should be specified using the 'col' argument above to ensure that this is the same across plot types.
ecdfplot.options	a list of arguments to be passed to the underlying plot function that creates the ecdf plots. A colour specification should be specified using the 'col' argument above to ensure that this is the same across plot types.
acplot.options	a list of arguments to be passed to the underlying plot function that creates the autocorr plots. A colour specification should be specified using the 'col' argument above to ensure that this is the same across plot types.
object	an object of class runjags-class.
...	additional arguments to be passed to pdf for the plot.runjags method, or the default print method for the print.runjags method.
x	an object of class runjags-class.
layout	the layout of the runjags plots to print, a numeric vector of length 2 stating the number of rows and columns of plots. The default value is taken from runjags.options.
new.windows	option to produce each plot (or matrix of plots) on a new graphics window rather than over-writing the previous plots. For R interfaces where plots can be cycled through (e.g. the OS X GUI and RStudio), it is likely to be preferable to produce all plots to the same device. The default value is taken from runjags.options, which depends on the system.
file	an optional filename to which plots can be saved using pdf. The default "" means produce plots in the active graphics device.
digits	the number of digits to display for printed numerical output.

Details

The print method is designed to display option prettily, wheras the summary method is designed to return the central table (summary statistics for each variable) as a numeric matrix that can be assigned to another variable and manipulated by the user. If summary statistics have been pre-calculated these will be returned without re-calculation by both methods, wheras only the summary method will re-calculate summary statistics if they are not already available.

The add.summary function returns an object of class runjags, with the new summary statistics (and plots if selected) stored internally for future use. Note that many of the summary method options can be passed to run.jags when the model is run and will be remembered for future output, although they can be modified explicitly by subsequent calls to summary or add.summary. If the summary statistics or plots requested are identical to those stored inside the runjags object, they will not be re-calculated. Calculation of the mode of continuous variables is possible, but requires the suggested modeest package.

Value

The summary method returns a numeric matrix of summary statistics for each variable (invisibly for the print method), wheras the add.summary function returns an object of class runjags-class with the new sumamry statistics (and plots if selected) stored for future use. Some summary statistics are only calculated for stochastic variables, but all monitored variables are shown in the output. The information returned as part of the summary is as follows:

• LowerXX The lower confidence limit for the highest posterior density (HPD) credible interval, as calculated by HPDinterval. One or more confidence limits can be selected using the confidence argument - the default of 0.95 corresponds to 95% credible intervals.

• Median The median value, as calculated by median.

• UpperXX The upper confidence limit for the highest posterior density (HPD) credible interval, as calculated by HPDinterval. One or more confidence limits can be selected using the confidence argument - the default of 0.95 corresponds to 95% credible intervals.

• Mean The mean value, as calculated by mean.

• SD The sample standard deviation, derived from var.

• Mode The mode of the variable. For discrete variables this is calculated using table, and for continuous variables by mlv if this package is installed - see the modeest.opts argument for more details.

• MCerr The Monte Carlo standard error associated with this variable, which is the standard error divided by the square root of the effective sample size as caulculated by effectiveSize.

• MC%ofSD The Monte Carlo standard error expressed as a percentage of the standard deviation of the variable - a rule of thumb is that this should be less than approximately 5%.

• SSeff The effective sample size as caulculated by effectiveSize. An effective sample size of over 400 should correspond to an MCerr of less than 5% of the sample standard deviation.

• AC.XX The autocorrelation of the sample, as calculated by autocorr.diag. One or more lag values can be specified using the autocorr.lags argument - the default is 10 iterations.

• psrf The potential scale reduction factor of the Gelman-Rubin statistic autocorrelation of the sample, as calculated by autocorr.diag. This is sometimes referred to as Rhat (or R-hat). Note that any variables marked with a $ sign were stochastic in some chains but not in others - this usually indicates a problem with the model or sampler.

References

Matthew J. Denwood (2016). runjags: An R Package Providing Interface Utilities, Model Templates, Parallel Computing Methods and Additional Distributions for MCMC Models in JAGS. Journal of Statistical Software, 71(9), 1-25. doi:10.18637/jss.v071.i09

See Also

runjags-class for details on other methods available for runjags class objects

runjags documentation built on Aug. 21, 2023, 9:09 a.m.