v0.7.2

FlexiChains v0.7.2

Diff since v0.7.1

Add compatibility with DocStringExtensions@0.10.

Merged pull requests:

• Bump JuliaRegistries/TagBot from 1.25.11 to 1.25.15 (#402) (@dependabot[bot])
• Bump julia-actions/setup-julia from 3.0.2 to 3.0.3 (#403) (@dependabot[bot])
• Bump julia-actions/cache from 3.3.0 to 3.5.0 (#404) (@dependabot[bot])
• Add DocStringExtensions@0.10 (#406) (@penelopeysm)
• [skip ci] Bump patch (#407) (@penelopeysm)

v0.7.1

FlexiChains v0.7.1

Diff since v0.7.0

Fixes a bug in pushforward_discrete so that this function now applies custom settings for alpha_limits instead of always using the default.
The default setting for alpha_limits is now listed in the docstrings of all three pushforward_ functions.

Merged pull requests:

• Harmonise plotting coverage defaults (#397) (@BJMCox)
• Fix diagnostics CI with MCMCDiagnosticTools 0.3.20 (#398) (@BJMCox)
• Check refimages and docs fix (#399) (@simonsteiger)
• Use custom alpha_limits in pushforward_discrete (#400) (@simonsteiger)

Closed issues:

• Add rstar (R* convergence diagnostic) (#125)
• Check for outdated refimages (#395)
• Harmonise coverage intervals (#396)

v0.7.0

FlexiChains v0.7.0

Diff since v0.6.44

v0.7 is a fairly large release of FlexiChains containing breaking changes.

Changes to core types

Extra is no longer parametric. Its name must be a Symbol, regardless of the chain's parameter key type.

FlexiChains now uses the VarName, VarNamedTuple, and Draw types defined in VarNames.jl, instead of the versions previously defined in AbstractPPL and DynamicPPL.
This allows for a good amount of code simplification as previously any VarNamedTuple-specific functionality had to rely on DynamicPPL, which was an unnecessarily large dependency.

In order to not completely break users, the old code based on AbstractPPL and DynamicPPL types has been retained for compatibility.
However, please note that VNChain is now aliased to the new type, i.e., FlexiChain{VarNames.VarName}.
Until and unless Turing itself updates its codebase (please see this issue), Turing users should stick to FlexiChains 0.6 where possible (this will be enforced by compatibility bounds).

If you are only using Turing, it is unlikely that you will have FlexiChains v0.7 in your environment.
However, if for some reason you need to use FlexiChains 0.7, please:

• update your code to use FlexiChain{AbstractPPL.VarName} instead of VNChain
• if you need to convert to/from the new VNChain, you can use the FlexiChains.upgrade and FlexiChains.downgrade conversion functions

Apart from this one change, everything else should still work seamlessly.
If/when Turing migrates to using VarNames.jl, the two aliases can be unified.

Pushforward plot functions

The keyword arguments of the plotting functions to create pushforward visualisations (pushforward_hist, pushforward_continuous, pushforward_discrete) have been changed:

• the baseline keyword argument has been deleted from pushforward_continuous and pushforward_discrete. As an alternative, we recommend using lines! or scatter! to overlay baseline values on the pushforward plot.
• the residual keyword argument has been deleted from pushforward_continuous and pushforward_discrete. As an alternative, we recommend using transform_values to calculate residuals inside the FlexiChain and to then plot this new parameter using the respective pushforward_ function.
• quantiles keyword argument has been renamed to levels across all pushforward functions and matches how forestplot's levels keyword argument works.

Stacking of array-valued parameters

Previously, if you had a parameter whose value was a DimArray, accessing its data (i.e., chain[key]) would automatically stack the parameter's dimensions with the iteration and chain dimensions.
This behaviour has been removed now; you must explicitly request stacking by passing stack=true to getindex, i.e., chain[key, stack=true].

Removal of deprecated functions

The deprecated top-level plotting functions have been removed.
Please use the versions in the FlexiChains.Plots and FlexiChains.Makie submodules instead:

• FlexiChains.traceplot, FlexiChains.mixeddensity, FlexiChains.meanplot, FlexiChains.rankplot, and FlexiChains.autocorplot (and their mutating versions) are now FlexiChains.Plots.traceplot etc.
• FlexiChains.mtraceplot, FlexiChains.mmixeddensity, FlexiChains.mmeanplot, FlexiChains.mrankplot, and FlexiChains.mautocorplot (and their mutating versions) are now FlexiChains.Makie.traceplot etc.

The deprecated positional signatures values_at(chn, iter, chain[, Tout]) and parameters_at(chn, iter, chain[, Tout]) have been removed.
Please use the keyword-argument forms values_at(chn[, Tout]; iter=..., chain=...) and parameters_at(chn[, Tout]; iter=..., chain=...) instead.

For FlexiChain{Symbol}s without a stored structure, parameters_at (and therefore rand(chn; parameters_only=true)) now returns a NamedTuple by default instead of an OrderedDict{Symbol}.
The two are isomorphic, but NamedTuples are more ergonomic to work with.
To restore the old behaviour, pass OrderedDict as the output type, i.e. parameters_at(chn, OrderedDict; iter=..., chain=...).

FlexiChains.FlexiChain(::MCMCChains.Chains) has been removed; please use
FlexiChains.from_mcmcchains instead.

Tables.jl output for single-statistic summaries

When converting a FlexiSummary with a dropped stat dimension (e.g. the output of mean(chn)) to a table, the statistic column is now named after the statistic (e.g. mean), rather than the generic stat.
For example, DataFrame(mean(chn)) now has columns param and mean.

split_interval is now the default for hdi and eti

PosteriorStats.hdi(::FlexiChain) and PosteriorStats.eti(::FlexiChain) now default to split_interval=true, i.e., the returned FlexiSummary has separate hdi_lower / hdi_upper (or eti_lower / eti_upper) statistics instead of a single hdi (or eti) statistic containing ClosedIntervals.
To restore the old behaviour, pass split_interval=false.

When using a multimodal HDI method (e.g. method=:multimodal), intervals cannot be split, so the unsplit FlexiSummary is returned along with a warning. Pass split_interval=false to silence the warning.

FlexiChains.collapse now requires CollapseFunctions

collapse now accepts a vector of CollapseFunctions instead of plain functions or (name::Symbol, f) tuples. Previously, collapsing over both dimensions flattened samples into a vector, discarding chain identity and requiring special handling for MCMC diagnostics (see the v0.6.40 bug fix).

A CollapseFunction holds a statistic name and three functions for dims=:both, :chain, and :iter. Each receives the full (iter, chain) sample matrix for a key. Setting a function to nothing disables that dimension; requesting it throws an ArgumentError. Returning an output of the wrong size throws a DimensionMismatch.

Two shortcut constructors cover common uses, each accepting ([name::Symbol,] f, args...; kwargs...) (the name defaults to Symbol(f)):

• FlexiChains.CollapseFunctionVec: for vector-to-scalar functions, such as mean or quantile. Preserves the previous behavior.
• FlexiChains.CollapseFunctionDiagnostic: applies diagnostics to the full matrix for :both or separately to each chain for :iter. Does not support :chain.

To migrate, replace:

collapse(chn, [f, (:name, g)])

with:

collapse(
    chn,
    [FlexiChains.CollapseFunctionVec(f), FlexiChains.CollapseFunctionVec(:name, g)],
)

FlexiChains.ChainDimAware has been removed; use FlexiChains.CollapseFunctionDiagnostic instead.

ess, rhat, and mcse now throw an ArgumentError for FlexiChains with dims=:chain: computing these diagnostics across chains at each iteration is not meaningful. All other summary functions (mean, summarystats, PosteriorStats.hdi, etc.) are unchanged.

quantile(chn, ps::AbstractVector; dims=:iter) (or dims=:chain) previously returned only missing values; it now returns a vector of quantiles for each chain (or iteration).

New summary functions: autocor and cor

autocor(chain; lags=[1, 5, 10, 50]) calculates the autocorrelation of each parameter at the given lags.
It returns a FlexiSummary with one statistic per lag, named lag1, lag5, and so on.
Autocorrelation is always computed within each chain; by default the per-chain values are averaged, and dims=:iter reports them separately for each chain.

cor(chain) calculates the Pearson correlation matrix between all parameters.
Since the result is a matrix over pairs of parameters, it is returned as a DimArray with two param dimensions rather than a FlexiSummary.
dims=:iter computes a separate correlation matrix for each chain.

changerate now accepts a dims keyword.
Its default behaviour, dims=:both, is to now compute per-chain changerates and average them across chains, like autocor above.
To restore the old behaviour, specify dims=:iter.

New diagnostic: rstar

rstar([rng,] classifier, chain) computes the R* convergence diagnostic of Lambert & Vehtari (2022), by forwarding the chain's Real-valued parameters to MCMCDiagnosticTools.rstar.
The classifier must be an MLJ model; depending on whether it is probabilistic or deterministic, either a distribution of R* or a single R* value is returned.

PosteriorDB.jl integration

A new function, FlexiChains.from_posteriordb(ref), loads a PosteriorDB.ReferencePosterior into a FlexiChain{VarName}.
Vector-valued parameters, which PosteriorDB stores as separate scalar entries using Stan's naming convention (e.g. theta[1], ..., theta[8]), are recombined into a single vector-valued parameter (e.g. @vn(theta)).
There is also a convenience method, from_posteriordb(::PosteriorDB.PosteriorDatabase, model::String), which directly loads the reference posterior for the given model (or throws if it does not have a reference posterior).

FlexiChains.from_posteriordb_ref, which returned a FlexiChain{String} with one key per scalar entry, has been removed in favour of from_posteriordb.

Pigeons.jl conversions

FlexiChains.from_pigeons now returns a VNChain rather than a SymChain for non-DynamicPPL models.

Stan conversions

The FlexiChain{Symbol}(::StanSample.SampleModel) constructor has been replaced by FlexiChains.from_stansample(::StanSample.SampleModel), to match the other from_* conversion functions.

FlexiChains.from_stan_csv and FlexiChains.from_stansample now accept an optional key_spec argument, in the same way as FlexiChains.from_mcmcchains.
This lets you construct a...

v0.6.44

FlexiChains v0.6.44

Diff since v0.6.43

Documentation updates only.

Merged pull requests:

• V0.7 rstar (#377) (@rsenne)
• Add an example chain, and do a pass over the docs for 0.7. (#378) (@penelopeysm)
• Restrict Extra names to symbols (#385) (@BJMCox)
• Don't update root of gh-pages from docs preview builds (#389) (@penelopeysm)
• samplemodel fix (#390) (@penelopeysm)
• Fix Pigeons docs, consolidate tests on v0.6 (#391) (@penelopeysm)
• make from_pigeons use varname by default (#392) (@penelopeysm)
• Actually run the tests (#393) (@penelopeysm)

Closed issues:

• Fix docs and tests to not use sample() (#194)
• Make Extras always contain symbols (#383)
• Automatically infer structures where possible (#384)
• Make from_pigeons return VNChain instead (#387)
• change FlexiChain{Symbol}(::SampleModel) (#388)

v0.6.43

FlexiChains v0.6.43

Diff since v0.6.42

Added changerate to compute per-chain parameter change rates.

Added a weights keyword to rand for weighted sampling from chains.

Merged pull requests:

• More overhauls for v0.7 (#373) (@penelopeysm)
• Add per-chain parameter change rates (#379) (@BJMCox)
• Add weighted sampling from chains (#380) (@BJMCox)

Closed issues:

• Add autocor (autocorrelation at specific lags) (#121)
• Add cor (posterior correlation matrix) (#123)
• Add changerate (parameter change rate) (#142)
• Weighted sampling from chain (#146)
• Consolidate tests (#275)
• Improve PosteriorDB extension (#330)

v0.6.42

FlexiChains v0.6.42

Diff since v0.6.41

Improved the performance of _split_varnames (internal but widely used in many other functions), as well as the conversion of FlexiChain and FlexiSummary objects to (Dim)Arrays.

Merged pull requests:

• more efficient flattening to (Dim)Array (#361) (@tiemvanderdeure)
• Merge main into v0.7 (port #355) (#362) (@rsenne)
• Remove deprecated top-level plotting functions (#363) (@rsenne)
• Remove deprecated positional values_at/parameters_at signatures (#365) (@rsenne)
• Format. (#366) (@rsenne)
• V0.7 collapse function (#367) (@rsenne)
• Return NamedTuple from parameters_at for Symbol chains by default (#369) (@rsenne)
• Use stored stat name in Tables.jl output for single-stat summaries (#370) (@rsenne)

Closed issues:

• Redesign landing page? (#293)
• parameters_at(::SymChain, ...) should probably give NamedTuple by default (#323)
• Port #355 to v0.7 (#358)
• Roadpath to 0.7? (#360)

v0.6.41

FlexiChains v0.6.41

Diff since v0.6.40

Improved the printing of FlexiSummary objects with many parameters.

Merged pull requests:

• improve printing of flexisummary (#344) (@tiemvanderdeure)
• Bump the all-julia-packages group across 2 directories with 9 updates (#357) (@dependabot[bot])

Closed issues:

• unicode parameter issue when loading onto another machine (#245)
• Improve pushforward_continuous (#334)

v0.6.40

FlexiChains v0.6.40

Diff since v0.6.39

Fixed a bug where R-hat, ESS, and MCSE were computed incorrectly if there were more than 2 chains in the FlexiChain.

Merged pull requests:

• [skip ci] Restrict test compat for OrderedCollections (#350) (@penelopeysm)
• Test on 1.12 as well (#351) (@penelopeysm)
• Fix Rhat/ESS/MCSE computations (#355) (@rsenne)
• Patch bump and changelog (#356) (@penelopeysm)

Closed issues:

• Serious R_hat underscoring. (#354)

v0.6.39

What's Changed

• Bump JuliaRegistries/TagBot from 1.25.10 to 1.25.11 by @dependabot[bot] in #342
• Bump julia-actions/cache from 3.2.0 to 3.3.0 by @dependabot[bot] in #343
• Only run Aqua on linux by @penelopeysm in #346
• Fix missing import by @penelopeysm in #348
• Bump the all-julia-packages group across 3 directories with 1 update by @dependabot[bot] in #349
• [skip ci] Restrict test compat for OrderedCollections by @penelopeysm in #350

Full Changelog: v0.6.38...v0.6.39

v0.6.38

What's Changed

• Transfer to organisation by @penelopeysm in #333
• Allow DimArray converters to not split_varnames by @penelopeysm in #341

Full Changelog: v0.6.37...v0.6.38