stacking — tSZ cluster stacking

stacking implements the SNR-selected cluster stacking analysis from paper §4.2. Stacking averages cutouts centred on tSZ signal peaks, suppressing uncorrelated pixel noise and revealing the mean radial profile of the underlying cluster population.

The analysis is carried out in SNR bins rather than mass bins because the patch-based pipeline has no direct access to the halo catalogue at inference time. Comparing AGORA and DDPM stacked profiles tests whether the model reproduces not just the pixel statistics but the spatial structure of individual clusters.

Workflow

from foregrounds_diffusion.stacking import select_snr_pixels, extract_cutouts

# 1. Find peaks in the 3–5σ SNR bin across all tSZ maps
coords = select_snr_pixels(tsz_maps_nhw, snr_min=3.0, snr_max=5.0,
                           min_separation=5)

# 2. Extract 32×32 pixel cutouts centred on each peak
cutouts = extract_cutouts(tsz_maps_nhw, coords, cutout_size=32)
# cutouts: (M, 32, 32)

# 3. Stack
stacked_profile = cutouts.mean(axis=0)   # (32, 32)

Run the same workflow on DDPM samples to compare against AGORA. See 09 — tSZ Cluster Stacking for the full analysis, including radial profile plots and SNR-bin comparisons.

API

tSZ cluster stacking utilities.

Stacking is a signal-recovery technique that averages cutouts centred on known or candidate cluster positions, suppressing uncorrelated noise and revealing the mean tSZ profile of the underlying population.

This module implements the stacking analysis from paper §4.2, which compares the stacked tSZ cluster profiles in AGORA maps against DDPM samples to test whether the model reproduces the spatial structure of galaxy clusters.

Workflow

  1. select_snr_pixels() identifies local SNR peaks in the tSZ maps within a chosen SNR bin (e.g. 3–5 or 5–∞), returning (patch_idx, row, col) coordinates.

  2. extract_cutouts() extracts square thumbnails of a given size centred on each peak coordinate.

  3. The returned cutout stack is averaged by the caller to produce a stacked profile image.

See tutorial docs/tutorials/09_tsz_stacking.ipynb for the full analysis, including stacked-profile comparisons across SNR bins.

foregrounds_diffusion.stacking.select_snr_pixels(tsz_maps_nhw, snr_min, snr_max, min_separation=5)[source]

Find local SNR-peak coordinates within a given SNR bin.

Parameters:

  • tsz_maps_nhw (ndarray, shape (N, H, W))

  • snr_min (float) – Lower SNR bound (inclusive).

  • snr_max (float or None) – Upper SNR bound (exclusive). None means no upper bound.

  • min_separation (int) – Minimum pixel separation between selected peaks.

Returns:

list of tuple – Each element is (patch_idx, row, col).

foregrounds_diffusion.stacking.extract_cutouts(maps_nhw, coords, cutout_size, max_cutouts=500)[source]

Extract square cutouts centred on (patch_idx, row, col) coordinates.

Parameters:

  • maps_nhw (ndarray, shape (N, H, W))

  • coords (list of tuple) – Coordinates from select_snr_pixels().

  • cutout_size (int) – Side length of the square cutout in pixels.

  • max_cutouts (int) – Maximum number of cutouts to extract (caps memory use).

Returns:

ndarray, shape (M, cutout_size, cutout_size) or None – Stacked cutouts, or None if no valid cutouts were found.