FlexiChains.jl

Appearance

Overview ​

FlexiChains.jl provides a rich data structure for storing and analysing Markov chain Monte Carlo (MCMC) output.

julia
using Turing, FlexiChains
@model function f()
    x ~ Normal()
    y ~ Poisson(3.0)
    z ~ MvNormal([x + y, x - y], I)
end
chain = sample(f(), Prior(), MCMCSerial(), 1000, 4)
╭─FlexiChain (1000 iterations, 4 chains) ──────────────────────────────────────╮
│ ↓ iter  = 1:1000                                                             │
│ → chain = 1:4                                                                │
│                                                                              │
│ Parameters (3) ── VarName                                                    │
│  Float64          x                                                          │
│  Int64            y                                                          │
│  Vector{Float64}  z (2,)                                                     │
│                                                                              │
│ Extras (3)                                                                   │
│  Float64  logprior, loglikelihood, logjoint                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

Primary features ​

Type and structure fidelity ​

FlexiChains preserves the original shapes of your samples: all Julia types are faithfully stored without modification. The example Turing.jl model above yields a FlexiChain where each x is a Float64, each y is an Int, and each z is a Vector{Float64}.

This is in contrast to many other representations which flatten all samples into a single Array{Float64}.

Diverse input sources ​

FlexiChains is the default chain type for Turing.jl since v0.45 of Turing.

You can also construct a FlexiChain from a variety of other sources, including ParallelMCMC.jl, Pigeons.jl, Stan CSV files, MCMCChains.jl, or PosteriorDB.jl.

Expressive indexing ​

You can access data stored in chains in a variety of ways, using the full power of DimensionalData.jl selectors.

julia
chain[@varname(x), iter=101:End, chain=2]
┌ 900-element DimArray{Float64, 1} Parameter(x) ┐
├───────────────────────────────────────────────┴────────── dims ┐
  ↓ iter Sampled{Int64} 101:1000 ForwardOrdered Regular Points
└────────────────────────────────────────────────────────────────┘
  101   0.944378
  102   0.393447
  103   0.831016
  104   1.46884
  105  -1.74298
    ⋮  
  996   0.660304
  997  -1.65671
  998   0.354678
  999  -0.398476
 1000   2.12553

Downstream analysis ​

FlexiChains provides a number of tools for statistical analysis, including:

julia
ss = summarystats(chain)
╭─FlexiSummary (9 statistics) ─────────────────────────────────────────────────╮
│   iter    collapsed                                                          │
│   chain   collapsed                                                          │
│ ↓ stat  = [mean, std, mcse, ess_bulk, ess_tail, rhat, q5, q50, q95]          │
│                                                                              │
│ Parameters (4) ── VarName                                                    │
│  Float64  x, y, z[1], z[2]                                                   │
│                                                                              │
│ Extras (3)                                                                   │
│  Float64  logprior, loglikelihood, logjoint                                  │
│                                                                              │
│ Summary                                                                      │
│  param  mean     std     mcse    …  rhat    q5       q50      q95            │
│  x      -0.0049  0.9974  0.0166     1.0001  -1.6702  0.0073   1.6345         │
│  y      2.9943   1.7499  0.0277     1.0002  1.0000   3.0000   6.0000         │
│  z[1]   2.9578   2.2236  0.0358     0.9995  -0.4979  2.8081   6.8878         │
│  z[2]   -3.0118  2.2761  0.0351     1.0004  -6.8883  -2.8896  0.4969         │
╰──────────────────────────────────────────────────────────────────────────────╯
julia
ss[@varname(x), stat=:mean]
-0.004868790074474263

For added versatility you can also convert a FlexiChain into a DimArray or a DataFrame.

Plotting ​

Many visualisation functions with both Makie.jl and Plots.jl backends are provided, along with a PairPlots.jl extension.

julia
using PairPlots, CairoMakie
pairplot(chain)