masking — Peak masks and AGORA cluster masks

masking provides two distinct families of functions used at different stages of the pipeline.

Flat-sky peak masks (post-sampling)

After drawing samples from the DDPM, bright point-source peaks in the generated CIB maps are masked before computing statistics. This mirrors the 2 mJy masking applied during training data preparation:

from foregrounds_diffusion.masking import get_peak_masks, inpaint_masked_regions

mask = get_peak_masks(cib_map, mask_threshold_sigma_units=3.0,
                      mask_radius_pixel_units=3.0)
inpainted = inpaint_masked_regions(cib_map, mask)

boundary_apod_mask() and get_mask_using_gaussian_fitting() are variants used for apodisation and adaptive threshold fitting respectively.

Full-sky HEALPix masks (preprocessing)

These functions run once during data preparation on the cluster, operating on full-sky HEALPix maps before patch extraction. They require healpy, astropy, and the MDPL2 halo catalogue produced by 01 — Halo Catalogue.

get_point_source_mask_in_healpix() masks CIB point sources above a flux threshold (default 2 mJy at 150 GHz) using sigma-clipping:

from foregrounds_diffusion.masking import get_point_source_mask_in_healpix

mask = get_point_source_mask_in_healpix(cib_map_jy_sr, freq_ghz=150,
                                         threshold_mjy=2.0, nside=8192)

get_apodised_mdpl2_cluster_mask() builds apodised circular masks around MDPL2 clusters with M_500c ≥ 3×10¹⁴ M☉:

from foregrounds_diffusion.masking import get_apodised_mdpl2_cluster_mask

cluster_mask = get_apodised_mdpl2_cluster_mask(
    nside=2048,
    halo_cat_fname="data/halo_catalogue/halo_catalogue_m500gt3e14.npy.npz",
    m500c_threshold=3e14,
)

See 02 — Masking for the full masking workflow.

API

Masking utilities for flat-sky patches and full-sky HEALPix maps.

Flat-sky helpers (formerly in preprocessing):

get_peak_masks, inpaint_masked_regions, boundary_apod_mask, get_mask_using_gaussian_fitting

AGORA MDPL2 cluster/point-source masks:

get_mdpl2_halo_cat, get_cluster_mask_radius, get_point_source_mask_in_healpix, get_mdpl2_conversion_factors_K_to_MjyperSr, apodize_binary_mask_prof, get_apodised_mdpl2_cluster_mask

foregrounds_diffusion.masking.get_peak_masks(tmap, mask_threshold_sigma_units=10, mask_radius_pixel_units=0, perform_apod=1, mask_shape='circle', taper_radius_fac=2.0)

Generate a sigma-clipping peak mask for a flat-sky map.

Parameters:

• tmap (ndarray) – Input flat-sky map.

• mask_threshold_sigma_units (float) – Sigma threshold above which pixels are masked.

• mask_radius_pixel_units (float) – Radius (in pixels) of the mask hole punched around each peak. When 0, only the peak pixel itself is masked.

• perform_apod (bool) – Apodise the mask boundary.

• mask_shape ({‘circle’, ‘square’}) – Shape of the mask hole.

• taper_radius_fac (float) – Apodisation taper radius as a multiple of mask_radius_pixel_units.

Returns:

peak_mask, mask (ndarray) – Binary peak mask and (apodised) extended mask.

foregrounds_diffusion.masking.inpaint_masked_regions(hmap, mask, rng=None)

Replace masked pixels with Gaussian noise matching unmasked-region statistics.

Parameters:

• hmap (ndarray, shape (npix,)) – HEALPix (or flat-sky) map.

• mask (ndarray, shape (npix,)) – Mask array (1 = keep, 0 = replace).

• rng (numpy.random.Generator, optional) – Random number generator. A fresh default_rng() is used when None.

Returns:

ndarray – Copy of hmap with masked pixels replaced by Gaussian noise.

foregrounds_diffusion.masking.boundary_apod_mask(x_grid, y_grid, mask_radius, perform_apod=True, mask_shape='circle', taper_radius_fac=6.0)

Create an apodised boundary mask on a 2D grid.

Parameters:

• x_grid, y_grid (ndarray) – Coordinate grids (e.g. RA, Dec) of the map.

• mask_radius (float) – Mask radius in the same units as x_grid and y_grid.

• perform_apod (bool) – Apodise the mask boundary.

• mask_shape ({‘circle’, ‘square’}) – Shape of the masked region.

• taper_radius_fac (float) – Apodisation taper radius as a multiple of mask_radius.

Returns:

ndarray – Binary or apodised mask with the same shape as x_grid.

foregrounds_diffusion.masking.get_mask_using_gaussian_fitting(nonpeak_mask, mul_width_by_factor=2, ini_height=0.0, ini_amp=1.0, ini_rot=0.0, ini_blob_size_in_pixels=10.0, use_elliptical_gaussian=False, perform_apod=True)

Fit Gaussians to blobs in a binary mask and create a smooth mask.

Parameters:

• nonpeak_mask (ndarray) – Binary mask where 1 marks regions to be masked.

• mul_width_by_factor (float) – Multiply the fitted Gaussian width by this factor for the mask radius.

• ini_height, ini_amp, ini_rot (float) – Initial Gaussian parameters (baseline, amplitude, rotation).

• ini_blob_size_in_pixels (float) – Initial guess for the Gaussian width in pixels.

• use_elliptical_gaussian (bool) – Fit an elliptical (asymmetric) Gaussian if True.

• perform_apod (bool) – Apodise the final mask.

Returns:

ndarray – Final (possibly apodised) mask.

foregrounds_diffusion.masking.get_mdpl2_halo_cat(halo_cat_fname, get_velocities=True)

Load the MDPL2 halo catalogue.

Parameters:

• halo_cat_fname (str) – Path to the halo catalogue file (.npy or .npz).

• get_velocities (bool) – If True, also return the three velocity components.

Returns:

tuple of ndarray – (ra, dec, z, m200c, m500c) or (ra, dec, z, m200c, m500c, vlos, vtht, vphi) when get_velocities=True.

foregrounds_diffusion.masking.get_cluster_mask_radius(m500c)

Return a mask radius in arcminutes based on cluster mass.

Parameters:

m500c (float) – Cluster mass M_500c in solar masses.

Returns:

float – Mask radius in arcminutes.

foregrounds_diffusion.masking.get_point_source_mask_in_healpix(freq, hmap_Mjy_per_sr, threshold_mjy_freq0, threshold2_mjy_freq0=None, freq0=150.0, spec_index=3.4, full_sky=True, ang_res_am=None, return_flux_map_in_mjy=False)

Identify pixels containing point sources above a flux threshold.

Parameters:

• freq (float) – Observation frequency in GHz.

• hmap_Mjy_per_sr (ndarray) – HEALPix map in MJy/sr.

• threshold_mjy_freq0 (float) – Flux threshold in mJy at freq0.

• threshold2_mjy_freq0 (float, optional) – Upper flux threshold for band-pass masking.

• freq0 (float) – Reference frequency in GHz.

• spec_index (float) – Spectral index for frequency scaling.

• full_sky (bool) – If True, treat hmap_Mjy_per_sr as a full-sky HEALPix map and compute pixel area from NSIDE. Otherwise supply ang_res_am.

• ang_res_am (float, optional) – Pixel angular resolution in arcminutes (required when full_sky=False).

• return_flux_map_in_mjy (bool) – If True, also return the flux map in mJy.

Returns:

• mask_pixels (ndarray of int) – Pixel indices (or (row, col) index tuple for flat maps) to mask.

• hmap_mjy (ndarray) – Flux map in mJy (only returned when return_flux_map_in_mjy=True).

foregrounds_diffusion.masking.get_mdpl2_conversion_factors_K_to_MjyperSr(expname, band)

Look up the K → MJy/sr conversion factor for a given experiment and band.

Parameters:

• expname (str or None) – Experiment name: 'planck', 'spt3g'/'spt'/'spt4', 'cmbs4'/'s4wide'/'s4deep', or None for a generic set.

• band (int) – Band centre frequency in GHz.

Returns:

float – Conversion factor.

foregrounds_diffusion.masking.apodize_binary_mask_prof(binary_mask, dist_smooth_angle, apod_start_dist, apod_end_dist)

Apodise a binary HEALPix mask using a distance-based smooth profile.

The apodisation profile is (x − sin x) / 2π on [0, 2π], the integral of a cosine-kernel cross-section.

Parameters:

• binary_mask (ndarray) – Full-sky HEALPix binary mask (1 = unmasked, 0 = masked).

• dist_smooth_angle (float) – FWHM of the Gaussian kernel applied to the distance map, in radians.

• apod_start_dist (float) – Distance below which pixels are set to 0, in radians.

• apod_end_dist (float) – Distance above which the profile is not applied, in radians.

Returns:

ndarray – Apodised mask.

foregrounds_diffusion.masking.get_apodised_mdpl2_cluster_mask(nside, halo_cat_fname, m500c_threshold=50000000000000.0, cluster_lmz_dic=None, howmanythetaforclusters=-1, apodise=True, expname=None)

Build an apodised HEALPix cluster mask from the MDPL2 halo catalogue.

Parameters:

• nside (int) – HEALPix NSIDE resolution.

• halo_cat_fname (str) – Path to the halo catalogue .npy file.

• m500c_threshold (float) – Minimum M_500c (in M_☉) for a cluster to be masked. Pass -1 to use the redshift-dependent mass limit from cluster_lmz_dic instead.

• cluster_lmz_dic (dict, optional) – Redshift-dependent mass-limit dictionary (required when m500c_threshold=-1). Must contain keys 'redshift' and 'M500c'.

• howmanythetaforclusters (float) – If > 0, compute the mask radius as this multiple of θ_500c. Otherwise use get_cluster_mask_radius().

• apodise (bool) – Apodise the binary mask.

• expname (str, optional) – Experiment name (used only when m500c_threshold=-1).

Returns:

ndarray – Final apodised (or binary) full-sky cluster mask.