sheap.Utils.UncertaintyFunction module

Uncertainty Estimation via Residuals

This module provides utilities to estimate parameter uncertainties after a fit, using residuals and Jacobian-based covariance approximations.

Main Features

• Compute normalized residuals between data and model (residuals()).

• Build residual functions for free parameters only, taking into account tied and fixed relationships (make_residuals_free_fn()).

• Estimate covariance matrices from the Jacobian of residuals with respect to free parameters (error_covariance_matrix()).

• Loop over spectra to propagate uncertainties back into the full parameter vector, respecting ties/fixed constraints (Errorfromloop(), error_for_loop_s()).

Public API

• residuals():

  Compute (y - model)/σ residuals for a given parameter vector.

• make_residuals_free_fn():

  Construct a callable that maps free parameters → residuals, restoring tied/fixed values internally.

• error_covariance_matrix():

  Estimate uncertainties for free parameters from the JTJ matrix.

• Errorfromloop():

  Iterate over multiple spectra, returning uncertainty arrays mapped back into the full parameter space.

• error_for_loop_s():

  Simplified variant of Errorfromloop().

Notes

• The covariance is estimated with the usual \((J^T J)^{-1} \, s^2\) approximation, where J is the Jacobian of residuals and s^2 is the residual variance.

• Tied and fixed parameters are reconstructed using sheap.Assistants.parser_mapper.apply_tied_and_fixed_params().

• Regularization is applied to stabilize ill-conditioned inversions.

Errorfromloop(model, spectra, params, dependencies)

error_covariance_matrix(residual_fn, params_i, xs_i, y_i, yerr_i, free_params, return_full=False, regularization=1e-06, overboost_threshold=10000000000.0)

Estimate uncertainty for free parameters using JTJ approximation. TODO: CHECK IF THIS CAN BE UPGRADED

Parameters:

• residual_fn (Callable)

• params_i (jax.numpy.ndarray)

• xs_i (jax.numpy.ndarray)

• y_i (jax.numpy.ndarray)

• yerr_i (jax.numpy.ndarray)

• free_params (int)

• return_full (bool)

• regularization (float)

• overboost_threshold (float)

Return type:

jax.numpy.ndarray | Tuple[jax.numpy.ndarray, jax.numpy.ndarray]

error_for_loop_s(model, spectra, params, dependencies)

save the samples could increase the number of stuff.

make_residuals_free_fn(model_func, xs, y, yerr, template_params, dependencies)

Parameters:

• model_func (Callable)

• xs (jax.numpy.ndarray)

• y (jax.numpy.ndarray)

• yerr (jax.numpy.ndarray)

• template_params (jax.numpy.ndarray)

Return type:

Callable

residuals(func, params, xs, y, y_uncertainties)

Parameters:

• func (Callable)

• params (jax.numpy.ndarray)

• xs (jax.numpy.ndarray)

• y (jax.numpy.ndarray)

• y_uncertainties (jax.numpy.ndarray)

Return type:

jax.numpy.ndarray