Add Bayesian posterior sampling to Analysis1d

[henrikjacobsenfys]

Adds Bayesian MCMC posterior sampling to Analysis1d, built on the BUMPS DREAM sampler that arrived in easyscience 2.5.1 (easyscience.fitting.Sampler).

Least-squares fitting reports one point with a curvature-derived uncertainty, which is only trustworthy when parameters are uncorrelated and roughly Gaussian — often not the case in QENS. Sampling maps the whole posterior instead, so correlated and skewed parameters get honest credible intervals, and the correlations themselves become visible.

This is the first of two PRs. Analysis and ParameterAnalysis follow in a second one.

API

Everything to do with sampling hangs off one bayesian property:

analysis.fit()
analysis.bayesian.suggest_bounds().apply()
results = analysis.bayesian.sample(samples=10000, burn=2000, thin=10)

analysis.bayesian.summary()                # median + 68% interval, real names and units
analysis.bayesian.plot_trace()             # convergence check
analysis.bayesian.plot_corner()            # correlations
analysis.bayesian.plot_posterior_predictive()  # data vs credible band

analysis.bayesian.extend(additional_samples=5000)
analysis.bayesian.save(path) / .load(path)
analysis.bayesian.set_parameters_to_median()
analysis.bayesian.results                  # the chain, or None

analysis.fitter.switch_minimizer(...)      # escape hatch

Structure

analysis.bayesian is a PosteriorSampler the analysis holds, not a mixin it inherits. The sampler knows nothing about analyses: it is handed three callables — the chain parameters, the (x, y, weights) to fit against, and a labeller — plus an optional hook to bring cached state up to date before a run. That is the whole contract, and it is what lets PR 2 reuse the same class for ParameterAnalysis, which is not an AnalysisBase at all.

The pieces that are not sampling live on their own:

• posterior_labels.py — ParameterLabels turns parameters into the names and units everything reports under, built once per call rather than once per parameter.
• posterior.py — bounds suggestions, the summary table, pile-up detection.
• utils/posterior_plotting.py — the figures, as plain functions over arrays.

fit() now uses a cached Fitter instead of constructing one per call, invalidated through the existing dirty-flag pattern. Behaviour is unchanged — the full pre-existing suite passes untouched.

Design notes

Bounds are the prior. In DREAM the bounds are the uniform prior, so sampling refuses to run while any free parameter is unbounded. suggest_bounds() proposes bounds from the fitted values and uncertainties, and is advisory until .apply() is called. It only ever fills an infinite side, so physical limits (a non-negative area) survive; and because too narrow a bound truncates the posterior and understates uncertainty, the defaults are deliberately generous (10σ plus 20% of the value). The relative pad covers minimizers that report zero uncertainty; when there is genuinely no scale information the parameter is flagged rather than given an invented one.

Sampling restores your parameters. BUMPS leaves them wherever the last likelihood evaluation put them, which would silently move a fitted model off its fit.

Chains use real parameter names. The sampler labels columns with unique_name (Parameter_4). Those are per-session, so a saved chain reloaded elsewhere was unreadable; save() now writes a sidecar mapping them to stable Parameter.names, and loading without one warns rather than mislabelling columns.

Pile-up detection. After sampling, a warning fires when the posterior has piled up against a bound — catching both over-tight bounds and degenerate parameters that drift until a bound stops them. Threshold calibrated against a measured clipped chain (0.135 occupancy) versus healthy ones (0.000).

Degenerate models. BUMPS crashes with a bare IndexError inside its own outlier removal when chains scatter, which in practice means the model is not identifiable. That is re-raised naming the likely cause and the sampler_kwargs={'outliers': 'none'} workaround.

Testing

• Unit tests mock the sampler; integration tests run real chains and check the posterior recovers known parameters, survives a save/load round trip, and extends.
• New bayesian.ipynb tutorial executes end to end under nbmake.
• pixi run fix and pixi run check both clean.

Notes for reviewers

Two pre-existing issues surfaced while building this, both left untouched as out of scope:

• normalize_resolution() sets the resolution area to 1 but leaves it free, so the next fit() moves it and the normalization silently does not hold.
• The models keep copies of their components, so component.area.fixed = True on an object you constructed has no effect on the analysis — you have to go through analysis.get_free_parameters(). This is easy to get wrong.

Worth a separate issue: fitting data with no uncertainties. Weights fall back to 1, which is harmless for least-squares but not for a posterior, whose width scales directly with the assumed noise. Treating σ as a free nuisance parameter would fix it, but needs a likelihood carrying the −N log σ term that BUMPS' Curve does not have. Documented as a caveat in the tutorial for now.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 92.36111% with 44 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (develop@208d5d3). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/easydynamics/analysis/posterior_sampling.py	87.50%	21 Missing and 7 partials ⚠️
src/easydynamics/utils/posterior_plotting.py	90.26%	5 Missing and 6 partials ⚠️
src/easydynamics/analysis/posterior.py	96.71%	2 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             develop     #237   +/-   ##
==========================================
  Coverage           ?   98.18%           
==========================================
  Files              ?       57           
  Lines              ?     4628           
  Branches           ?      795           
==========================================
  Hits               ?     4544           
  Misses             ?       47           
  Partials           ?       37           

Flag	Coverage Δ
unittests	98.18% <92.36%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/easydynamics/analysis/__init__.py	100.00% <100.00%> (ø)
src/easydynamics/analysis/analysis1d.py	99.21% <100.00%> (ø)
src/easydynamics/analysis/posterior_labels.py	100.00% <100.00%> (ø)
src/easydynamics/utils/__init__.py	100.00% <100.00%> (ø)
src/easydynamics/analysis/posterior.py	96.71% <96.71%> (ø)
src/easydynamics/utils/posterior_plotting.py	90.26% <90.26%> (ø)
src/easydynamics/analysis/posterior_sampling.py	87.50% <87.50%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.