dsf.covariance.cov_builder module

Delta Sigma covariance builder.

This module assembles covariance matrices for projected Delta Sigma 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 Delta Sigma 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, tomography, rp_bin_edges, area_deg2, sigma_e, pk_gg=None, pk_gm=None, galaxy_bias=None, k=None, projection=None, hankel=None)

Bases: object

Build projected Delta Sigma 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 Delta Sigma 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.

Tomographic bin indices refer to the original lens and source bins. Selecting bin pairs does not renumber the underlying tomography. Covariance calculations are restricted to the selected bin pairs.

Parameters:

• cosmo (ccl.Cosmology)

• tomography (Mapping[str, Any])

• rp_bin_edges (ArrayLike)

• area_deg2 (float)

• sigma_e (ScalarOrPerBin)

• pk_gg (ccl.Pk2D | None)

• pk_gm (ccl.Pk2D | None)

• galaxy_bias (ScalarOrPerBin | None)

• k (FloatArray | None)

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

• hankel (Mapping[str, Any] | HankelTransform | 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[float64]) – Covariance matrix.

Returns:

Correlation matrix with the same shape as covariance.

Return type:

NDArray[float64]

covariance_for_pair(lens_bin_index, source_bin_index)

Return all Delta Sigma 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[float64]) – Covariance matrix.

Returns:

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

Return type:

NDArray[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 Delta Sigma 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 Delta Sigma 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 Hankel backend and numerical settings.

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 lens-averaged power spectra, survey volume, noise terms, galaxy bias (if applicable), redshift limits, and line-of-sight projection factors for the requested pair.

Return type:

dict[str, Any]

selected_pairs(bin_pairs=None)

Return selected pairs using original tomographic bin indices.

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. Requested pairs must belong to the builder’s selected bin pairs.

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]