dsf.covariance.cov_builder module

DeltaSigma covariance builder.

This module assembles covariance matrices for projected DeltaSigma forecast data vectors. Binny provides the tomographic redshift distributions, bin metadata, densities, and selected lens-source pairs. This builder combines those tomography products with covariance ingredients such as matter power spectra, survey volume, shape noise, shot noise, galaxy bias, and critical surface density factors.

The main class is designed for forecasts where the observable may be the galaxy-matter DeltaSigma signal alone, the projected clustering-like signal alone, or a joint data vector containing both. The block-diagonal scripts give simple first-pass covariances in which different tomographic lens-source pairs are treated as independent.

class dsf.covariance.cov_builder.DeltaSigmaCovarianceBuilder(*, cosmo, lens_result, source_result, lens_population_stats, source_population_stats, bin_pairs, rp_bin_edges, area_deg2, sigma_e, 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=None, hankel_kwargs=None, covariance_orders=None, taper=True, taper_kwargs=None)

Bases: object

Build projected DeltaSigma covariance matrices from tomography outputs.

The builder collects the survey, cosmology, tomography, nuisance, and projection inputs needed to evaluate covariance blocks for tomographic lens-source bin pairs.

It supports three useful covariance views:

• gm x gm for the galaxy-matter DeltaSigma signal.

• gg x gg for a projected clustering-like contribution.

• a joint gm + gg covariance including the cross block.

The class assumes that the input tomography objects already contain the redshift grids, binned distributions, bin edges, bin summaries, and sample metadata needed for the forecast.

Parameters:

• cosmo (ccl.Cosmology)

• lens_result (Any)

• source_result (Any)

• lens_population_stats (Mapping[str, Any])

• source_population_stats (Mapping[str, Any])

• bin_pairs (BinPairs)

• rp_bin_edges (ArrayLike)

• area_deg2 (float)

• sigma_e (ScalarOrPerBin)

• 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 (HankelTransform | None)

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

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

• taper (bool)

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

static bin_value(value, bin_index)

Return the value associated with one tomographic bin.

Parameters:

• value (float | Sequence[float] | Mapping[int | str, float]) – Scalar value shared by all bins, or an array/dictionary with one value per tomographic bin.

• bin_index (int) – Tomographic bin index to select.

Returns:

Scalar value for the requested bin.

Return type:

float

block_diagonal_from_outputs(outputs, output_key)

Return a block-diagonal covariance from already-computed outputs.

Parameters:

• outputs (dict[tuple[int, int], dict[str, Any]]) – Covariance outputs keyed by bin pair.

• output_key (str) – Name of the covariance block stored in each pair output.

Returns:

Pair list and block-diagonal covariance matrix.

Return type:

tuple[list[tuple[int, int]], ndarray]

correlation_matrix(covariance)

Return the correlation matrix for a covariance matrix.

Parameters:

covariance (ndarray[tuple[Any, ...], dtype[float64]]) – Covariance matrix.

Returns:

Correlation matrix with the same shape as covariance.

Return type:

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

covariance_for_pair(lens_bin_index, source_bin_index)

Return all DeltaSigma covariance blocks for one bin pair.

Parameters:

• lens_bin_index (int) – Index of the lens tomographic bin.

• source_bin_index (int) – Index of the source tomographic bin.

Returns:

Dictionary containing the projected radii, individual covariance blocks, joint covariance matrix, and physical ingredients for the requested lens-source pair.

Return type:

dict[str, Any]

covariance_for_pairs(bin_pairs=None)

Return all covariance outputs for multiple lens-source bin pairs.

Parameters:

bin_pairs (list[tuple[int, int]] | None) – Optional set of (lens_bin, source_bin) pairs. If omitted, the pairs stored on the builder are used.

Returns:

Dictionary keyed by (lens_bin, source_bin). Each value is the full covariance output returned by covariance_for_pair().

Return type:

dict[tuple[int, int], dict[str, Any]]

cross_block_diagonal(bin_pairs=None)

Return a block-diagonal covariance for the gm-gg cross block.

Parameters:

bin_pairs (list[tuple[int, int]] | None) – Optional set of (lens_bin, source_bin) pairs. If omitted, the builder’s stored bin pairs are used.

Returns:

Pair list and block-diagonal gm x gg covariance matrix.

Return type:

tuple[list[tuple[int, int]], ndarray]

cross_covariance_for_pair(lens_bin_index, source_bin_index, ingredients=None)

Return the gm x gg cross-covariance for one bin pair.

Parameters:

• lens_bin_index (int) – Index of the lens tomographic bin.

• source_bin_index (int) – Index of the source tomographic bin.

• ingredients (Mapping[str, Any] | None) – Optional precomputed covariance ingredients.

Returns:

Dictionary containing the cross-covariance block and metadata.

Return type:

dict[str, Any]

cross_covariance_for_pairs(bin_pairs=None)

Return gm x gg cross-covariance outputs for multiple bin pairs.

Parameters:

bin_pairs (list[tuple[int, int]] | None) – Optional set of (lens_bin, source_bin) pairs. If omitted, the pairs stored on the builder are used.

Returns:

Dictionary keyed by (lens_bin, source_bin).

Return type:

dict[tuple[int, int], dict[str, Any]]

diagonal_error(covariance)

Return one-sigma errors from a covariance matrix.

Parameters:

covariance (ndarray[tuple[Any, ...], dtype[float64]]) – Covariance matrix.

Returns:

One-dimensional array containing the square root of the covariance diagonal.

Return type:

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

gg_block_diagonal(bin_pairs=None)

Return a block-diagonal covariance for the projected gg signal.

Parameters:

bin_pairs (list[tuple[int, int]] | None) – Optional set of (lens_bin, source_bin) pairs. If omitted, the builder’s stored bin pairs are used.

Returns:

Pair list and block-diagonal gg x gg covariance matrix.

Return type:

tuple[list[tuple[int, int]], ndarray]

gg_covariance_for_pair(lens_bin_index, source_bin_index, ingredients=None)

Return the gg x gg projected clustering covariance for one bin pair.

Parameters:

• lens_bin_index (int) – Index of the lens tomographic bin.

• source_bin_index (int) – Index of the source tomographic bin.

• ingredients (Mapping[str, Any] | None) – Optional precomputed covariance ingredients.

Returns:

Dictionary containing the gg x gg covariance block and metadata.

Return type:

dict[str, Any]

gg_covariance_for_pairs(bin_pairs=None)

Return gg x gg covariance outputs for multiple bin pairs.

Parameters:

bin_pairs (list[tuple[int, int]] | None) – Optional set of (lens_bin, source_bin) pairs. If omitted, the pairs stored on the builder are used.

Returns:

Dictionary keyed by (lens_bin, source_bin).

Return type:

dict[tuple[int, int], dict[str, Any]]

gm_block_diagonal(bin_pairs=None)

Return a block-diagonal covariance for the DeltaSigma signal.

Parameters:

bin_pairs (list[tuple[int, int]] | None) – Optional set of (lens_bin, source_bin) pairs. If omitted, the builder’s stored bin pairs are used.

Returns:

Pair list and block-diagonal gm x gm covariance matrix.

Return type:

tuple[list[tuple[int, int]], ndarray]

gm_covariance_for_pair(lens_bin_index, source_bin_index, ingredients=None)

Return the gm x gm DeltaSigma covariance for one bin pair.

Parameters:

• lens_bin_index (int) – Index of the lens tomographic bin.

• source_bin_index (int) – Index of the source tomographic bin.

• ingredients (Mapping[str, Any] | None) – Optional precomputed covariance ingredients.

Returns:

Dictionary containing the gm x gm covariance block and metadata.

Return type:

dict[str, Any]

gm_covariance_for_pairs(bin_pairs=None)

Return gm x gm covariance outputs for multiple bin pairs.

Parameters:

bin_pairs (list[tuple[int, int]] | None) – Optional set of (lens_bin, source_bin) pairs. If omitted, the pairs stored on the builder are used.

Returns:

Dictionary keyed by (lens_bin, source_bin).

Return type:

dict[tuple[int, int], dict[str, Any]]

hankel_transform(hankel_kwargs=None)

Return the Hankel transform used for radial covariance projections.

Parameters:

hankel_kwargs (Mapping[str, Any] | None) – Optional settings for the Hankel transform.

Returns:

Hankel transform object configured for the covariance Bessel orders.

Return type:

HankelTransform

joint_block_diagonal(bin_pairs=None)

Return a block-diagonal joint covariance matrix.

Parameters:

bin_pairs (list[tuple[int, int]] | None) – Optional set of (lens_bin, source_bin) pairs. If omitted, the builder’s stored bin pairs are used.

Returns:

Pair list and block-diagonal covariance matrix.

Return type:

tuple[list[tuple[int, int]], ndarray]

lens_ingredients(lens_bin_index)

Return cached covariance ingredients that only depend on the lens bin.

Parameters:

lens_bin_index (int) – Index of the lens tomographic bin.

Returns:

Dictionary containing lens-only covariance ingredients.

Return type:

dict[str, Any]

pair_ingredients(lens_bin_index, source_bin_index)

Return the covariance ingredients for one lens-source bin pair.

Parameters:

• lens_bin_index (int) – Index of the lens tomographic bin.

• source_bin_index (int) – Index of the source tomographic bin.

Returns:

Dictionary containing the lens-averaged matter power spectrum, survey volume, lens and source noise terms, galaxy bias, redshift limits, and line-of-sight projection factors for the requested pair.

Return type:

dict[str, Any]

selected_pairs(bin_pairs=None)

Return requested bin pairs in a consistent integer format.

Parameters:

bin_pairs (list[tuple[int, int]] | None) – Optional set of (lens_bin, source_bin) pairs. If omitted, the builder’s stored bin pairs are used.

Returns:

List of integer (lens_bin, source_bin) pairs.

Return type:

list[tuple[int, int]]

source_ingredients(source_bin_index)

Return cached covariance ingredients that only depend on the source bin.

Parameters:

source_bin_index (int) – Index of the source tomographic bin.

Returns:

Dictionary containing source-only covariance ingredients.

Return type:

dict[str, Any]