Plots.jl

Documentation for Plots.jl ↗

FlexiChains defines a collection of plot recipes which allows you to use the Plots.jl ecosystem to visualise chains. In particular, to access these you will want to load StatsPlots.jl:

julia

using StatsPlots

Plot types

What kind of plot you get in when using Plots.jl is controlled mainly by the seriestype keyword argument. For example, plot(..., seriestype=:histogram) will produce a histogram. In fact, calling histogram(...) simply redirects to plot(..., seriestype=:histogram).

The following series types are supported for FlexiChain objects.

`seriestype=`	Equivalent function	Description
`:traceplot`	`FlexiChains.Plots.traceplot`	Trace plot of samples
`:histogram`	`Plots.histogram`	Histogram of samples
`:density`	`Plots.density`	Kernel density estimate of samples
`:mixeddensity`	`FlexiChains.Plots.mixeddensity`	Density plot or histogram, depending on whether the parameter is continuous or discrete
`:meanplot`	`FlexiChains.Plots.meanplot`	Running mean of samples
`:autocorplot`	`FlexiChains.Plots.autocorplot`	Autocorrelation of samples
`:traceplot_and_density`	`Plots.plot` (with no `seriestype` argument)	Trace plot and mixed density side-by-side
`:rankplot`	`FlexiChains.Plots.rankplot` with `overlay=false`	Rank plot with separate histograms per chain
`:rankplot_overlay`	`FlexiChains.Plots.rankplot` with `overlay=true`	Rank plot with all chains' data overlaid

There is currently one exception to this: StatsPlots.cornerplot is manually overloaded because it does not use the usual seriestype mechanism.

Identifier conflicts

Please note that the identifiers traceplot, meanplot, mixeddensity, and autocorplot are also exported by MCMCChains.jl (which uses Plots.jl as its backend), as well as the FlexiChains.Makie submodule. If you have imported more than one of these modules, you will need to disambiguate which function you want to use by prefixing it with the module name, e.g. FlexiChains.Plots.traceplot.

General interface

The above plotting functions should be called with the following signature:

julia

plotfunc(chn, param_or_params; pool_chains::Bool=false, kwargs...)

Positional arguments

chn is a FlexiChain object.
param_or_params is optional, and can be anything that is used to index into a chain. If not provided, all parameters in the chain will be plotted.

Keyword arguments

If pool_chains=true, then samples from all chains are concatenated before plotting densities or histograms. Otherwise, each chain is plotted separately.
Some plotting functions like autocorplot and rankplot have additional keyword arguments which control the details of the plot; please see the docstrings for those functions for more details.
Other keyword arguments are passed through to the underlying Plots.jl functions which allow you to, for example, control the appearance of the plot.

Setup

Here, we demonstrate the plotting features with a typical chain sampled from a Turing model. However, the general principles are applicable to any FlexiChain object.

We'll make a model with different types of parameters (continuous, discrete, and vector-valued).

julia

using FlexiChains, StatsPlots, Turing

import FlexiChains.Plots as FP # For the plotting functions.

@model function f()
    x ~ Normal()
    y ~ Poisson(3)
    z ~ MvNormal(zeros(2), I)
end

chn = sample(
    f(),
    MH(),
    MCMCThreads(),
    1000,
    3;
    discard_initial=100,
    chain_type=VNChain,
    progress=false,
)

╭─FlexiChain (1000 iterations, 3 chains) ──────────────────────────────────────╮
│ ↓ iter  = 101:1100                                                           │
│ → chain = 1:3                                                                │
│                                                                              │
│ Parameters (3) ── VarName                                                    │
│  Float64          x                                                          │
│  Int64            y                                                          │
│  Vector{Float64}  z (2,)                                                     │
│                                                                              │
│ Extras (4)                                                                   │
│  Bool     accepted                                                           │
│  Float64  logprior, loglikelihood, logjoint                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

Default plot

Calling plot(chn) produces a trace plot and mixed density side-by-side for each parameter.

Notice that the chain has not split z up into z[1] and z[2]. However, when plotting, it will be automatically split up for you. Also notice that Extra keys, like the log probabilities, are not plotted by default.

RecipesBase.plot Function

julia

Plots.plot(
    chn::FlexiChain[, param_or_params];
    pool_chains=false,
    kwargs...
)

Plot a FlexiChain using Plots.jl. By default, this produces a trace plot and mixed density side-by-side for each parameter.

If no parameters are specified, this will plot all parameters in the chain. Note that non-parameter, i.e. Extra, keys are excluded by default. If you want to plot all keys, you can explicitly pass all keys with plot(chn, :).

Other keyword arguments are forwarded to the underlying Plots.jl functions.

Plots.jl ​

Plot types ​

General interface ​

Setup ​

Default plot ​

Trace plots ​

Density plots ​

Histograms ​

Running mean plots ​

Rank plots ​

Autocorrelation plots ​

Mixed density plots ​

Corner plots ​

Violin plots ​

Plots.jl

Plot types

General interface

Setup

Default plot

Trace plots

Density plots

Histograms

Running mean plots

Rank plots

Autocorrelation plots

Mixed density plots

Corner plots

Violin plots