MCMCsummary: Summary function for MCMC output

Description Usage Arguments Value Details Notes References Examples

View source: R/MCMCsummary.R

Description

Extract summary information from MCMC output (mean, median, quantiles, Gelman-Rubin convergence statistic, number of effective samples, and specified custom metrics) for specific parameters of interest.

Usage

1
2
MCMCsummary(object, params = "all", excl = NULL, ISB = TRUE, digits = 2,
  Rhat = TRUE, n.eff = FALSE, func = NULL, func_name = NULL)

Arguments

object

Object containing MCMC output. See DETAILS below.

params

Character string (or vector of character strings) denoting parameters to be returned in summary output.

Default 'all' returns all parameters in summary output.

excl

Character string (or vector of character strings) denoting parameters to exclude. Used in conjunction with params argument to select parameters of interest.

ISB

Ignore Square Brackets (ISB). Logical specifying whether square brackets should be ignored in the params and excl arguments. If TRUE, square brackets are ignored - input from params and excl are otherwise matched exactly. If FALSE, square brackets are not ignored - input from params and excl are matched using grep, which can take arguments in regular expression format. This allows partial names to be used when specifying parameters of interest.

digits

Number of digits to include for posterior summary. Values will be rounded to the specified number of digits (except for Rhat which is always rounded to 2 digits).

Default is digits = 2.

Rhat

Logical specifying whether to calculate and display the Gelman-Rubin convergence statistic (Rhat). Values near 1 suggest convergence (Brooks and Gelman 1998). Rhat = FALSE will prevent display of this column in summary output. Specifying Rhat = FALSE, will increase function speed, particularly with very large 'mcmc.list' objects.

n.eff

Logical specifying whether to calculate and display the number of effective samples for each parameter. Kruschke (2014) recommends n.eff > 10,000 for reasonably stable posterior estimates. n.eff = FALSE will prevent display of this column in summary output. Specifying n.eff = FALSE, will increase function speed, particularly with very large 'mcmc.list' objects.

func

Function to be performed on MCMC output. If a function is specified, it will be evaluated on posteriors for each specified parameter and returned as a column in the summary output (or multiple columns if the function returns more than one value).

func_name

Character string (or vector of character strings) specifying labels for output from func argument. If func_name is not specified, columns with func argument will be labeled 'func'.

Value

Function returns summary information (including parameter posterior mean, posterior sd, 2.5% quantile, median, 97.5% quantile, Gelman-Rubin convergence statistic (Rhat), number of effective samples, and other specified metrics) for specified parameters.

Details

object argument can be a stanfit object (rstan package), an mcmc.list object (coda package), an R2jags model object (R2jags package), or a matrix containing MCMC chains (each column representing MCMC output for a single parameter, rows representing iterations in the chain). The function automatically detects the object type and proceeds accordingly.

Notes

For mcmc.list objects, Gelman-Rubin convergence statistic (Rhat) is calculated using the gelman.diag function in the coda package.

For mcmc.list objects, the number of effective samples is calculated using the effectiveSize function in the coda package.

References

Brooks, S. P., and A. Gelman. 1998. General methods for monitoring convergence of iterative simulations. Journal of Computational and Graphical Statistics 7:434.

Kruschke, J. 2014. Doing Bayesian data analysis: A tutorial with R, JAGS, and Stan. Academic Press.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
#Load data
data(MCMC_data)

#Summary information for MCMC output
MCMCsummary(MCMC_data)

#Just 'beta' parameters
MCMCsummary(MCMC_data, params = 'beta')

#Just 'beta[1]', 'gamma[4]', and 'alpha[3]'
#'params' takes regular expressions when ISB = FALSE, square brackets must be escaped with '\\'
MCMCsummary(MCMC_data, params = c('beta\\[1\\]', 'gamma\\[4\\]', 'alpha\\[3\\]'), ISB = FALSE)

MCMCvis documentation built on Jan. 11, 2018, 9:03 a.m.