Covariance estimation

Spatial jackknife covariance estimation using HEALPix patches.

sum_stat.covariance.jackknife.assign_jackknife_regions(ra, dec, n_regions=100, seed=0)[source]

Assign objects to spatial jackknife regions via KMeans clustering.

Objects are projected onto the unit sphere (x, y, z) and clustered into n_regions groups of approximately equal angular area using KMeans.

Parameters:

  • ra (ndarray, shape (N,)) – Right ascension [degrees].

  • dec (ndarray, shape (N,)) – Declination [degrees].

  • n_regions (int) – Number of jackknife regions.

  • seed (int) – Random seed for KMeans initialisation.

Returns:

labels (ndarray, shape (N,)) – Integer region labels 0 … n_regions-1.

Parameters:
Return type:

ndarray

sum_stat.covariance.jackknife.jackknife_covariance(ra, dec, estimator, n_regions=100, seed=0)[source]

Spatial jackknife covariance matrix.

Divides the footprint into n_regions HEALPix-like patches, then evaluates estimator n_regions times, each time omitting one patch.

Parameters:

  • ra (ndarray, shape (N,)) – Right ascension of the objects [degrees].

  • dec (ndarray, shape (N,)) – Declination of the objects [degrees].

  • estimator (Callable) – Function that takes a boolean mask array of shape (N,) indicating which objects to include, and returns an ndarray of shape (n_out,).

  • n_regions (int) – Number of jackknife regions.

  • seed (int) – Random seed for KMeans.

Returns:

  • mean_estimate (ndarray, shape (n_out,)) – Mean of the jackknife subsamples (≈ full-sample estimate).

  • cov (ndarray, shape (n_out, n_out)) – Jackknife covariance: (N_jk - 1)/N_jk * Σ (x_k - x̄)(x_k - x̄)^T

  • Performance

  • ———–

  • ~depends on estimator cost; overhead ~1 ms/region for region assignment

Parameters:
Return type:

tuple[ndarray, ndarray]

sum_stat.covariance.jackknife.jackknife_covariance_from_labels(ra, dec, labels, estimator, n_regions)[source]

Jackknife covariance from pre-assigned region labels.

Parameters:

  • ra, dec (ndarray, shape (N,)) – Positions (only used to pass to estimator via mask).

  • labels (ndarray, shape (N,)) – Pre-assigned region labels 0 … n_regions-1.

  • estimator (Callable) – Takes a boolean include-mask of shape (N,), returns ndarray (n_out,).

  • n_regions (int) – Number of jackknife regions.

Returns:

  • mean_estimate (ndarray, shape (n_out,))

  • cov (ndarray, shape (n_out, n_out))

Parameters:
Return type:

tuple[ndarray, ndarray]

sum_stat.covariance.jackknife.jackknife_covariance_from_subsamples(subsamples)[source]

Jackknife covariance from pre-computed leave-one-out estimates.

Parameters:

subsamples (ndarray, shape (n_jack, n_bins)) – Leave-one-out estimate vectors.

Returns:

  • mean_estimate (ndarray, shape (n_bins,)) – Mean of the jackknife subsamples.

  • cov (ndarray, shape (n_bins, n_bins)) – Jackknife covariance matrix: (N-1)/N * Σ_k (x_k - x̄)(x_k - x̄)^T

Parameters:

subsamples (ndarray)

Return type:

tuple[ndarray, ndarray]

Spatial block bootstrap covariance estimation.

sum_stat.covariance.bootstrap.bootstrap_covariance(ra, dec, estimator, n_bootstrap=500, n_patches=50, seed=0)[source]

Spatial block bootstrap covariance matrix.

The sky footprint is divided into n_patches spatial blocks via KMeans clustering. Each bootstrap resample draws n_patches blocks with replacement and evaluates the estimator on the combined selection.

Parameters:

  • ra (ndarray, shape (N,)) – Right ascension [degrees].

  • dec (ndarray, shape (N,)) – Declination [degrees].

  • estimator (Callable) – Takes a boolean include-mask of shape (N,), returns ndarray (n_out,).

  • n_bootstrap (int) – Number of bootstrap realisations.

  • n_patches (int) – Number of spatial blocks.

  • seed (int) – Random seed.

Returns:

  • mean_estimate (ndarray, shape (n_out,)) – Mean over bootstrap realisations (≈ full-sample estimate).

  • cov (ndarray, shape (n_out, n_out)) – Bootstrap covariance: 1/(B-1) * Σ_b (x_b - x̄)(x_b - x̄)^T

  • Performance

  • ———–

  • ~depends on estimator cost × n_bootstrap; overhead ~5 ms/bootstrap for N=5000

Parameters:
Return type:

tuple[ndarray, ndarray]