Add cr_method dial (per-frame deepCR route) and PSF star-pass decoupling (#61, #62)

[Jammy2211]

Summary

Implements the maintainer-triaged scope for community issues #61 and #62 (@samlange04): a user-facing cosmic-ray-method dial and the decoupling of PSF-star measurement from the shipped science CR pass. The science default is deliberately unchanged — flipping it remains gated on the SLACS validation with a tuned-driz_cr comparison arm, so this PR does not close either issue.

1. TargetSpec.cr_method: "driz_cr" (default) | "deepcr" (#61)

• "driz_cr" — today's STScI route, byte-identical kwargs to before (pinned by a regression test that also asserts no resetbits key appears).
• "deepcr" — per-frame CR masking then plain weighted-mean drizzle (driz_cr=median=blot=False), eliminating the blotted-median reference that reads systematically low at steep gradients (driz_cr (median/blot CR rejection) systematically erodes flux at steep-gradient cores — consider LACosmic per-frame masking as the default #61's ~37% core-flux erosion). Masks are written into each exposure's DQ as the AstroDrizzle CR bit (4096) via a pure, idempotent dq_with_cr_flags (bit cleared before rewrite).
• The driz_cr (median/blot CR rejection) systematically erodes flux at steep-gradient cores — consider LACosmic per-frame masking as the default #61 resetbits trap is pinned by a unit test: the deepcr route must emit resetbits=0 — AstroDrizzle's default (4096) clears exactly the bit the masks live in, silently producing an unmasked drizzle.
• Naming: the reporter used LACosmic; this repo's established per-frame CR machinery is deepCR (package/cosmic_rays.py, already used by frame products), so that is reused rather than adding an astroscrappy dependency — and the dial is honestly named "deepcr". Same method class (per-frame, no median reference). An actual LACosmic backend would be a follow-up.
• Fail-fast in reduce_target: deepcr on non-astrodrizzle backends or instruments without a registered deepCR model (e.g. wfc3_ir, whose CRs calwf3 already flags per-frame) is rejected before any download.

2. PSF star-pass decoupling: TargetSpec.psf_star_pass: "auto" (default) | "science" | "no_cr" (#62)

• _psf now draws star finding and stamp extraction from _star_pass_image(...) instead of unconditionally from the science mosaic.
• "auto" never adds a drizzle: it uses the least-CR-rejected pass that costs nothing extra (which today is the science mosaic — on driz_cr runs AstroDrizzle keeps no less-rejected intermediate, and the median image is the biased reference itself), and always records why.
• "no_cr" is the explicit opt-in second AstroDrizzle pass on the identical grid/kernel/pixfrac with CR DQ flags treated as good (final_bits | 4096) and resetbits=0 so the science pass's flags survive in the inputs.
• Provenance can't silently regress: the reduction.json psf block always records star_source_pass (+ reason or the star-pass kwargs), and the drizzle block records cr_method (+ per-frame model/threshold/bit/pixel counts when active) — the Tier-1 empirical ePSF is built from the CR-rejected mosaic — field-star cores get masked before DAOStarFinder ever sees them #62 wiring requirement.

3. Design doc

docs/design/hst_acs_pipeline.md Stage 3 documents the dial as a lensing-motivated deviation-in-waiting: default stays STScI driz_cr; the flip decision is human-gated on SLACS reference-bar validation comparing deepCR against tuned driz_cr (driz_cr_scale/snr 1.5/1.2 per published STScI reprocessing, vs the 1.2/0.7 pipeline defaults we currently inherit). Stage 5 documents the star-pass decoupling.

Tests

19 new unit tests (numpy/astropy-only, house style): kwargs regressions for both routes and the single-exposure branch, the resetbits trap, DQ bit write/idempotence/shape-mismatch, star-pass decision matrix incl. single-exposure never re-drizzling, and the fail-fast set. Full suite: 265 passed, 15 skipped (baseline 246/15) — verified independently of the implementing agent.

Honest gaps

• The deepcr drizzle route and the no_cr star pass are exercised through unit-tested pure functions and monkeypatched plumbing — no drizzlepac/deepCR execution or real-data validation in this environment.
• The SLACS validation (incl. the tuned-driz_cr arm) has not run; the default flip and therefore driz_cr (median/blot CR rejection) systematically erodes flux at steep-gradient cores — consider LACosmic per-frame masking as the default #61/Tier-1 empirical ePSF is built from the CR-rejected mosaic — field-star cores get masked before DAOStarFinder ever sees them #62 closure remain pending.
• psf_star_pass="no_cr" + psf_backend="starred" weights stamps with the science-pass noise map (documented approximation; the passes differ only in CR-rejected pixels).
• JWST image3's outlier_detection has the analogous median-reference failure mode; cr_method there is rejected, not addressed — out of scope.
• apply_per_frame_cr_masks mutates cached FLC DQ arrays in place (idempotently, bit cleared first) — the same behaviour class as driz_cr itself, but reviewer attention welcome.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UBpwwfzbewbMLhE137h231

---

Generated by Claude Code