StatsPlots.jl

MCMCChains implements many functions for plotting via StatsPlots.jl.

Simple example

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

using MCMCChains
using StatsPlots

# Define the experiment
n_iter = 100
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, [:A, :B, :C, :D])

# visualize the MCMC simulation results
plot(chn; size=(840, 600))

GKS: cannot open display - headless operation mode active

Default plot for Chains

plot(chn, colordim = :parameter; size=(840, 400))

Note that the plot function takes the additional arguments described in the Plots.jl package.

Mixed density

plot(chn, seriestype = :mixeddensity)

Or, for all seriestypes, use the alternative shorthand syntax:

mixeddensity(chn)

Trace

plot(chn, seriestype = :traceplot)

traceplot(chn)

Running average

meanplot(chn)

Density

density(chn)

Histogram

histogram(chn)

Autocorrelation

autocorplot(chn)

Violin

Violin plots are similar to box plots but also show the probability density of the data at different values, smoothed by a kernel density estimator.

violinplot(chn) # Plotting parameter 1 across all chains

violinplot(chn, 1) # Plotting parameter 1 across all chains

violinplot(chn, :A) # Plotting a specific parameter across all chains

violinplot(chn, [:C, :B, :A]) # Plotting multiple specific parameters across all chains

violinplot(chn, 1, colordim = :parameter) # Plotting chain 1 across all parameters

violinplot(chn, show_boxplot = false) # Plotting all parameters without the inner boxplot

You can also aggregate (pool) samples from all chains for a given parameter by using append_chains = true. This is useful when you want to visualize the overall posterior distribution without distinguishing between individual chains.

violinplot(chn, :A, append_chains = true) # Single parameter, all chains appended

violinplot(chn, append_chains = true) # All parameters, all chains appended

You can also use the plot function with seriestype = :violinplot or seriestype = :violin

plot(chn, seriestype = :violin)

Corner

corner(chn)

Energy Plot

The energy plot is a diagnostic tool for HMC-based samplers (like NUTS) that helps diagnose sampling efficiency by visualizing the energy and energy transition distributions. This plot requires that the chain contains the internal sampler statistics :hamiltonian_energy and :hamiltonian_energy_error.

# First, we generate a chain that includes the required sampler parameters.
n_iter = 1000
n_chain = 4
val_params = randn(n_iter, 2, n_chain)
val_energy = randn(n_iter, 1, n_chain) .+ 20
val_energy_error = randn(n_iter, 1, n_chain) .* 0.5
full_val = hcat(val_params, val_energy, val_energy_error)

parameter_names = [:a, :b, :hamiltonian_energy, :hamiltonian_energy_error]
section_map = (
    parameters=[:a, :b],
    internals=[:hamiltonian_energy, :hamiltonian_energy_error],
)

chn_energy = Chains(full_val, parameter_names, section_map)

# Generate the energy plot (default is a density plot).
energyplot(chn_energy)

# The plot can also be generated as a histogram.
energyplot(chn_energy, kind=:histogram)

For plotting multiple parameters, ridgeline, forest and caterpillar plots can be useful.

Ridgeline

ridgelineplot(chn, [:C, :B, :A])

Forest

forestplot(chn, [:C, :B, :A], hpd_val = [0.05, 0.15, 0.25])

Caterpillar

forestplot(chn, chn.name_map[:parameters], hpd_val = [0.05, 0.15, 0.25], ordered = true)

API

MCMCChains.energyplot — Function

energyplot(chains::Chains; kind=:density, kwargs...)

Generate an energy plot for the samples in chains.

The energy plot is a diagnostic tool for HMC-based samplers like NUTS. It displays the distributions of the Hamiltonian energy and the energy transition (error) to diagnose sampler efficiency and identify divergences.

This plot is only available for chains that contain the :hamiltonian_energy and :hamiltonian_energy_error statistics in their :internals section.

Keywords

kind::Symbol (default: :density): The type of plot to generate. Can be :density or :histogram.

source

MCMCChains.energyplot! — Function

energyplot(chains::Chains; kind=:density, kwargs...)

Generate an energy plot for the samples in chains.

This plot is only available for chains that contain the :hamiltonian_energy and :hamiltonian_energy_error statistics in their :internals section.

Keywords

kind::Symbol (default: :density): The type of plot to generate. Can be :density or :histogram.

source

energyplot(chains::Chains; kind=:density, kwargs...)

Generate an energy plot for the samples in chains.

This plot is only available for chains that contain the :hamiltonian_energy and :hamiltonian_energy_error statistics in their :internals section.

Keywords

kind::Symbol (default: :density): The type of plot to generate. Can be :density or :histogram.

source

MCMCChains.ridgelineplot — Function

ridgelineplot(chains::Chains[, params::Vector{Symbol}]; kwargs...)

Generate a ridgeline plot for the samples of the parameters params in chains.

By default, all parameters are plotted.

Keyword arguments

The following options are available:

fill_q (default: false) and fill_hpd (default: true): Fill the area below the curve in the quantiles interval (fill_q = true) or the highest posterior density (HPD) interval (fill_hpd = true). If both fill_q = false and fill_hpd = false, then the whole area below the curve is filled. If no fill color is desired, it should be specified with series attributes. These options are mutually exclusive.
show_mean (default: true) and show_median (default: true): Plot a vertical line of the mean (show_mean = true) or median (show_median = true) of the posterior density estimate. If both options are set to true, both lines are plotted.
show_qi (default: false) and show_hpdi (default: true): Plot a quantile interval (show_qi = true) or the largest HPD interval (show_hpdi = true) at the bottom of each density plot. These options are mutually exclusive.
q (default: [0.1, 0.9]): The two quantiles used for plotting if fill_q = true or show_qi = true.
hpd_val (default: [0.05, 0.2]): The complementary probability mass(es) of the highest posterior density intervals that are plotted if fill_hpd = true or show_hpdi = true.

Note

If a single parameter is provided, the generated plot is a density plot with all the elements described above.

source

MCMCChains.ridgelineplot! — Function

ridgelineplot(chains::Chains[, params::Vector{Symbol}]; kwargs...)

Generate a ridgeline plot for the samples of the parameters params in chains.

By default, all parameters are plotted.

Keyword arguments

The following options are available:

fill_q (default: false) and fill_hpd (default: true): Fill the area below the curve in the quantiles interval (fill_q = true) or the highest posterior density (HPD) interval (fill_hpd = true). If both fill_q = false and fill_hpd = false, then the whole area below the curve is filled. If no fill color is desired, it should be specified with series attributes. These options are mutually exclusive.
show_mean (default: true) and show_median (default: true): Plot a vertical line of the mean (show_mean = true) or median (show_median = true) of the posterior density estimate. If both options are set to true, both lines are plotted.
show_qi (default: false) and show_hpdi (default: true): Plot a quantile interval (show_qi = true) or the largest HPD interval (show_hpdi = true) at the bottom of each density plot. These options are mutually exclusive.
q (default: [0.1, 0.9]): The two quantiles used for plotting if fill_q = true or show_qi = true.
hpd_val (default: [0.05, 0.2]): The complementary probability mass(es) of the highest posterior density intervals that are plotted if fill_hpd = true or show_hpdi = true.

Note

If a single parameter is provided, the generated plot is a density plot with all the elements described above.

source

ridgelineplot(chains::Chains[, params::Vector{Symbol}]; kwargs...)

Generate a ridgeline plot for the samples of the parameters params in chains.

By default, all parameters are plotted.

Keyword arguments

The following options are available:

fill_q (default: false) and fill_hpd (default: true): Fill the area below the curve in the quantiles interval (fill_q = true) or the highest posterior density (HPD) interval (fill_hpd = true). If both fill_q = false and fill_hpd = false, then the whole area below the curve is filled. If no fill color is desired, it should be specified with series attributes. These options are mutually exclusive.
show_mean (default: true) and show_median (default: true): Plot a vertical line of the mean (show_mean = true) or median (show_median = true) of the posterior density estimate. If both options are set to true, both lines are plotted.
show_qi (default: false) and show_hpdi (default: true): Plot a quantile interval (show_qi = true) or the largest HPD interval (show_hpdi = true) at the bottom of each density plot. These options are mutually exclusive.
q (default: [0.1, 0.9]): The two quantiles used for plotting if fill_q = true or show_qi = true.
hpd_val (default: [0.05, 0.2]): The complementary probability mass(es) of the highest posterior density intervals that are plotted if fill_hpd = true or show_hpdi = true.

Note

If a single parameter is provided, the generated plot is a density plot with all the elements described above.

source

MCMCChains.forestplot — Function

forestplot(chains::Chains[, params::Vector{Symbol}]; kwargs...)

Generate a forest or caterpillar plot for the samples of the parameters params in chains.

By default, all parameters are plotted.

Keyword arguments

ordered (default: false): If ordered = false, a forest plot is generated. If ordered = true, a caterpillar plot is generated.
fill_q (default: false) and fill_hpd (default: true): Fill the area below the curve in the quantiles interval (fill_q = true) or the highest posterior density (HPD) interval (fill_hpd = true). If both fill_q = false and fill_hpd = false, then the whole area below the curve is filled. If no fill color is desired, it should be specified with series attributes. These options are mutually exclusive.
show_mean (default: true) and show_median (default: true): Plot a vertical line of the mean (show_mean = true) or median (show_median = true) of the posterior density estimate. If both options are set to true, both lines are plotted.
show_qi (default: false) and show_hpdi (default: true): Plot a quantile interval (show_qi = true) or the largest HPD interval (show_hpdi = true) at the bottom of each density plot. These options are mutually exclusive.
q (default: [0.1, 0.9]): The two quantiles used for plotting if fill_q = true or show_qi = true.
hpd_val (default: [0.05, 0.2]): The complementary probability mass(es) of the highest posterior density intervals that are plotted if fill_hpd = true or show_hpdi = true.

source

MCMCChains.forestplot! — Function

forestplot(chains::Chains[, params::Vector{Symbol}]; kwargs...)

Generate a forest or caterpillar plot for the samples of the parameters params in chains.

By default, all parameters are plotted.

Keyword arguments

ordered (default: false): If ordered = false, a forest plot is generated. If ordered = true, a caterpillar plot is generated.
fill_q (default: false) and fill_hpd (default: true): Fill the area below the curve in the quantiles interval (fill_q = true) or the highest posterior density (HPD) interval (fill_hpd = true). If both fill_q = false and fill_hpd = false, then the whole area below the curve is filled. If no fill color is desired, it should be specified with series attributes. These options are mutually exclusive.
show_mean (default: true) and show_median (default: true): Plot a vertical line of the mean (show_mean = true) or median (show_median = true) of the posterior density estimate. If both options are set to true, both lines are plotted.
show_qi (default: false) and show_hpdi (default: true): Plot a quantile interval (show_qi = true) or the largest HPD interval (show_hpdi = true) at the bottom of each density plot. These options are mutually exclusive.
q (default: [0.1, 0.9]): The two quantiles used for plotting if fill_q = true or show_qi = true.
hpd_val (default: [0.05, 0.2]): The complementary probability mass(es) of the highest posterior density intervals that are plotted if fill_hpd = true or show_hpdi = true.

source

forestplot(chains::Chains[, params::Vector{Symbol}]; kwargs...)

Generate a forest or caterpillar plot for the samples of the parameters params in chains.

By default, all parameters are plotted.

Keyword arguments

ordered (default: false): If ordered = false, a forest plot is generated. If ordered = true, a caterpillar plot is generated.
fill_q (default: false) and fill_hpd (default: true): Fill the area below the curve in the quantiles interval (fill_q = true) or the highest posterior density (HPD) interval (fill_hpd = true). If both fill_q = false and fill_hpd = false, then the whole area below the curve is filled. If no fill color is desired, it should be specified with series attributes. These options are mutually exclusive.
show_mean (default: true) and show_median (default: true): Plot a vertical line of the mean (show_mean = true) or median (show_median = true) of the posterior density estimate. If both options are set to true, both lines are plotted.
show_qi (default: false) and show_hpdi (default: true): Plot a quantile interval (show_qi = true) or the largest HPD interval (show_hpdi = true) at the bottom of each density plot. These options are mutually exclusive.
q (default: [0.1, 0.9]): The two quantiles used for plotting if fill_q = true or show_qi = true.
hpd_val (default: [0.05, 0.2]): The complementary probability mass(es) of the highest posterior density intervals that are plotted if fill_hpd = true or show_hpdi = true.

source