parms2plot {mcmcplots}

Matches groups of parameters to plot in MCMC diagnostics plots.

Description

Utility function that finds the parameter names to plot in the mcmcplot function. Intended for internal use only.

Usage

parms2plot(parnames, parms, regex, random, leaf.marker = "[\\[_]", do.unlist = TRUE)

Arguments

parnames

parameter names from an MCMC run

parms

partial parameter names that will be used to determine which subset of parnames will be plotted.

regex

a vector of character strings containing regular expressions to match parameter names in the mcmc object.

random

an integer or NULL. If an integer is specified, the function will select only random number of plots from each parameter group for plotting. If NULL, all parameter names from groups specified in params will be plotted.

leaf.marker

a regular expression with a character class that marks the beginning of the “leaf” portion of a parameter name. The default character class includes [ and _

do.unlist

a logical indicating whether the function should return the vector of parameter names or a list of parameter names according to parameter "groupings" (so parameters can be accessed according to their "stems"). This option was added in order to improve the functionality of mcmcplot function.

Details

The function parms2plot is used internally by most plotting functions in the mcmcplots package. The function's purpose is to allow users to conveniently specify groups of parameters to be used in plots of MCMC output.

parms2plot relies on using regular expressions to find “stems” and “leaves” in parameter names and to create groups of parameters. For example, the parameter beta[10] has stem beta and leaf [10], and this naming convention indicates that the parameter beta[10] is part of a larger collection of beta parameters.

parms2plot uses a “leaf marker” specified by the leaf.marker argument to determine the end of the parameter stem and the beginning of its leaf. The default leaf marker is an open left bracket “[” or an “_” as specified by a regular expression character class.

Creating plots of specific groupings of parameters is possible by specifying parameter stems in the parms argument. For example, calling the function traplot(mcmcout, parms="beta") will create a single plot window of trace plots for parameters beta[1], ..., beta[10].

At first glance the leaf-marker concept might seem like overkill. For example, to plot parameters mu[1], ..., mu[10] why not simply use a string matching function to match “mu” in the parameter names? The answer is that other parameter names might also match “mu” but may not be part of the grouping mu[1], ..., mu[10]. A model with parameter name mu.gamma would match the string “mu” but is not part of the parameter grouping mu[1], ..., mu[10]. parms2plot avoids this “greedy” matching by requiring an explicit declaration of a leaf marker.

parms2plot also allows the user to specify regular expressions for more direct control over the groups of parameters that are plotted. Regular expressions are specified via the regex argument. When parms, regex, and random are NULL, parms2plot will return all parameter names.

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 is not feasible to create or examine plots for all parameters in a model. 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.

Value

A character vector with parameter names.

Author(s)

S. McKay Curtis with contributions from Ilya Goldin

See Also

mcmcplot, caterplot, traplot, denplot

Examples

prm <- c(paste("gamma[", 1:30, "]", sep=""), paste("alpha[", 1:20, "]", sep=""))

parms2plot(prm, NULL, NULL, NULL)      # returns all
parms2plot(prm, NULL, NULL, 5)         # returns 5 randomly from each group
parms2plot(prm, NULL, NULL, c(5, 10))  # 5 from gamma, 10 from alpha
parms2plot(prm, NULL, NULL, c(10, NA)) # 10 from gamma, all from alpha
parms2plot(prm, "alpha", NULL, NULL)   # all alphas
parms2plot(prm, "gamma", NULL, NULL)   # all gammas
parms2plot(prm, NULL, "alpha\\[1[[:digit:]]\\]$", NULL)   # alpha[10]-alpha[19]
parms2plot(prm, "gamma", "alpha\\[1[[:digit:]]\\]$", NULL)  # all gamma and alpha[10]-alpha[19]