feat: Add direct signal-to-noise over-sampling helper

[Jammy2211]

Overview

Add a direct signal-to-noise threshold helper without a second noise division or adaptive cutoff. Correct the companion adapt-image documentation while preserving the existing workspace idiom.

Plan

• Add the direct S/N helper beside the existing adaptive helper.
• Pin exact threshold behavior and array metadata.
• Correct the galaxy documentation for both return modes.
• Validate public access and downstream compatibility.

Detailed implementation plan

Suggested branch: feature/over-sample-snr-helper

Classification: Library; PyAutoArray primary and PyAutoGalaxy companion. No autolens_workspace edits: the prompt explicitly permits a follow-up sweep and requires its current np.where idiom to keep working. Small, independent.

1. Add over_sample_size_via_snr_from(signal_to_noise_map, signal_to_noise_cut=3.0, sub_size_lower=2, sub_size_upper=4) in autoarray/operators/over_sampling/over_sample_util.py (current path uses over_sampling, not over_sample). Accept the established Array2D input, preserve mask and pixel metadata, return Array2D integer sub-sizes using strictly snr > cut. No division and no auto-lowering. Leave existing helper behavior compatible; clarify its data/noise contract if needed.
2. Confirm export through aa.util.over_sample and downstream al.util.over_sample via existing module exposure; edit exports only if necessary.
3. Extend test_autoarray/operators/over_sample/test_over_sample_util.py: exact np.where equality, below/equal/above cutoff, low-maximum map that must not lower cutoff, negative/zero values, custom sizes, mask preservation, and old helper regression coverage.
4. Correct galaxy_name_image_dict_via_result_from in autogalaxy/analysis/adapt_images/adapt_images.py: default use_model_images=False returns per-galaxy subtracted S/N maps with existing flooring/caching; True returns model images. Correct summary, parameter and Returns prose without altering behavior.
5. Run focused and full PyAutoArray suite; appropriate PyAutoGalaxy suite per ship requirements. Verify downstream al.util.over_sample access and direct np.where equivalence. Ship linked PyAutoArray and PyAutoGalaxy PRs under this member issue, naming the added public API. Defer workspace conversion as the original prompt permits.

Worktree root: /home/jammy/Code/PyAutoLabs/.worktrees/autoarray-bundle-1, created once using Brain's worktree helper with PYAUTO_WT_ROOT inside this workspace. Shared repo worktrees: PyAutoArray, PyAutoGalaxy, autolens_workspace_test. Each member starts from origin/main on its own branch; execute and ship sequentially before switching the shared PyAutoArray worktree. One primary PyAutoArray issue and registry entry per member, linked companion PRs per repository as explicitly authorized. No merges.

Branch survey: PyAutoArray, PyAutoGalaxy and autolens_workspace_test canonical checkouts are clean on main. No target repo claims in active.md. Heart reports an unregistered sparse-operator-oversampling-cache/PyAutoArray worktree with 11 dirty files: preserve it and obtain overlap acknowledgement before setup. Recent PyAutoArray branches: main, feature/sparse-operator-oversampling-cache, chore/session-start-hook-regen, feature/delaunay-area-magnification-audit, claude/autonerves-floor-regime-stamp. Recent PyAutoGalaxy branches: main, chore/session-start-hook-regen. Recent autolens_workspace_test branches: main, feature/point-audits-wheel-provenance, feature/point-solver-image-accuracy, feature/point-solver-duplicate-policy, chore/session-start-hook-regen.

Execution: one native Sol delegate per member, sequential within shared repositories. Parent owns judgment and lifecycle. Pass the approved issue plan, branch, exact starting commit, worktree, permitted files, validation requirements; stop and return exact failure evidence rather than weakening tests. Full logs stay in ignored scratch. Applicable full library suites and workspace smoke checks, authoritative Heart verdict, then ship separately. Report counts without inventing results; CI must check Python 3.12 and 3.13. No tests have yet run for this bundle.

Original Prompt

Click to expand starting prompt

Add over_sample_size_via_snr_from so a signal-to-noise map can steer over-sampling without a second division

Type: feature
Target: PyAutoArray
Repos:

• PyAutoArray
• PyAutoGalaxy
• autolens_workspace
  Difficulty: small
  Autonomy: supervised
  Priority: medium
  Status: draft
  Issued: 2026-09-03
  Consequence: glance
  Witness: al.util.over_sample.over_sample_size_via_snr_from(signal_to_noise_map, signal_to_noise_cut=3.0, sub_size_lower=2, sub_size_upper=4) exists, thresholds its input once with no auto-lowering of the cut, and a unit test pins that its {2, 4} map equals np.where(snr > cut, 4, 2) exactly; the docstring of galaxy_name_image_dict_via_result_from says it returns a signal-to-noise map.
  Review-minutes: 3
  Unattended: ready

Split out of over-sample-snr-double-division at close-out (autolens_workspace#523, record
complete/2026/09/over-sample-snr-double-division.md, scope item 4). The workspace side shipped
without any library change: every SLaM pipeline now thresholds the source S/N map directly with
np.where(source_image_raw > 3.0, 4, 2).

What is wrong in the library today:

• over_sample_size_via_adapt_from(data, noise_map, signal_to_noise_cut=5.0, ...) is named as if it
  took an adapt image but its first line is signal_to_noise = data / noise_map. Every caller in the
  organism handed it the per-galaxy map from galaxy_name_image_dict_via_result_from, which is already
  subtracted_image / noise_map, so the S/N was divided by the noise twice (~18x inflation on HST-depth
  data; ~90 % of the mask at sub-size 4 instead of ~30 %).
• It defaults the cut to 5.0 and silently lowers it when max(S/N) < 2 * cut, so it cannot express
  "S/N > 3 → 4" even with the right inputs.
• galaxy_name_image_dict_via_result_from (PyAutoGalaxy) has a docstring saying "model image"; it
  returns subtracted_signal_to_noise_maps_of_galaxies_dict.

Decide and implement one of:

1. Add over_sample_size_via_snr_from(signal_to_noise_map, signal_to_noise_cut, sub_size_lower, sub_size_upper) in autoarray/operators/over_sample/over_sample_util.py beside the existing
   helper, no auto-lowering, and point the workspace idiom at it in a follow-up workspace sweep; or
2. Rename the existing helper's data parameter (e.g. image) and make its docstring state that it
   divides by the noise map itself, so passing an S/N map reads as the misuse it is.

Either way fix the PyAutoGalaxy docstring. Keep the workspace's direct np.where idiom working; the
assistant skill al_adaptive_pixelization.md documents that idiom and the never-do-this.

[Jammy2211]

PRs opened

• PyAutoArray: feat: Add direct signal-to-noise over-sampling helper #606 (54c360be)
• PyAutoGalaxy: docs: Clarify adapt-image signal-to-noise return values PyAutoGalaxy#644 (ba7c70dc)

Validation: PyAutoArray 1,922 passed / 0 failed; PyAutoGalaxy 1,307 passed / 0 failed; focused 23 passed; downstream API and exact threshold equivalence passed. Heart GREEN. Python 3.13 remains for CI.

Full logs: .worktrees/autoarray-bundle-1/scratch/snr-helper/. Both PRs carry pending-release. Existing workspace idiom unchanged; no migration needed. Approved linked-PR scope preserved. Shared Array worktree now proceeds to the next independent bundle member. Awaiting human merge; no automatic monitoring armed.

[Jammy2211]

over-sample-snr-helper

Issue: #602
Date: 2026-10-02

Shipped

Added direct S/N threshold over-sampling helper and clarified Galaxy adapt-image documentation. Array1922passed; Galaxy1307passed; focused23passed; downstream equivalence passed.

• feat: Add direct signal-to-noise over-sampling helper #606

• docs: Clarify adapt-image signal-to-noise return values PyAutoGalaxy#644

• pending-release: PyAutoArray@feat: Add direct signal-to-noise over-sampling helper #606

• pending-release: PyAutoGalaxy@docs: Clarify adapt-image signal-to-noise return values PyAutoGalaxy#644

Human authorized linked PRs, development shipping with exact Heart YELLOW acknowledgment, then merge and full close-out. Every head run and matrix leg was checked; merge receipts are recorded by GitHub. No release performed. Shared bundle worktree cleanup follows all four members; logs and data preserved under organs/PyAutoMind/tmp/autoarray-bundle-1-closeout/.

For workspace conflict updates, the human explicitly acknowledged generated organism-map and public front-door table drift (one mismatch each); stale release rehearsal evidence remained disclosed. Only smoke manifest entries were reconciled; scripts unchanged.