compare.samplers: Compare MCMC samplers on distributions

Description Usage Arguments Details Value Sampler calling convention References See Also

View source: R/compare-samplers.R


Simulate a set of distributions with a set of samplers and tuning parameters


compare.samplers(sample.size, dists, samplers, tuning = 1,
                 trace = TRUE, seed = 17, = 0.2)



An integer specifying how long a chain to simulate.


A list of scdist objects (often generated by make.dist) specifying the probability distributions to simulate.


A list of sampler functions. See the section “Sampler calling convention”.


A numeric vector of tuning parameters


A logical indicating whether a message should be printed when a chain completes (useful for large simulations).


If not null, the random seed is set to this with set.seed before each chain and restored afterwards. This makes each chain individually replicable, useful when debugging.

Fraction of chain to discard before computing autocorrelation time.


compare.samplers runs a single Markov chain simulation of length sampler.size size for each combination of the elements of dists, samplers, and tuning. Each chain starts at a point generated by the initial member of the distribution object, or a point uniformly drawn from the unit hypercube if initial is not defined. It returns a data frame with one row per simulation so that performance of the methods can be compared on the various distributions. The simplest way to visualize the results is with the comparison.plot function.

For an example of the use of this method, see the “Introduction to SamplerCompare” vignette. For discussion of the ideas behind it, see Thompson (2010).


A data frame with columns dist, dist.expr, ndim, sampler, sampler.expr, tuning, act, act.025, act.975, act.y, act.y.025, act.y.975, evals, grads, cpu, err, and aborted. Each row represents a single simulation.

Sampler calling convention

Sampler functions passed to compare.samplers should be of the form:

sampler(target.dist, x0, sample.size, tuning)

target.dist is a scdist object representing the distribution to sample from; see make.dist for more information on these. x0 is the initial state of the chain; it must be a numeric vector of length target.dist$ndim. sample.size is the desired length of the chain, passed down from compare.samplers. tuning is a scalar tuning parameter from the vector passed to compare.samplers.

Sampler functions should return a list with elements X, evals, and (optionally) grads. X should be a matrix with target.dist$ndim columns and sample.size rows. If for some reason it is necessary to abort the chain, returning fewer rows is acceptable. evals and grads indicate the number of calls to target.dist$log.density and target.dist$grad.log.density respectively.

Sampler functions must have a name attribute with a human-readable name for the MCMC method. If desired, they may also have a name.expression attribute containing a more nicely-formatted version of the name in plotmath format.

See the vignette “Introduction to SamplerCompare” for an example of a function that implements this interface.


Thompson, M. B. (2010), Graphical comparison of MCMC performance, University of Toronto Dept. of Statistics technical report no. 1010.

Thompson, M. B. (2011), “Introduction to SamplerCompare,” Journal of Statistical Software 43(12):1-10, doi: 10.18637/jss.v043.i12.

See Also

make.dist, comparison.plot, ar.act, “Introduction to SamplerCompare” (vignette)

SamplerCompare documentation built on Oct. 22, 2021, 9:14 a.m.