Makie.jl

FlexiChains provides a number of functions to visualise chains using the Makie plotting library.

Parts of the Makie integration in FlexiChains are heavily lifted from the (unreleased) ChainsMakie.jl package (there have also been many further additions since then!). This includes some custom code to generate (e.g.) shared legends, which leads to slightly nicer plots than for Plots.jl (on top of Makie generally yielding nicer plots out of the box).

Note

You can also use Makie as a backend to make pair / corner plots! This requires loading a Makie backend as well as PairPlots.jl. Please see the PairPlots.jl integration section for more details.

General interface

For all functions plotfunc shown in the table of the plotting page, you can use the following invocation:

Generate an entire Makie.Figure. This automatically generates a complete plot for you, including a legend.
```
plotfunc(    chn,    param_or_params;    figure=(;),    axis=(;),    legend=(;),    legend_position=:bottom,    kwargs...,)
```
param_or_params can be anything used to index into a chain (single parameters are also accepted). It can also be omitted, in which case all parameters in the chain will be plotted.
Most keyword arguments are passed to the underlying Makie plotting functions, but there are some special ones which are handled by FlexiChains. For more information about these, see the customisation section below.

For functions which create only a single plot per parameter (e.g. density, or traceplot), the following options are also available. The intention is to allow you to build more complex figures using these as building blocks:

Plot a single parameter onto an existing Makie.Axis object: this uses the 'mutating' version with an exclamation mark.
If ax is not specified, uses the current axis. Colours are handled the same way as above. param must be a single parameter.
```
plotfunc!([ax]chn, param; kwargs...)
```
Plot a single parameter onto a Makie grid position. This constructs a Makie.Axis for you, and as before you can pass options via the axis keyword argument. Colours are handled the same way as above. param must be a single parameter.
```
f = Figure()gp = f[1, 1]plotfunc!(gp, chn, param; axis=(;), kwargs...)
```

Setup

Here, we set up a chain with different types of parameters (continuous, discrete, and vector-valued). 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, CairoMakieimport FlexiChains.Makie as FM  # 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 Makie.plot(chn) produces a trace plot and mixed density side-by-side for each parameter.

Makie.plot — Function

Makie.plot(
    chn::FC.FlexiChain,
    param_or_params = FC.Parameter.(FC.parameters(chn));
    kwargs...,
)

Plot the parameters in a FlexiChain using Makie. For each parameter, a trace plot and a density plot are created.

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 Makie.plot(chn, :).

Keyword arguments

pool_chains::Bool: whether to pool data from all chains into a single plot, or to plot each chain separately. Defaults to false.
figure::NamedTuple: Additional keyword arguments passed to the Makie.Figure constructor.
axis::NamedTuple: Additional keyword arguments passed to the Makie.Axis constructor for each subplot.
legend::NamedTuple: Additional keyword arguments passed to the Makie.Legend constructor, if the legend is added.
legend_position::Symbol: Position of the legend. This can be either :right, :bottom or :none for no legend.
layout: either nothing (the default), or a tuple of (nrows, ncols) specifying the grid layout for the subplots.

All other keyword arguments are passed to the original Makie plotting function.