mcmcplots (version 0.2)

mcmcplot: Diagnostics Plots for MCMC in HTML format

Description

Creates an HTML file which will display diagnostic plots (trace, density, autocorrelation) from an MCMC simulation. When the number of parameters in an MCMC simulation is large, viewing all plots in a web browser is much easier than clicking through R graph windows.

Usage

mcmcplot(mcmcout, parms = NULL, regex = NULL, random = NULL, dir = tempdir(), filename = "MCMCoutput", extension = "html", title = NULL, heading = NULL, col = mcmcplotsPalette(nchains), lty = 1, style=c("gray", "plain"))

Arguments

mcmcout

posterior draws. This argument will be coerced to an mcmc object.

parms

character vector specifying which subsets of parameters to plot. If NULL and regex=NULL, mcmcplot will plot all parameters. Regular expressions are used to strip all numbers and punctuation out of the parameter name

regex

character vector of regular expressions denoting groups of parameters to plot.

random

integer specifying how many parameters from each group will be randomly selected for plotting. This argument is useful when mcmcout has a large number of parameters (e.g., from a hierarchical model). If NULL, mcmcplot

dir

string containing the directory where the plots and the main html file will be stored.

filename

string containing the name of the main html file which will contain code to display each plot produced by mcmcplot.

extension

string containing the extension to be used for the html file.

title

string containing the title to be included in the html file. Default is to use the name of object passed as the mcmcout argument prepended with the string "MCMC Output: ".

heading

string containing the heading to be used for the html file.

col

vector of colors. This will determine the colors that will be used to plot each chain in the traceplots and density plots. If missing, mcmcplot will use 1:nchain + 1, where nchain is the number of chains per parame

lty

vector of line types. This will determine the line types that will be used to plot each chain in the traceplots and density plots. If missing, mcmcplot will use 1 for all line types.

style

if "gray", then the plotting region is printed with a gray background, otherwise the default plotting region is used.

Value

• Invisibly returns a string containing the path to filename.

Details

The mcmcplot function generates an html file that contains plots -- trace plots, autocorrelation plots, and density plots -- for parameters from an MCMC simulation. When an MCMC simulation contains a large number of parameters, it's no longer convenient to view plots in a small graph window. Viewing the plots in an web browser gives the user the ability to scroll through and examine a large number of plots in a more convenient manner. The function mcmcplot uses character strings in parms and/or regex to denote groups of parameters that will be plotted. For example, if parms is a vector c("alpha", "beta"), then parameters alpha[1], alpha[2], ..., beta[1], beta[2], ...will be plotted. The regex option is similar to the parms option except that it allows more fine-tuned control over which parameters will be plotted. In fact, character strings in parms are converted to default regular expressions and concatenated with regex to form all regular expressions that will be used to select the groups of parameters to plot. The random option is useful when an MCMC simulation contains a large number of parameters in a group, e.g. in a hierarchical model with one or more parameter per observation in the data set. In such settings, it's not feasible to create or examine all possible plots. The random argument allows the user to specify a maximum number of plots to create for each parameter grouping. If a parameter grouping exceeds the number specified in random, then a number of parameters (as specified in random) will be randomly selected for plotting. If random is a vector, then each element of random corresponds to a parameter grouping specified in parms and regex. If specified, the random argument is recycled to be the same length as length(parms) + length(regex). Values of NA in random denote parameter groupings where all parameters in the group will be plotted.

References

None.

See Also

Plotting functions in the coda package.

Examples

## Create fake MCMC output
nc <- 10; nr <- 1000
pnames <- c(paste("alpha[", 1:5, "]", sep=""), paste("gamma[", 1:5, "]", sep=""))
means <- rpois(10, 20)
fakemcmc <- as.mcmc.list(lapply(1:3, function(i) mcmc(matrix(rnorm(nc*nr, rep(means,each=nr)), nrow=nr, dimnames=list(NULL,pnames)))))

## Use mcmcplot to plot
## the fake MCMC output
mcmcplot(fakemcmc)
mcmcplot(fakemcmc, "gamma")
mcmcplot(fakemcmc, regex="alpha\\[[12]", style="plain")
mcmcplot(fakemcmc, "gamma", regex="alpha\\[[12]")
mcmcplot(fakemcmc, random=2)
mcmcplot(fakemcmc, random=c(2, 3))

## mcmcplot works on bugs objects too
library(R2WinBUGS)
example("openbugs", "R2WinBUGS")
## from the help file for openbugs:
schools.sim <- bugs(data, inits, parameters, model.file,
                    n.chains = 3, n.iter = 5000,
                    program = "openbugs", working.directory = NULL)
mcmcplot(schools.sim)