R Graphical Manual

Browse All

Last data update: 2014.03.03

R: Generate MCMC samples for posterior distributions

BESTmcmc

R Documentation

Generate MCMC samples for posterior distributions

Description

This function is the core of the BEST package. It calls JAGS and passes a description of the model, priors, and data, then retrieves and returns the MCMC samples for the parameters.

Usage

  
BESTmcmc(y1, y2 = NULL, priors = NULL, doPriorsOnly = FALSE,
  numSavedSteps = 1e+05, thinSteps = 1, burnInSteps = 1000,
	verbose=TRUE, rnd.seed=NULL, parallel=NULL)

Arguments

`y1`	a numeric vector of data values.
`y2`	a vector of values for a second group, or NULL if there is only one group of observations.
`priors`	an optional list of values controlling the priors, see Details.
`doPriorsOnly`	if TRUE, `BESTmcmc` returns MCMC chains representing the prior distributions, not the posterior distributions for your data set.
`numSavedSteps`	the number of MCMC observations to be returned.
`thinSteps`	thinning rate. If set to n > 1, n steps of the MCMC chain are calculated for each one returned. This is useful if autocorrelation is high.
`burnInSteps`	number of steps to discard as burn-in at the beginning of the chain.
`verbose`	if FALSE, output to the R Console is suppressed.
`rnd.seed`	a positive integer (or NULL): the seed for the random number generator, used to obtain reproducible samples if required. Values generated in different versions of BEST may differ.
`parallel`	if NULL or TRUE and > 3 cores are available, the MCMC chains are run in parallel. (If TRUE and < 4 cores are available, a warning is given.)

Details

The function generates vectors of random draws from the posterior distributions of the group means (μ) and standard deviations (σ), as well as the measure of normality (ν). The procedure uses a Bayesian MCMC process implemented in JAGS (Plummer 2003).

If priors = NULL, broad priors as described by Kruschke (2013) are used. The user can specify priors for all parameters by including elements in the priors list:
μ : population means have separate normal priors, with mean muM and standard deviation muSD;
σ : population standard deviations have separate gamma priors, with mode sigmaMode and standard deviation sigmaSD;
ν : the normality parameter has a gamma prior with mean nuMean and standard deviation nuSD. (Versions before 0.4.0 constrained nu to be >1.)

If there are 2 groups of observations, muM, muSD, sigmaMode, sigmaSD may be vectors of length 2 or scalar, in which case the same value is used for each population. The default priors correspond to list(muM = mean(y), muSD = sd(y)*5, sigmaMode = sd(y), sigmaSD = sd(y)*5, nuMean = 30, nuSD = 30), where y = c(y1, y2).

The model is shown in the diagram below.

Derived parameters, including the differences in means or standard deviations, and effect sizes can be obtained from the results of the BESTmcmc run.

The output from BESTmcmc has class BEST, which has print, plot and summary methods. These permit the extraction and display of credible intervals and proportions of the posterior mass above or below values of interest.

Value

An object of class BEST inheriting from data.frame. If two samples are compared, the output has the following columns:

`mu1, mu2`	simulated observations of means for each population
`sigma1, sigma2`	simulated observations of standard deviations for each population
`nu`	simulated observations of normality parameter

while for a single sample, the columns are mu, sigma, nu.

The output has the following attributes:

`call`	the call to the function.
`Rhat`	the 'potential scale reduction factor'.
`n.eff`	sample size adjusted for autocorrelation.
`data`	a list with elements y1 and y2 containing the original data; y2 may be NULL.
`priors`	a list with the priors used, if the `priors` argument is not NULL.
`doPriorsOnly`	logical, the value of the `doPriorsOnly` argument.

The package provides print, plot and summary methods for BEST objects.

Author(s)

Original code by John K. Kruschke, modified by Mike Meredith.

References

Kruschke, J K. 2013. Bayesian estimation supersedes the t test. Journal of Experimental Psychology: General 142(2):573-603. doi: 10.1037/a0029146

Plummer, Martyn (2003). JAGS: A Program for Analysis of Bayesian Graphical Models Using Gibbs Sampling, Proceedings of the 3rd International Workshop on Distributed Statistical Computing (DSC 2003), March 20-22, Vienna, Austria. ISSN 1609-395X

Examples

## See examples in BEST-package help.