dsf.delta_sigma_forecast_builder module

Forecast-ready DeltaSigma inputs.

This module provides the high-level builder used to prepare DeltaSigma forecast inputs for Fisher or DALI analyses. It connects three pieces of the forecast:

  • tomographic lens and source samples,

  • the stacked DeltaSigma data vector,

  • the covariance matrix matched to the selected lens-source bin pairs.

The builder is intentionally model-agnostic. It assumes that the data vector is computed with DeltaSigmaCalculator, but it does not assume a fixed physical parameterization. Users provide a function that maps a parameter vector into the cosmology and profile parameters used by the DeltaSigma calculation.

This makes the class suitable for simple amplitude-only forecasts, cosmology forecasts, HOD or SHMR parameter forecasts, and later Fisher/DALI comparisons.

class dsf.delta_sigma_forecast_builder.DeltaSigmaForecastBuilder(*, cosmo, pk2d_func, theta0, r, rp_bin_edges, area_deg2, sigma_e=0.26, theta_mapper=None, parameter_names=None, lens_survey='desi', source_survey='lsst', lens_sample='lrg', source_sample=None, lens_year=None, source_year=None, lens_role='lens', source_role='source', overlap_threshold=0.1, source_behind_lens=True, center_method='mean', decimal_places=4, shared_overrides=None, lens_overrides=None, source_overrides=None, observable='delta_sigma', sigma_crit_prefactor=None, galaxy_bias=None, galaxy_bias_prefactor=1.0, galaxy_bias_round_decimals=4, k=None, h=None, omega_m=None, rho_crit=None, nonlinear=True, pi=None, gm_window=None, hankel_kwargs=None, covariance_orders=None, covariance_kind='gm', taper=True, taper_kwargs=None, trim_edge_points=0, verbose=True)[source]

Bases: object

Prepare DeltaSigma data vectors and covariance inputs for forecasts.

This class is the user-facing forecast layer for DeltaSigma analyses. It builds the tomographic samples, selects valid lens-source bin pairs, constructs the matching covariance, and exposes a model function that can be passed directly to forecast tools.

The current forecast data vector contains only the galaxy-matter DeltaSigma signal, so this builder currently supports only the matching gm covariance block. The covariance layer also contains heleprs for gg and joint covariance blocks, which are intended for future forecast builders once the corresponding gg or joint data vectors are added.

Parameters:

  • cosmo (ccl.Cosmology)

  • pk2d_func (Callable[..., ccl.Pk2D])

  • theta0 (Sequence[float])

  • r (ArrayLike)

  • rp_bin_edges (ArrayLike)

  • area_deg2 (float)

  • sigma_e (ScalarOrPerBin)

  • theta_mapper (ThetaMapper | None)

  • parameter_names (Sequence[str] | None)

  • lens_survey (str)

  • source_survey (str)

  • lens_sample (str | None)

  • source_sample (str | None)

  • lens_year (str | None)

  • source_year (str | None)

  • lens_role (str)

  • source_role (str)

  • overlap_threshold (float)

  • source_behind_lens (bool)

  • center_method (str)

  • decimal_places (int)

  • shared_overrides (Mapping[str, Any] | None)

  • lens_overrides (Mapping[str, Any] | None)

  • source_overrides (Mapping[str, Any] | None)

  • observable (str)

  • sigma_crit_prefactor (float | None)

  • galaxy_bias (ScalarOrPerBin | None)

  • galaxy_bias_prefactor (float)

  • galaxy_bias_round_decimals (int | None)

  • k (FloatArray | None)

  • h (float | None)

  • omega_m (float | None)

  • rho_crit (float | None)

  • nonlinear (bool)

  • pi (FloatArray | None)

  • gm_window (FloatArray | None)

  • hankel_kwargs (Mapping[str, Any] | None)

  • covariance_orders (Mapping[str, int] | None)

  • covariance_kind (str)

  • taper (bool)

  • taper_kwargs (dict[str, Any] | None)

  • trim_edge_points (int)

  • verbose (bool)

context()[source]

Return the shared forecast context.

Returns:

Dictionary containing the tomography products, bin centers, selected bin pairs, covariance builder, calculator, radius grids, and fiducial cosmology.

Return type:

dict[str, Any]

Notes

The returned dictionary is a shallow copy of the cached context so that model calls can safely use it without directly exposing the cached context object.

forecast(covariance=None)[source]

Return cached forecast products, preparing them if needed.

Parameters:

covariance (ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional precomputed covariance matrix. If provided and no forecast has been cached yet, the builder uses this matrix instead of recomputing the covariance.

Returns:

Dictionary of forecast products suitable for direct use in Fisher, DALI, plotting, or diagnostic workflows.

Return type:

dict[str, Any]

Notes

This is the safe accessor to use in downstream code. Unlike prepare(), it does not rebuild tomography and covariance if the forecast has already been prepared.

If a cached forecast already exists, passing a new covariance is not allowed because it would silently mismatch the cached context.

forecast_inputs()[source]

Return the model function, fiducial parameters, and covariance.

Returns:

Tuple containing the model callable, fiducial parameter vector, and covariance matrix.

Return type:

tuple[Callable[[ndarray[tuple[Any, …], dtype[float64]] | list[float] | tuple[float, …]], ndarray[tuple[Any, …], dtype[float64]]], ndarray[tuple[Any, …], dtype[float64]], ndarray[tuple[Any, …], dtype[float64]]]

Notes

This is the minimal interface needed by many Fisher-style forecast tools. It uses cached forecast products when available, so repeated calls do not rebuild tomography or covariance.

model(theta, *, context=None)[source]

Return the stacked DeltaSigma data vector for one parameter vector.

Parameters:

  • theta (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...]) – Parameter vector at which the DeltaSigma model is evaluated.

  • context (Mapping[str, Any] | None) – Optional forecast context. If omitted, the cached forecast context is used.

Returns:

One-dimensional stacked data vector containing the DeltaSigma blocks for all selected lens-source bin pairs.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

Notes

The optional theta_mapper controls how theta changes the physical model. For example, it can update the cosmology, HOD parameters, SHMR parameters, or any keyword arguments accepted by the supplied pk2d_func.

prepare(covariance=None)[source]

Build and cache all forecast products.

Parameters:

covariance (ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional precomputed covariance matrix. If provided, the builder reuses this matrix instead of recomputing the covariance block. Tomography, context, and the fiducial data vector are still rebuilt so the model function remains matched to the selected lens-source bin pairs.

Returns:

Dictionary containing the model callable, fiducial parameters, covariance matrix, fiducial data vector, selected bin pairs, tomography products, covariance builder, DeltaSigma calculator, and shared forecast context.

Return type:

dict[str, Any]

Notes

Calling this method explicitly recomputes the forecast products and refreshes the cached result. Use forecast() when you want the cached products if they already exist.