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:

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:

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

We'll begin by making a model with different types of parameters (continuous, discrete, and vector-valued) to demonstrate the plotting functions. We could use the familiar example chain from the other docs pages, but that one is too small to demonstrate some of these plots well.

using FlexiChains, StatsPlotsimport FlexiChains.Plots as FP # For the plotting functions.using FlexiChains: FlexiChain, Parameter, Extra, OrderedDictchn = FlexiChain{VarName}(    500,    2,    OrderedDict(        Parameter(@vn(float)) => randn(500, 2),        Parameter(@vn(int)) => rand(1:5, 500, 2) .* 3 .+ 2,        Parameter(@vn(vect)) => [[randn(), randn() - 1.0] for _ in 1:500, _ in 1:2],        Extra(:an_extra) => randn(500, 2),    ),)

╭─FlexiChain (500 iterations, 2 chains) ───────────────────────────────────────╮
│ ↓ iter  = 1:500                                                              │
│ → chain = 1:2                                                                │
│                                                                              │
│ Parameters (3) ── VarName                                                    │
│  Float64          float                                                      │
│  Int64            int                                                        │
│  Vector{Float64}  vect (2,)                                                  │
│                                                                              │
│ Extras (1)                                                                   │
│  Float64  an_extra                                                           │
╰──────────────────────────────────────────────────────────────────────────────╯

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

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.