PyBNF ArviZ bridge (pybnf.inference_data)

The ArviZ InferenceData bridge (ADR-0055, issue #438 item 3).

from_pybnf maps a finished PyBNF MCMC run’s saved samples onto an arviz.InferenceData, so PyBNF’s posterior output becomes first-class in the ArviZ / bayesplot / loo ecosystem (trace / rank / forest / pair plots, az.summary, az.compare). It is a format bridge, not new statistics: PyBNF already runs the samplers, writes Results/samples.txt, and computes rank-normalized split-R-hat + bulk/tail ESS (pybnf.diagnostics, ADR-0009).

Design (ADR-0055), in brief:

  • Source = the saved sample on disk. Results/samples.txt is the thinned, post-burn-in posterior sample (written every sample_every iterations after burn-in) – the same draws credible*.txt and the histograms are built from. It is not the dense in-memory chain diagnostics.txt is computed on, so ArviZ recomputing diagnostics here gives valid numbers on fewer draws: R-hat is comparable, az.ess reads lower than diagnostics.txt by design. A user wanting denser ArviZ diagnostics lowers sample_every. PyBNF’s own final R-hat/ESS are copied into the object’s attrs so nothing is lost.

  • Posterior in sampling space. A log-scaled parameter is emitted in its sampling space (log10 / ln), the space the sampler moved in and the space diagnostics.py already uses – so ArviZ’s diagnostics share PyBNF’s parameterization and Vehtari method. The variable is named <scale>_<name> (e.g. log10_k) so the space is explicit. Linear parameters are unchanged. Recovering each parameter’s scale needs the run’s free parameters: the auto-emit path passes the live variables; the standalone path auto-discovers the .conf copied into Results/ and falls back to natural-space-with-a-warning if it cannot.

  • Groups: ``posterior`` + ``sample_stats`` (``lp``), plus an optional ``log_likelihood``. When the run recorded the per-observation log-likelihood sidecar (output_inference_data set + a per-point likelihood objfunc, ADR-0056, #438 item 4), the bridge adds a log_likelihood group so az.loo / az.waic / az.compare work directly. Its values are genuine unweighted per-point log-densities (the complete, normalized family log_density), not -score. prior and observed_data remain deferred.

arviz is an optional extra (pip install pybnf[arviz]), imported lazily so core stays dependency-free (ADR-0019). Both arviz major lines are supported – the classic 0.x InferenceData and the 1.x xarray-DataTree rewrite – since they differ only in the one from_dict construction call (see _build_idata); the extra is uncapped so installing the bridge never downgrades a user’s arviz.

pybnf.inference_data.from_pybnf(source, *, config=None, variables=None)[source]

Build an arviz.InferenceData from a finished PyBNF MCMC run.

Parameters:

  • source – a Results/ directory, an output directory containing Results/, or a samples.txt file. An Adaptive_MCMC (am) run’s Results/ is read from its per-chain A_MCMC/Runs/params_<chain>.txt files (it writes no usable samples.txt) – see _resolve_samples_path().

  • config – optional path / Configuration used to recover each parameter’s scale for sampling-space output. Ignored when variables is given; auto-discovered from source when both are None.

  • variables – optional list of the run’s free parameters (the in-process auto-emit path passes these directly, so no config reload is needed).

Returns:

an InferenceData with a posterior group (one variable per parameter, dims chain x draw, log parameters in sampling space) and, for samplers that record it, a sample_stats group carrying lp (the recorded log-posterior; omitted for am, which records draws only). When a log_likelihood.txt sidecar is present beside the samples (ADR-0056), a log_likelihood group (variable y over an obs_id axis) is added so az.loo / az.waic / az.compare work directly.

Raises:

ImportError – if the optional arviz extra is not installed.