dsf.covariance.projection.hankel_transform module¶

Hankel transforms for projected radial statistics.

This module provides the HankelTransform class, which converts Fourier-space spectra into projected radial-space quantities. It is useful for computing projected correlation functions, covariance matrices, and higher-order radial tensors that appear in weak-lensing and Delta Sigma calculations.

The class owns the public validation layer and delegates low-level radial and Bessel operations to hankel_utils.

class dsf.covariance.projection.hankel_transform.HankelTransform(r_min=0.1, r_max=100.0, k_min=0.0001, k_max=10.0, orders=(0, 2), n_zeros=1000, n_zeros_step=1000, prune_r=None, prune_log_space=True, verbose=False, max_iterations=100)[source]¶

Bases: object

Project Fourier-space spectra into radial-space statistics.

The class builds Bessel-function grids for the requested orders and uses them to evaluate projected radial quantities. A single input spectrum gives a projected correlation-like statistic, two spectra give a projected covariance matrix, and three spectra give a projected third-order radial tensor.

Parameters:

r_min (float) – Minimum radial scale to cover.
r_max (float) – Maximum radial scale to cover.
k_min (float) – Minimum wavenumber to cover.
k_max (float) – Maximum wavenumber to cover.
orders (Iterable[float | int]) – Bessel orders to precompute.
n_zeros (int) – Initial number of Bessel roots used for each grid.
n_zeros_step (int) – Number of extra Bessel roots added if the requested range is not covered.
prune_r (int | None) – Optional radial-grid pruning factor. Use None or 0 to keep the full grid.
prune_log_space (bool) – Whether pruning should keep approximately logarithmic radial spacing.
verbose (bool) – Whether to print grid-construction diagnostics.
max_iterations (int) – Maximum number of grid-construction attempts per order.

available_orders()[source]¶

Return the Bessel orders available for projection.

Return type:: tuple[float | int, …]

bin_radial_matrix(r, matrix, r_bins)[source]¶

Average a radial matrix or tensor into radial bins.

Parameters:

r (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...]) – Radial grid associated with each axis of matrix.
matrix (ndarray[tuple[Any, ...], dtype[float64]]) – Radial matrix or tensor to bin.
r_bins (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...]) – Radial bin edges.

Returns:

Radial bin centers and binned matrix or tensor.

Return type:

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

correlation_matrix(covariance)[source]¶

Return the correlation matrix associated with a covariance matrix.

Parameters:: covariance (ndarray[tuple[Any, ...], dtype[float64]]) – Covariance matrix.
Returns:: Dimensionless correlation matrix.
Return type:: ndarray[tuple[Any, …], dtype[float64]]

diagonal_error(covariance)[source]¶

Return one-sigma errors from a covariance matrix.

Parameters:: covariance (ndarray[tuple[Any, ...], dtype[float64]]) – Covariance matrix.
Returns:: Square root of the covariance diagonal.
Return type:: ndarray[tuple[Any, …], dtype[float64]]

pk_grid(k_pk=None, pk=None, order=0, taper=False, taper_kwargs=None, **kwargs)[source]¶

Return a power spectrum evaluated on a Hankel grid.

Parameters:

k_pk (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...] | None) – Wavenumber grid for tabulated spectra.
pk (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...] | Callable[[...], ndarray[tuple[Any, ...], dtype[float64]]] | None) – Power-spectrum values or callable power spectrum.
order (float | int) – Bessel order to use.
taper (bool) – Whether to suppress low-k and high-k edge power.
taper_kwargs (dict | None) – Optional settings for the spectrum taper.
**kwargs – Extra arguments passed to callable spectra.

Returns:

Power spectrum evaluated on the internal wavenumber grid.

Return type:

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

projected_correlation(k_pk=None, pk=None, order=0, taper=False, taper_kwargs=None, **kwargs)[source]¶

Compute a projected radial statistic from one spectrum.

Parameters:

k_pk (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...] | None) – Wavenumber grid for tabulated spectra.
pk (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...] | Callable[[...], ndarray[tuple[Any, ...], dtype[float64]]] | None) – Spectrum values or callable spectrum.
order (float | int) – Bessel order to use.
taper (bool) – Whether to suppress low-k and high-k edge power.
taper_kwargs (dict | None) – Optional settings for the spectrum taper.
**kwargs – Extra arguments passed to callable spectra.

Returns:

Radial grid and projected radial statistic.

Return type:

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

projected_covariance(k_pk=None, pk1=None, pk2=None, order=0, taper=False, taper_kwargs=None, **kwargs)[source]¶

Compute a projected covariance matrix from two spectra.

Parameters:

k_pk (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...] | None) – Wavenumber grid for tabulated spectra.
pk1 (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...] | Callable[[...], ndarray[tuple[Any, ...], dtype[float64]]] | None) – First spectrum values or callable spectrum.
pk2 (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...] | Callable[[...], ndarray[tuple[Any, ...], dtype[float64]]] | None) – Second spectrum values or callable spectrum.
order (float | int) – Bessel order to use.
taper (bool) – Whether to suppress low-k and high-k edge power.
taper_kwargs (dict | None) – Optional settings for the spectrum taper.
**kwargs – Extra arguments passed to callable spectra.

Returns:

Radial grid and projected covariance matrix.

Return type:

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

projected_skewness(k_pk=None, pk1=None, pk2=None, pk3=None, order=0, taper=False, taper_kwargs=None, **kwargs)[source]¶

Compute a projected third-order radial tensor from three spectra.

Parameters:

k_pk (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...] | None) – Wavenumber grid for tabulated spectra.
pk1 (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...] | Callable[[...], ndarray[tuple[Any, ...], dtype[float64]]] | None) – First spectrum values or callable spectrum.
pk2 (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...] | Callable[[...], ndarray[tuple[Any, ...], dtype[float64]]] | None) – Second spectrum values or callable spectrum.
pk3 (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...] | Callable[[...], ndarray[tuple[Any, ...], dtype[float64]]] | None) – Third spectrum values or callable spectrum.
order (float | int) – Bessel order to use.
taper (bool) – Whether to suppress low-k and high-k edge power.
taper_kwargs (dict | None) – Optional settings for the spectrum taper.
**kwargs – Extra arguments passed to callable spectra.

Returns:

Radial grid and projected third-order radial tensor.

Return type:

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

spherical_correlation(k_pk=None, pk=None, order=0, taper=False, taper_kwargs=None, **kwargs)[source]¶

Compute the k-weighted projected radial statistic.

Parameters:

k_pk (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...] | None) – Wavenumber grid for tabulated spectra.
pk (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...] | Callable[[...], ndarray[tuple[Any, ...], dtype[float64]]] | None) – Spectrum values or callable spectrum.
order (float | int) – Bessel order to use.
taper (bool) – Whether to suppress low-k and high-k edge power.
taper_kwargs (dict | None) – Optional settings for the spectrum taper.
**kwargs – Extra arguments passed to callable spectra.

Returns:

Radial grid and k-weighted projected radial statistic.

Return type:

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

taper_spectrum(k, pk, **kwargs)[source]¶

Return a smoothly tapered power spectrum.

Parameters:

k (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...]) – Wavenumber grid.
pk (ndarray[tuple[Any, ...], dtype[float64]] | list[float] | tuple[float, ...]) – Power-spectrum values evaluated on k.
**kwargs – Optional taper settings.

Returns:

Power spectrum with smooth low-k and high-k suppression.

Return type:

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