kinextract.assess_recovery_bias

kinextract.assess_recovery_bias(fit: dict, cfg: FitConfig, v_true_grid: Sequence[float], sigma_true_grid: Sequence[float], h3_true: float = 0.0, h4_true: float = 0.0, n_seeds: int = 8, seed0: int = 0) → dict[source]

Measure empirical LOSVD recovery bias on a grid of known truths.

For every combination of v_true_grid x sigma_true_grid, generates n_seeds independent matched mocks (kinextract.mocks.build_matched_mock(), reusing fit’s own instrument grid, template mixture, continuum, and per-pixel noise level), refits each with kinextract.fitting.fit_state_map_with_optional_clean() (the same pipeline kinextract.fitting.run_spectral_fit() uses by default), and reports the mean and seed-to-seed standard deviation of recovered - true for V, sigma, h3, and h4 (kinextract.losvd.fit_losvd_gauss_hermite()).

Parameters:

  • fit (dict) – A completed fit dict, as returned by kinextract.fitting.run_spectral_fit() (or built directly via kinextract.spectrum.make_fit_state() + kinextract.fitting.fit_state_map_with_optional_clean()) on the real target being validated. Must contain "state" (the FitState) and "a_map" (the best-fit flat parameter vector) – these supply the template weights, continuum, and amplitude that matched mocks reuse, and the instrument grid/noise level they’re built on. Not modified.

  • cfg (FitConfig) – The same configuration used to produce fit. Every replicate refit runs with cfg exactly as configured – including xlam_auto (so the bias table reflects the same regularisation-selection behavior a real fit would use) and clean sigma-clipping – so the measured bias reflects the pipeline’s actual end-to-end behavior on this target’s configuration, not a simplified version of it. A copy of cfg is used internally, so the caller’s own cfg object (e.g. its xlam field, which xlam_auto would otherwise overwrite on every replicate) is never mutated by this call.

  • v_true_grid (sequence of float) – Ground-truth velocity/dispersion grid points to test, in km/s. The full Cartesian product is evaluated.

  • sigma_true_grid (sequence of float) – Ground-truth velocity/dispersion grid points to test, in km/s. The full Cartesian product is evaluated.

  • h3_true (float, optional) – Ground-truth higher-order Gauss-Hermite moments to inject at every grid point (held fixed across the grid; this characterizes bias for one LOSVD shape at a time).

  • h4_true (float, optional) – Ground-truth higher-order Gauss-Hermite moments to inject at every grid point (held fixed across the grid; this characterizes bias for one LOSVD shape at a time).

  • n_seeds (int, optional) – Number of independent noise realizations per grid point.

  • seed0 (int, optional) – Base seed; replicate i at each grid point uses seed seed0 + i, so results are reproducible.

Returns:

Keyed by (v_true, sigma_true) tuples. Each value is a dict with keys bias_v, bias_v_std, bias_sigma, bias_sigma_std, bias_h3, bias_h3_std, bias_h4, bias_h4_std (all floats, mean/std of recovered - true over the successful replicates), and n_seeds (int, the number of replicates that converged – may be less than the requested n_seeds if some replicates fail). Grid points where every replicate failed are omitted (logged, not raised).

Return type:

dict