[cailmdaley]

PSF-star selection now rejects candidates on the UNIONS manual mask (bit 8) as well as instrument flags. Outlier rejection alone handles crowded star fields, but not M33. There, HII regions and clusters outnumber stars on the CCD, pass selection, and inflate the PSF model itself. Inside 0.15° of M33, normal-size stars (|dT/T| < 0.2, so not contaminants) come out 2.4% smaller than the model, against ≈0 in the field. Their ellipticity residual rms is 6.4× the field value, and 24% of selected "stars" are more than 1.2× the PSF size. M13, M92, M101 and the Draco and Ursa Minor dwarf spheroidals are crowding only: no oversized candidates, and residuals within ~1.2× of the field (figure; measurement in #993). The manual mask removes 1,024 of M33's 1,025 oversized candidates within 1° and every radius where the model is biased. It costs 0.5% of PSF stars survey-wide. Draco and Ursa Minor are not in the manual mask and don't need to be.

What changes.

• config_exp_psfex.ini and config_exp_mccd.ini set MASK_PATHS = $SP_INPUT_MASKS/mask_ugriz_nside131072_n8.hsp, a 55 MB map.
• star_selection.setools adds MASK_EXT == 0 beside IMAFLAGS_ISO == 0 in preselect, flag and star_selection. The preselect cut matters most, because it keeps the contaminants from setting the stellar-locus mode. fwhm_mag_cut only feeds the size–magnitude plot and is unchanged.
• In astra.yaml, masking.psf_star_mask_veto defaults to the new manual_mask_veto option. instrument_flags_only (how run 1 ran) and star_body_veto remain as alternatives, with their measured costs. The Values pin both configs' MASK_PATHS and all three setools cuts.
• Docs (tutorial, README, mask_query docstrings, tile config comment) now state the one in-pipeline use of a sky mask and why it exists. The final catalogue's MASK_<band> columns are still never cut on.

Simulations. config/cfis_image_sims/ symlinks the exposure configs and star_selection.setools, so any sims run that selects PSF stars (psf_model psfex or mccd) now runs this veto too and needs inputs.masks. The new parse-time guard refuse_missing_masks says so instead of failing in setools. psf_model: fake, the sims default, queries no masks and is unaffected. candide's image_sims profile in workflow/config.yaml points inputs.masks at the same DR6 masks as its data profile; the field notes there say when the key is required.

Tests.

• A setools test reproduces the failure on one CCD: 60 compact extended sources at 1.05″ outnumber 30 stars at 0.75″. Without the mask the locus locks onto the extended sources; with MASK_EXT set, exactly the stars are selected.
• Decision-pin mutations: deleting the star_selection cut and commenting out MCCD's MASK_PATHS each break the record check.
• Guard tests cover which runs need masks and check that the sims share the masked star selection.
• In the ShapePipe container (shapepipe-develop-240b37e4.sif), 181 tests across the decision, setools, mask_query, mode and mask-column files pass, as do 89 in the guard, decision and setools files. The Snakemake DAG tests run in CI.

Run 2 only. Run-1 products keep their PSF models; the downstream bit-8 star veto for run 1 is sp_validation's. M33's biased model sits inside bit 8, where galaxies are already cut, so run 1 needs no rerun. A small residual remains in the 0.5–0.7° ring outside M33's manual ellipse (1.15× δe rms, no size bias), noted in #993.

Closes #993.

Claude on behalf of Cail

🤖 Generated with Claude Code

https://claude.ai/code/session_01JK7o9FjcungfGYzSdkjy7z