Stan

From CSV files

FlexiChains has a function to read in chains stored in Stan CSV format:

FlexiChains.from_stan_csv — Function

FlexiChains.from_stan_csv(
    base_path::AbstractString, num_chains::Integer, key_spec=nothing
)::FlexiChain

Reads the Stan CSV files from {base_path}_1.csv through to {base_path}_{num_chains}.csv. This is a convenience method that recognises the fact that CmdStan saves its outputs in this format.

Note

You do not need to provide the underscore before the chain number in the filename! That is, if your files are example_1.csv etc., then base_path should just be "example".

See the other method of from_stan_csv for details of the key_spec argument.

source

FlexiChains.from_stan_csv(
    csv_paths::AbstractVector{<:AbstractString}, key_spec=nothing
)::FlexiChain

Parse a set of Stan CSV files at the given paths.

These files must correspond to a set of compatible chains, i.e., their parameter names, lengths (i.e., number of iterations), and other data should be consistent. This will be the case if they were all drawn from the same call to Stan's sampling. However, note that FlexiChains does only a rudimentary set of checks to ensure consistency: the user should be responsible for ensuring that the CSVs read in are valid.

If key_spec is not provided, columns that end in double-underscores (__) are treated as Extras (the underscores will be stripped), and all other columns as Parameter{Symbol}s, giving a FlexiChain{Symbol}.

If key_spec is provided, it is passed directly to the FlexiChain from-array constructor, and the key type of the resulting FlexiChain is inferred from it. key_spec must cover every column of the CSV files, in order, including the sampler columns (e.g. lp__) that CmdStan writes before the model's own parameters. This lets you, for example, use VarName keys, or group array-valued parameters together: since CmdStan writes arrays in column-major order, Parameter(@vn(Sigma)) => (2, 2) will correctly reconstruct a 2x2 matrix Sigma from the columns Sigma.1.1, Sigma.2.1, Sigma.1.2, Sigma.2.2.

Please see the FlexiChain constructor documentation for details on what key_spec is allowed.

source

This of course assumes that you already have the CSV files on disk somewhere, e.g. if you have run Stan externally.

StanSample.jl

If you are using StanSample.jl you can also read data directly from a SampleModel once you have sampled with it.

Note

This code block is not run, as running it would necessitate setting up CmdStan on GitHub runners.

using StanSample, FlexiChainssm = SampleModel(args...)# Note: this mutates `sm` -- StanSample has a rather unconventional interfacestan_sample(sm; data)chn = FlexiChains.from_stansample(sm)

By default, both from_stansample and from_stan_csv return a FlexiChain{Symbol}, where each column of the CSV is a separate key (e.g. Symbol("theta.1")). If you want VarName keys, or want to group array-valued parameters back together, you can pass a key_spec tuple as the last argument. This works in exactly the same way as for the FlexiChain from-array constructor and the MCMCChains converter. Note that key_spec must also cover the sampler columns that Stan writes first:

using FlexiChains: Parameter, Extra, @vnkey_spec = (    Extra(:lp),    Extra(:accept_stat),    Extra(:stepsize),    Extra(:treedepth),    Extra(:n_leapfrog),    Extra(:divergent),    Extra(:energy),    Parameter(@vn(theta)) => (8,),    Parameter(@vn(mu)),    Parameter(@vn(tau)),)chn = FlexiChains.from_stansample(sm, key_spec)

FlexiChains.from_stansample — Function

FlexiChains.from_stansample(sm::StanSample.SampleModel, key_spec=nothing)::FlexiChain

Convert a StanSample.SampleModel object to a FlexiChain. Sampling must already have been run on sm (e.g. with stan_sample(sm; data)).

This reads the Stan CSV files that StanSample.jl wrote to disk, using FlexiChains.from_stan_csv; see its docstring for details of how columns are converted into keys, and the key_spec argument.

source

If you are using BridgeStan.jl and/or StanLogDensityProblems.jl plus a native Julia sampler, you should check whether there is an integration for the sampler in question. For example if you use AdvancedHMC.jl then you can pass the chain_type=FlexiChain{Symbol} keyword argument (see above).

(If the sampler in question does not have an integration with FlexiChains, please feel free to open an issue!)