sp_validation.b_modes

B-mode analysis functions for weak lensing validation.

Pure E/B modes (Schneider et al. 2022) as a fixed linear operator on the fine ξ± grid with their exact covariance, COSEBIs, and the χ²/PTE and plotting helpers shared by both.

find_conservative_scale_cut_key(results, requested_scale_cut)

Find scale cut key that conservatively fits within requested range.

Parameters:

• results (dict) – COSEBIs results dictionary with scale cut tuples as keys

• requested_scale_cut (tuple) – (min_theta, max_theta) requested by user

Returns:

Best matching scale cut key from results

Return type:

tuple

scale_cut_to_bins(gg, min_scale=None, max_scale=None)

Convert conservative scale cuts to bin indices.

Conservative approach: excludes ANY bin with partial overlap with forbidden region. For example, with a bin [1,3] arcmin and cuts at 2 arcmin: - Both lower and upper cuts at 2 would exclude this bin

Parameters:

• gg (treecorr.GGCorrelation) – Correlation function object with bin edges

• min_scale (float, optional) – Minimum angular scale (lower cut) - exclude bins extending below this

• max_scale (float, optional) – Maximum angular scale (upper cut) - exclude bins extending above this

Returns:

• start_bin (int) – First included bin index

• stop_bin (int) – Last included bin index + 1 (for slicing notation)

bins_from_edges(left_edges, right_edges, min_scale=None, max_scale=None)

scale_cut_to_bins() on bare bin edges.

bins_from_scale_cut(left_edges, right_edges, scale_cut)

Reporting bins inside a pure-E/B scale cut, as (start_bin, stop_bin).

Each end of scale_cut snaps to the nearest reporting edge in log θ — the rule that snaps reporting edges onto the fine grid — so a cut placed on a nominal edge selects the same bins whichever fine grid the edges were snapped to. stop_bin is exclusive.

log_bin_edges(min_sep, max_sep, nbins)

TreeCorr Log bin edges — the grid a binning defines.

SACC ξ± parts store bin centres, not edges, so a consumer working from a part reconstructs the edges from the binning it was measured on.

correlation_from_covariance(covariance)

Convert covariance matrix to correlation matrix.

Parameters:

covariance (numpy.ndarray) – Covariance matrix

Returns:

Correlation matrix

Return type:

numpy.ndarray

hartlap_factor(npatch, dof)

Hartlap (2007) debiasing of an inverse covariance.

(N - p - 2) / (N - 1) for a jackknife covariance from N = npatch patches inverted over p = dof data points; exactly 1 for an analytic covariance, which npatch=None denotes.

_reporting_binning(weight_int, edges_int, reporting_edges)

Reporting bins as unions of fine bins, and their pair-weighted average.

Each requested reporting edge snaps to the nearest fine edge (in log θ), so every reporting bin is a whole number of fine bins. Row i of the (n_report, n_fine) matrix weights the fine bins of reporting bin i by their TreeCorr pair weight Σ w_i w_j and sums to one. TreeCorr’s ξ± and meanr are averages over pairs under that same weight, so each row reproduces what TreeCorr would measure on the snapped bin.

Returns (binning, edges), edges being the snapped reporting edges.

_fixed_quadrature_operator(edges_int)

The Schneider (2022) transform on the fine grid, _EB_KEYS order.

The single call into cosmo_numba. Its interpolator places the samples on a regular grid in log θ, so the transform runs on the log-uniform nodes of the fine bins — their geometric centres, TreeCorr’s rnom — and is evaluated at every node, with [tmin, tmax] at their extent. That makes it a function of the fine grid alone (the zero-padded ξ− window extends from the evaluation grid). Returns the (6, n_fine, 2 * n_fine) stack of the six matrices acting on [xi_+; xi_-]; rows whose integration support is too small near the grid edges are NaN.

pure_eb_operator(weight_int, edges_int, reporting_edges)

The pure-E/B estimator as one matrix on the fine ξ± grid.

The Schneider et al. (2022) transform is evaluated with fixed-quadrature weights at the log-uniform fine-grid nodes (TreeCorr rnom), integrating over the whole fine grid, and the six pure modes are then averaged into the reporting bins with TreeCorr pair weights. The reporting edges snap to the nearest fine edges, so each reporting bin is a union of fine bins. Both steps are linear and independent of the ξ± values, so the estimator is K = (I_6 ⊗ P) · M and

[xip_E; xim_E; xip_B; xim_B; xip_amb; xim_amb] = K @ [xip_int; xim_int]

with K of shape (6 * n_report, 2 * n_fine).

Parameters:

• weight_int (array_like) – TreeCorr pair weight Σ w_i w_j per fine bin (gg.weight), the averaging weights.

• edges_int (array_like) – The n_fine + 1 log-uniform fine-grid bin edges. The transform’s [tmin, tmax] is the extent of their centres, so they must reach beyond the reporting range on both sides.

• reporting_edges (array_like) – Requested reporting-bin edges, n_report + 1 of them.

Returns:

• operator (numpy.ndarray) – K, shape (6 * n_report, 2 * n_fine).

• binning (numpy.ndarray) – P, the (n_report, n_fine) pair-weighted average.

• edges (numpy.ndarray) – The reporting edges actually used, each a fine-grid edge.

calculate_pure_eb_correlation(theta_int, xip_int, xim_int, weight_int, edges_int, cov_xi, reporting_edges, *, npatch=None)

Pure E/B modes and their exact covariance from fine-grid ξ±.

The modes are pure_eb_operator() applied to [xip_int; xim_int], and the covariance is K C_xi Kᵀ — exact for whatever ξ± covariance is supplied, analytic or jackknife. npatch records which: the jackknife patch count behind cov_xi, or None for an analytic covariance. It travels in the results and sets the Hartlap factor of every χ² built on them (hartlap_factor()).

The reporting bins are unions of fine bins (the requested edges snap to the nearest fine edges), and their theta, xip/xim and variances are the same pair-weighted average of the fine grid, so xi_± = E ± B + amb holds bin by bin and theta/xip/xim are what TreeCorr would measure on the snapped bins.

Parameters:

• theta_int (array_like) – Fine-grid meanr, ξ±, and TreeCorr pair weight Σ w_i w_j. meanr enters only the reported theta; the transform runs on the log-uniform nodes of edges_int.

• xip_int (array_like) – Fine-grid meanr, ξ±, and TreeCorr pair weight Σ w_i w_j. meanr enters only the reported theta; the transform runs on the log-uniform nodes of edges_int.

• xim_int (array_like) – Fine-grid meanr, ξ±, and TreeCorr pair weight Σ w_i w_j. meanr enters only the reported theta; the transform runs on the log-uniform nodes of edges_int.

• weight_int (array_like) – Fine-grid meanr, ξ±, and TreeCorr pair weight Σ w_i w_j. meanr enters only the reported theta; the transform runs on the log-uniform nodes of edges_int.

• edges_int (array_like) – The n_fine + 1 log-uniform fine-grid bin edges.

• cov_xi (array_like) – (2 n_fine, 2 n_fine) covariance of [xip_int; xim_int].

• reporting_edges (array_like) – Requested reporting-bin edges, n_report + 1 of them.

• npatch (int, optional) – Jackknife patch count behind cov_xi; None if it is analytic.

Returns:

The six _EB_KEYS mode arrays, cov (in _EB_KEYS block order), npatch, the reporting grid (theta, the snapped left_edges/right_edges, xip, xim, var_xip, var_xim) and the fine-grid inputs (theta_int, xip_int, xim_int, weight_int, edges_int).

Return type:

dict

covariance_label(npatch)

How a pure-E/B covariance was made, from its npatch record.

calculate_cosebis(gg, nmodes=10, scale_cuts=None, cov_path=None)

Calculate COSEBIs modes from a correlation function for multiple scale cuts.

Parameters:

• gg (treecorr.GGCorrelation) – Fine-binned correlation function object for COSEBIs calculation

• nmodes (int, optional) – Number of COSEBIs modes to compute

• scale_cuts (list of tuples, optional) – List of (min_theta, max_theta) scale cuts to apply. If None, uses full range as a single scale cut.

• cov_path (str, optional) – Path to theoretical covariance matrix (ξ±) which will be transformed to COSEBIs space

Returns:

Dictionary with scale cut tuples as keys and results dictionaries as values. Each results dictionary contains ‘En’, ‘Bn’, ‘cov’, ‘chi2_E’, ‘chi2_B’, ‘pte_B’, ‘scale_cut’, and ‘mask’ entries.

Return type:

dict

cosebis_scan_from_xi(theta, xip, xim, cov_xipm, left_edges, right_edges, *, nmodes=10, scale_cuts=None, npatch=None)

COSEBIs over a set of scale cuts, from ξ± arrays and their covariance.

The values-and-covariance seam of calculate_cosebis(), for callers holding a ξ± data vector rather than a TreeCorr GGCorrelation. The COSEBIs covariance is the ξ± covariance carried through the same linear kernel as the modes, so no estimator re-run is involved. npatch is the jackknife realisation count behind cov_xipm, which sets the Hartlap debiasing; leave it None for a theory covariance, which needs none.

Returns the {scale_cut: result} mapping calculate_cosebis() returns.

calculate_eb_statistics(results)

Calculate E/B mode statistics using 2D PTE analysis for all scale cut combinations.

This function processes pure E/B mode results, calculates covariance blocks, and performs comprehensive 2D PTE analysis. The traditional “1D PTE” values are simply extracted from the 2D matrices at the full-range position.

Parameters:

results (dict) – Pure E/B results: the six mode arrays, the cov block, the reporting theta, and npatch — the jackknife patch count behind the covariance, or None for an analytic one — which sets the Hartlap factor (hartlap_factor())

Returns:

Updated results dictionary with PTE matrices and statistics

Return type:

dict

plot_integration_vs_reporting(results, output_path, version)

Plot integration vs reporting scale comparison.

Parameters:

• results (dict) – Pure E/B results carrying the fine grid (theta_int/xip_int/ xim_int) and its pair-weighted average into the reporting bins (theta/xip/xim, with the var_xip/var_xim the error bars use)

• output_path (str) – Output file path for the plot

• version (str) – Version string for plot title

_get_pte_from_scale_cut(pte_matrix, edges, scale_cut)

Extract PTE value from matrix at a scale cut (bins_from_scale_cut()).

Parameters:

• pte_matrix (numpy.ndarray) – 2D PTE matrix

• edges (tuple of numpy.ndarray) – (left_edges, right_edges) of the grid the matrix is indexed on

• scale_cut (tuple) – (min_scale, max_scale) angular range for scale cut

Returns:

PTE value for the given scale cut, or full-range PTE if scale_cut is None

Return type:

float

plot_pure_eb_correlations(results, output_path, version, fiducial_xip_scale_cut=None, fiducial_xim_scale_cut=None)

Plot pure E/B mode correlation functions.

Parameters:

• results (dict) – Results dictionary containing E/B mode data and statistics

• output_path (str) – Output file path for the plot

• version (str) – Version string for plot title

• fiducial_xip_scale_cut (tuple, optional) – (min_scale, max_scale) for xi+ fiducial analysis, shown as gray regions

• fiducial_xim_scale_cut (tuple, optional) – (min_scale, max_scale) for xi- fiducial analysis, shown as gray regions

plot_cosebis_scale_cut_heatmap(cosebis_results, edges, version, output_path, fiducial_scale_cut=None)

Create 2D heatmaps showing how COSEBIs statistics vary across different scale cuts.

Parameters:

• cosebis_results (dict) – Dictionary with scale cut tuples as keys, containing ‘chi2_E’ and ‘pte_B’ values

• edges (tuple of numpy.ndarray) – (left_edges, right_edges) of the grid the scale cuts index

• version (str) – Version string for main title

• output_path (str) – Output file path for the plot

• fiducial_scale_cut (tuple, optional) – (min_scale, max_scale) for cross-hatching

plot_pte_2d_heatmaps(results, version, output_path, fiducial_xip_scale_cut=None, fiducial_xim_scale_cut=None)

Plot 2D PTE matrix heatmaps for B-mode analysis.

Parameters:

• results (dict) – Results dictionary containing PTE matrices

• version (str) – Version string for plot title

• output_path (str) – Output file path for the plot

• fiducial_xip_scale_cut (tuple, optional) – (min_scale, max_scale) for xi+ fiducial analysis, shown as cross-hatched

• fiducial_xim_scale_cut (tuple, optional) – (min_scale, max_scale) for xi- fiducial analysis, shown as cross-hatched

plot_eb_covariance_matrix(cov_matrix, label, output_path, version)

Plot E/B mode covariance matrix as correlation matrix.

Parameters:

• cov_matrix (numpy.ndarray) – Covariance matrix from E/B mode analysis

• label (str) – How the covariance was made (covariance_label())

• output_path (str) – Output file path for the plot

• version (str) – Version string for plot title

plot_cosebis_modes(results, version, output_path, fiducial_scale_cut=None)

Plot COSEBIs E/B mode correlation functions.

Parameters:

• results (dict) – COSEBIs results dictionary containing E/B mode data

• version (str) – Version string for plot title

• output_path (str) – Output file path for the plot

• fiducial_scale_cut (tuple, optional) – (min_scale, max_scale) for fiducial analysis, shown for reference

save_pure_eb_results(results, output_path)

Save pure E/B mode data vectors and covariance to .npz.

Parameters:

• results (dict) – Results dictionary from calculate_eb_statistics

• output_path (str) – Output .npz file path

_cosebis_result_to_dict(r, suffix='')

Build save dict entries from a single COSEBIs result.

save_cosebis_results(results, output_path, fiducial_scale_cut=None)

Save COSEBIs data vectors and covariance to .npz.

Parameters:

• results (dict) – COSEBIs results. Either a single-scale-cut dict with keys like ‘En’, ‘Bn’, ‘cov’, or a multi-scale-cut dict with tuple keys.

• output_path (str) – Output .npz file path

• fiducial_scale_cut (tuple, optional) – If results has multiple scale cuts, save only this one. If None and results has multiple scale cuts, saves all.

plot_cosebis_covariance_matrix(results, version, var_method, output_path)

Plot COSEBIs covariance matrix as correlation matrix.

Parameters:

• results (dict) – COSEBIs results dictionary containing covariance matrix

• version (str) – Version string for plot title

• var_method (str) – Variance method used for the analysis

• output_path (str) – Output file path for the plot