Chain types and utility functions for MCMC simulations
Clone or download
Latest commit a3821eb Oct 12, 2018


Build Status Build status Coverage Status

Implementation of Julia types for summarizing MCMC simulations and utility functions for diagnostics and visualizations.


The following simple example illustrates how to use Chain to visually summarize a MCMC simulation:

using MCMCChain
using StatPlots


# Define the experiment
n_iter = 500;
n_name = 3;
n_chain = 2;

# experiment results
val = randn(n_iter, n_name, n_chain) .+ [1, 2, 3]';
val = hcat(val, rand(1:2, n_iter, 1, n_chain));

# construct a Chains object
chn = Chains(val);

# visualize the MCMC simulation results
p1 = plot(chn)
p2 = plot(chn, colordim = :parameter)

# save to a png file
savefig(p1, "demo-plot-parameters.png")
savefig(p2, "demo-plot-chains.png")

This code results in the visualizations shown below. Note that the plot function takes the additional arguments described in the Plots.jl package.

Summarize parameters  Summarize chains
plot(chn; colordim = :chain) plot(chn; colordim = :parameter)
p1 p2


Chains type

# construction of a Chains object
Chains(iterations::Int, params::Int;
    start = 1, thin = 1, chains = 1,
    names = String[])

# construction of a Chains object using an
# iteration * params * chains
# array (values).
Chains(values::Array{T, 3};
    start = 1, thin = 1, chains = 1,
    names = String[])

# Indexing a Chains object
chn = Chains(...)
chn_param1 = chn[:,2,:] # returns a new Chains object for parameter 2
chn[:,2,:] = ... # set values for parameter 2

Convergence Diagnostics functions

Discrete Diagnostic

Options for method are [:weiss, :hangartner, :DARBOOT, MCBOOT, :billinsgley, :billingsleyBOOT]

discretediag(c::AbstractChains; frac=0.3, method=:weiss, nsim=1000)

Gelman, Rubin, and Brooks Diagnostics

gelmandiag(c::AbstractChains; alpha=0.05, mpsrf=false, transform=false)

Geweke Diagnostic

gewekediag(c::AbstractChains; first=0.1, last=0.5, etype=:imse)

Heidelberger and Welch Diagnostics

heideldiag(c::AbstractChains; alpha=0.05, eps=0.1, etype=:imse)

Raftery and Lewis Diagnostic

rafterydiag(c::AbstractChains; q=0.025, r=0.005, s=0.95, eps=0.001)


# construct a plot
plot(c::AbstractChains, seriestype = (:traceplot, :mixeddensity))
plot(c::AbstractChains; ptypes = [TracePlot, MixedDensityPlot]) # deprecated
plot(c::AbstractChains; [:trace, :mixeddensity]) # deprecated

# construct trace plots
plot(c::AbstractChains, seriestype = :traceplot)
plot(c::AbstractChains, TracePlot) # deprecated
plot(c::AbstractChains, :trace) # deprecated

# construct running average plots
plot(c::AbstractChains, seriestype = :meanplot)
plot(c::AbstractChains, MeanPlot) # deprecated
plot(c::AbstractChains, :mean) # deprecated

# construct density plots
plot(c::AbstractChains, seriestype = :density)
plot(c::AbstractChains, DensityPlot) # deprecated
plot(c::AbstractChains, :density) # deprecated

# construct histogram plots
plot(c::AbstractChains, seriestype = :histogram)
plot(c::AbstractChains, HistogramPlot) # deprecated
plot(c::AbstractChains, :histogram) # deprecated

# construct mixed density plots
plot(c::AbstractChains, seriestype = :mixeddensity)
plot(c::AbstractChains, MixedDensityPlot) # deprecated
plot(c::AbstractChains, :mixeddensity) # deprecated

# construct autocorrelation plots
plot(c::AbstractChains, seriestype = :autocorplot)
plot(c::AbstractChains, AutocorPlot) # deprecated
plot(c::AbstractChains, :autocor) # deprecated

License Notice

Note that this package heavily uses and adapts code from the Mamba.jl package licensed under MIT License, see