kinextract.bayesian.fit_state_bayesian

kinextract.bayesian.fit_state_bayesian(st: FitState, cfg: FitConfig, a0: ndarray, bounds: list)[source]

Run the full Bayesian LOSVD/template/continuum fit, called from kinextract.fitting.run_spectral_fit().

Only pre-normalized-mode fits are supported (cfg.fit_continuum=False): this raises NotImplementedError immediately if cfg.fit_continuum is True, since continuum-cofitting has no NUTS-compatible implementation here (see the module docstring). Pre-normalize the spectrum first (see kinextract.continuum.asymmetric_least_squares_continuum() and examples/notebooks/06_prenormalized_workflow.ipynb), or use the MAP joint path (kinextract.joint) if a cofit continuum with bootstrap uncertainty estimates is needed instead.

cfg.clean=True (iterative sigma-clipping of outlier pixels) is handled as a one-time MAP-based preprocessing pass (kinextract.fitting.run_iterative_clean_map()) before any posterior sampling happens: identifying cosmic rays/bad columns is a data-quality step, not the scientific measurement, so it doesn’t need full posterior sampling.

Regularization-strength (xlam) auto-selection uses a cheap MAP-based grid search (see the module docstring). One full NUTS posterior is run at the very end, at cfg’s configured (fast) sampling budget – if that posterior fails the reliability gate (poor R-hat or too many divergences, more likely for real data with more structure than a smooth synthetic mock), it is retried once at a substantially larger, separately-validated budget rather than silently reporting an unconverged result. Whichever posterior passes (or the last one tried, if neither does) is what gets reported.

Parameters:

  • st (FitState) – Fit state to update in place (st.xlam, st.continuum_mult, etc.).

  • cfg (FitConfig) – Run configuration. Must have cfg.fit_continuum=False. NUTS-specific fields (nuts_num_warmup, nuts_num_samples, nuts_num_chains, nuts_seed) fall back to sensible defaults if unset.

  • a0 (ndarray) – Initial flat parameter vector (from kinextract.spectrum.build_initial_guess_nonparam()), used to seed the first NUTS run.

  • bounds (list of tuple) – Unused here (NUTS samples in unconstrained space with automatic transforms rather than box-constrained optimization); accepted only so the call site in run_spectral_fit does not need to branch on fit method.

Returns:

result – x (posterior-mean flat vector), success (bool, True unless divergence fraction or R-hat fails the reliability thresholds), message (str), mcmc (the final numpyro.infer.MCMC object – mcmc.get_samples() gives the raw posterior draws for every named site, used by e.g. kinextract.plotting.plot_losvd_posterior() to draw credible-interval error bars), diagnostics (dict with n_divergent, n_total, r_hat (per-site dict), max_r_hat (scalar, the same value used in the success gate above and quoted in message), mean_num_steps/ max_num_steps (NUTS trajectory length – leapfrog steps per transition – a direct measure of posterior geometry difficulty), and setup_wall_time_s/nuts_wall_time_s (wall-clock split between everything before the final NUTS call – cleaning, xlam selection – and the final NUTS call(s) themselves, which typically dominate total runtime; the latter includes the retry time if a budget escalation happened).

Return type:

SimpleNamespace