kinextract.LOSVDErrorEstimator

class kinextract.LOSVDErrorEstimator(fit: dict, cfg)[source]

Unified interface for estimating uncertainties on a recovered LOSVD.

Wraps the output of a completed run_spectral_fit() – a fit that recovers a non-parametric line-of-sight velocity distribution b on the velocity grid xl, together with template weights w – and provides three complementary, combinable error estimation strategies plus Gauss-Hermite (GH) moment error propagation. run_spectral_fit()’s default output is a genuine MAP/penalized-likelihood fit, so laplace_covariance() and bias_correction() work directly on it. If instead handed a fit produced by the optional, non-default full-posterior path (kinextract.bayesian.fit_state_bayesian(), whose reported point estimate is the NUTS posterior mean, not a MAP mode), those two methods raise a clear ValueError rather than silently computing a meaningless Hessian at a non-stationary point (see _require_genuine_map_fit()) – use plot_losvd_posterior() for error bars on such a fit instead. residual_bootstrap() works either way (it always refits fresh via the MAP machinery internally, regardless of what kind of fit it was constructed from):

  1. Laplace / penalized-likelihood covariance (laplace_covariance()) — fast (~seconds), computes a finite-difference Hessian of the MAP objective and inverts it to obtain the Bayesian posterior covariance under the Laplace approximation. Cheap and always worth running first, but likely underestimates true (frequentist) errors if the noise model or regularization strength is imperfect. Requires a genuine MAP fit (see above).

  2. Residual bootstrap (residual_bootstrap()) — the most statistically honest but most expensive method (minutes, embarrassingly parallel via n_jobs). Draws many synthetic spectra by adding resampled residuals (optionally in contiguous blocks, to preserve correlated noise from sky subtraction/resampling) to the best-fit model, refits each synthetic spectrum through the full pipeline (including, for continuum-cofit fits, the joint continuum), and uses the resulting ensemble of recovered LOSVDs/GH moments to build frequentist error bars and percentile intervals.

  3. Bias-corrected LOSVD (bias_correction()) — analytic and nearly free once the Hessian is available. The roughness/smoothing penalty used during the MAP fit shrinks the recovered LOSVD toward flatness (regularization bias); the hat (influence) matrix of the linearized penalized problem is used to estimate and subtract this bias, at the cost of amplified noise in the corrected LOSVD. Requires a genuine MAP fit (see above); also see FitConfig’s “Known limitations” section – this correction was separately found to be actively harmful near the instrumental resolution limit, independent of the MAP-vs-Bayesian question here.

  4. Gauss-Hermite moment errors — propagates the LOSVD covariance (from either the Laplace or bootstrap methods) through the GH moment extraction (kinextract.losvd.fit_losvd_gauss_hermite()) via the delta method, giving uncertainties directly on the physically interpretable moments (V, sigma, h3, h4) rather than just on the raw LOSVD bins.

summarize() combines whichever of these methods were run into a single dict with a recommended central estimate and error bar (preferring bootstrap over Laplace when both are available), and plot_losvd_with_errors() visualizes the result.

Parameters:

  • fit (dict) – Output of run_spectral_fit() for the fit whose errors are to be estimated. Must contain fit["state"] (the FitState), fit["a_map"] (the full MAP parameter vector), and fit["outputs"] with keys "b" (recovered LOSVD), "w" (template weights), and "gp" (best-fit model spectrum).

  • cfg (FitConfig) – Configuration object used to produce the original fit. Reused as the starting point for bootstrap refits (with relaxed optimizer tolerances — see _make_frozen_cfg/_make_frozen_cfg_joint) and to rebuild parameter bounds identical to those used in the original fit.

fit

The fit dict passed to the constructor.

Type:

dict

cfg

The configuration passed to the constructor.

Type:

FitConfig

st

The FitState of the original fit (fit["state"]).

Type:

FitState

a_map

Full MAP parameter vector (LOSVD bins, template weights, continuum offsets, etc.), as a flat array.

Type:

ndarray

b_map

MAP (best-fit) non-parametric LOSVD amplitudes on the velocity grid xl.

Type:

ndarray, shape (nl,)

w_map

MAP template weights.

Type:

ndarray, shape (nt,)

gp_map

MAP best-fit model spectrum.

Type:

ndarray, shape (npix,)

xl

LOSVD velocity grid (km/s).

Type:

ndarray, shape (nl,)

bounds

Parameter bounds for the full parameter vector, rebuilt identically to those used in the original MAP fit; used to keep bootstrap refits within the same feasible region.

Type:

list of (float, float)

__init__(fit: dict, cfg)[source]

Initialize the estimator from a completed fit and its configuration.

Extracts the MAP parameter vector, recovered LOSVD, template weights, and best-fit model spectrum from fit, and rebuilds the parameter bounds used during the original fit (via build_initial_guess_nonparam()) so that subsequent bootstrap refits (residual_bootstrap()) are constrained identically to the original MAP optimization.

Parameters:

  • fit (dict) – Output of run_spectral_fit(). See the class docstring for required keys.

  • cfg (FitConfig) – Configuration object used for the original fit.

Methods

__init__(fit, cfg)

Initialize the estimator from a completed fit and its configuration.

bias_correction()

Estimate and subtract the regularization bias from the MAP LOSVD.

laplace_covariance([rel_step, ...])

Compute the Laplace-approximation posterior covariance at a_map.

plot_bootstrap_distribution(bootstrap_result)

Diagnostic plot of the full bootstrap ensemble (LOSVD bins and GH moments).

plot_losvd_with_errors(summary[, fig, ax, show])

Plot the recovered LOSVD together with its estimated error band.

plot_spectrum_with_errors(summary[, fig, ...])

Plot the best-fit spectrum with observational and model error bands.

residual_bootstrap([n_bootstrap, ...])

Run a residual block bootstrap to estimate LOSVD error bars.

summarize([laplace_result, ...])

Combine results from multiple methods into a unified summary.