Migrate to ArviZ v1

[haeussma]

Migrate to ArviZ v1

Why

In April 2026, ArviZ released v1.0 (Catalax currently pins v0.x). The
v1 release is a substantial rewrite that splits the package into
arviz-base, arviz-stats, and arviz-plots, and ships breaking changes to
the public API (InferenceData → xarray.DataTree, hdi_prob → prob /
ci_prob, plot_posterior → plot_dist, plot_ess(kind="evolution") →
plot_ess_evolution, and so on). Pinning v0.x is no longer viable: it
prevents Catalax from coexisting in the same environment as other Bayesian
modelling tools that have already migrated (notably Chromhander, which we
routinely use together with Catalax).

This PR migrates Catalax to ArviZ v1 so the library stays current and
installable alongside the wider ArviZ-v1 ecosystem.

Impact for Catalax users

• The public Catalax API does not change. All MCMC plotting and summary
  entrypoints keep their existing signatures
  (HMCResults.plot_posterior(...), Model.from_samples(..., hdi_prob=...),
  summary(mcmc, hdi_prob=...), etc.). Existing notebooks and downstream
  code continue to work without edits.
• Minimum Python version is raised from 3.11 → 3.12. ArviZ v1.1 itself
  requires Python ≥ 3.12, so we have no choice here. Bumping the floor is
  necessary to make Catalax installable in the same environment as
  Chromhander and other ArviZ-v1-based tools that are typically used
  together with Catalax in a single venv.

What changed

Dependency / packaging

• pyproject.toml
  • requires-python = ">=3.12,<3.15" (was >=3.11).
  • arviz>=1.1.0,<2.0 (was >=0.22,<0.30).
  • Added h5netcdf>=1.6.4,<2 and h5py>=3.10,<4: ArviZ v1 writes NetCDF
    via h5netcdf and the latter no longer pulls in h5py automatically.
  • Removed corner>=2.2.2,<3: the corner library is not compatible with
    xarray.DataTree, so the pair plot is now built with
    arviz.plot_pair.
• README.md: badge, prerequisites and CI section updated to Python 3.12+.
• .github/workflows/tests.yml: test matrix ['3.12', '3.13'] (dropped
  3.11).
• .github/workflows/test-publish.yml: build runs on 3.12.

Internal adaptation to ArviZ v1

Public Catalax signatures are unchanged; only the calls Catalax makes into
ArviZ were updated.

• catalax/model/model.py
  • Type hints samples: az.InferenceData → samples: xarray.DataTree.
  • All az.hdi(..., hdi_prob=...) calls converted to
    az.hdi(..., prob=...).
  • Model.from_samples now reshapes raw 1-D dict samples to (1, -1)
    before passing to az.hdi, because az.hdi in v1 expects sample
    dimensions to be present. A regression test was added for this path
    (tests/unit/model/test_from_samples.py).
• catalax/mcmc/plotting.py
  • plot_posterior now calls az.plot_dist (v0 az.plot_posterior was
    removed in v1).
  • plot_ess body simplified to a direct
    az.plot_ess_evolution(...) call (v0
    plot_ess(kind="evolution") was removed in v1).
  • summary uses ci_prob=hdi_prob, ci_kind="hdi" (v0 hdi_prob kwarg
    was renamed).
  • plot_corner was rewritten on top of arviz.plot_pair:
    • KDE marginals on the diagonal with median dot + HDI bar +
      point-estimate text (controlled via stats.ci_kind="hdi",
      stats.ci_prob=hdi_prob, stats.point_estimate="median" scoped via
      az.rc_context so user rcParams are not modified).
    • Lower-triangle joint plots: filled KDE bands (cmap="Blues",
      levels=6) with a thin matching contour line on top to hide soft
      fill transitions, a faint grey scatter underlay so tail samples
      outside the lowest contour remain visible, and divergent transitions
      overlaid by arviz.plot_pair itself.
• catalax/mcmc/results.py
  • to_netcdf(...) now passes engine="h5netcdf" (the default netcdf4
    engine is no longer bundled with ArviZ v1).
  • Docstring sweep: arviz.plot_posterior → arviz.plot_dist, hdi_prob
    → ci_probs, InferenceData → DataTree.
• catalax/__init__.py, catalax/dataset/__init__.py,
  catalax/mcmc/__init__.py, catalax/model/__init__.py,
  catalax/neural/__init__.py
  • Dropped import arviz as az + az.style.use("arviz-doc") from
    package init modules (the v0 style is gone in v1 and we intentionally
    do not override the user's matplotlib / arviz style).
• catalax/__init__.py
  • Set matplotlib.rcParams["figure.dpi"] = 300 and savefig.dpi = 300
    so all plots Catalax produces (and saved files) render at 300 dpi.

Tests / examples

• New regression test tests/unit/model/test_from_samples.py covers the
  reshape path in Model.from_samples that v1 az.hdi forced.
• Example notebooks (HMC.ipynb, InhomogeneousData.ipynb, etc.) were
  re-executed against ArviZ v1 and the resulting JSON / .eqx artefacts
  refreshed. Notebook code itself only changed where the Catalax API was
  not the entrypoint (e.g. direct ArviZ calls inside the notebook).

Verification

• uv run ruff check catalax tests — clean.
• uv run pytest -m "not expensive" — 62 passed, 2 deselected (= 64
  total, including the new from_samples regression test).
• examples/HMC.ipynb runs end-to-end on arviz==1.1.0.
• import catalax produces no FutureWarning / MigrationWarning from
  ArviZ.

Known minor visual differences

• az.summary column names changed upstream (hdi_2.5% → hdi95_lb).
  Visible in the summary DataFrame; unavoidable from the ArviZ side.
• The corner / pair plot now uses ArviZ + seaborn (KDE bands) instead of
  the corner library, so styling is slightly different. The replacement
  shows the same information (HDI, median, divergences) and additionally
  displays joint KDE density rather than just scatter clouds.