fix: stale plot_array kwargs break HowToGalaxy chapter 4 tutorial

[Jammy2211]

Overview

The public HowToGalaxy teaching notebook chapter_4_pixelizations/tutorial_3_inversions crashes with TypeError: plot_array() got an unexpected keyword argument 'mask', caught by PyAutoHeart workspace-smoke (run 30858578587, job smoke / run_notebooks (3.12, howtogalaxy, chapter_4_pixelizations), 2026-08-03T22:49:33Z).

That run installed released autolens 2026.7.29.2. The newer 2026.8.4.1 release does not fix it — PyAutoGalaxy main sits at the release commit bf91c570 and the wrapper still rejects mask. This is live breakage in a user-facing tutorial.

The caller is wrong, not the signature — plus a second, larger instance of the same stale-plot-API drift was found in autolens_workspace_developer.

Plan

• Move the HowToGalaxy plot_array call below dataset.apply_mask(...) and drop the mask= kwarg, so the mask-boundary overlay is auto-derived — preserving the author's visual intent rather than just deleting the argument.
• Regenerate the HowToGalaxy notebook and navigator catalogue from the fixed script (never hand-edit the .ipynb).
• Repair the related aplt.Output drift across 10 files in autolens_workspace_developer, which currently raise AttributeError before they even reach the TypeError.
• Verify by re-running the AST detector on the post-fix tree, not by trusting the pre-fix inventory.
• File a separate follow-up prompt for the same drift in autocti_workspace_test and euclid_strong_lens_modeling_pipeline.

Detailed implementation plan

Work Classification

Workspace (both repos are workspace/tutorial repos; no library change).

Affected Repositories

• HowToGalaxy (primary)
• autolens_workspace_developer

Branch Survey

Repository	Current Branch	Dirty?
./HowToGalaxy	main	clean
./autolens_workspace_developer	main	clean

Neither repo is claimed by any active.md worktree — no conflict.

Suggested branch: feature/plot-array-stale-kwargs
Worktree root: ~/Code/PyAutoLabs-wt/plot-array-stale-kwargs/

Root cause

aplt.plot_array resolves to PyAutoGalaxy/autogalaxy/util/plot_utils.py:124, whose parameters are array, title, output_path, output_filename, output_format, colormap, use_log10, vmin, vmax, symmetric, positions, lines, line_colors, grid, cb_unit, ax — no mask. The overlay is derived one layer down at PyAutoArray/autoarray/plot/array.py:128 (if mask is None: mask = auto_mask_edge(array)).

auto_mask_edge returns None for a fully-unmasked array, so it draws nothing. The tutorial's call sits before apply_mask, where dataset.data is still unmasked — which is why the author reached for mask=mask. Measured on the installed stack:

unmasked   -> mask.is_all_false: True  | auto_mask_edge: None
after mask -> mask.is_all_false: False | auto_mask_edge: (156, 2)

So relocating the call below apply_mask restores the intended overlay with no kwarg at all.

An AST sweep of every .py and .ipynb across all ~25 workspace repos found mask= at exactly one logical site. HowToLens and HowToFit are clean.

Implementation Steps

1. HowToGalaxy/scripts/chapter_4_pixelizations/tutorial_3_inversions.py:70 — move the plot below dataset = dataset.apply_mask(mask=mask) and drop the kwarg:

   dataset = dataset.apply_mask(mask=mask)
   
   aplt.plot_array(array=dataset.data, title="Data")

   Matches the canonical idiom in autogalaxy_workspace/markdown/ellipse/fit.md:158.

2. Regenerate notebooks + catalogue from the HowToGalaxy repo root:

   PYTHONPATH=../PyAutoHands/autohands python3 ../PyAutoHands/autohands/generate.py howtogalaxy

   Commit the regenerated .ipynb, llms-full.txt and workspace_index.json — navigator_check.yml gates them.

3. autolens_workspace_developer — aplt.Output no longer exists on the autolens/autogalaxy plot namespace (it survives only as autoarray.plot.Output); its removal was deliberate and is documented in autolens_assistant/AGENTS.md:218. Fixing only the 7 plot_array(output=...) sites would leave these scripts still crashing on adjacent calls (e.g. subplot_tracer(..., output=aplt.Output(...)) at plotting_alignment/plot/imaging/orientation/simulator.py:137-139), so repair the repo's whole drift — 10 files:

   # before
   aplt.plot_array(array=..., output=aplt.Output(path=P, filename=F, format="png"))
   # after
   aplt.plot_array(array=..., output_path=P, output_filename=F, output_format="png")

   Two forms need care beyond a blind rename:

   • scaling_relation_agg/error_make.py:20 binds output = aplt.Output(path=".", format="png") to a variable reused at line 55 — delete the binding, inline flat kwargs at the call site.
   • Flat kwargs differ per callee (subplot_tracer has no output_filename) — check each signature.

Key Files

• HowToGalaxy/scripts/chapter_4_pixelizations/tutorial_3_inversions.py — the CI failure
• autolens_workspace_developer/plotting_alignment/ — 9 of the 10 drifted files
• autolens_workspace_developer/scaling_relation_agg/error_make.py — the variable-bound Output
• PyAutoGalaxy/autogalaxy/util/plot_utils.py:124 — the wrapper signature (read-only reference; not modified)
• PyAutoArray/autoarray/plot/array.py:128 — auto mask-edge derivation (read-only reference)

Verification

1. Reproduce the TypeError on unchanged input first (done — confirmed identical to the CI trace).
2. Run the tutorial from the HowToGalaxy repo root; expect a clean run and a "Data" figure carrying the circular mask boundary:

   NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib \
   PYAUTO_TEST_MODE=1 PYAUTO_SKIP_FIT_OUTPUT=1 PYAUTO_FAST_PLOTS=1 \
   python scripts/chapter_4_pixelizations/tutorial_3_inversions.py

3. Re-run the AST detector on the post-fix tree; require zero remaining out-of-signature plot_array kwargs.
4. Sweep for residual aplt.Output in autolens_workspace_developer; expect zero.
5. That repo has no smoke coverage — compile-check all 10 files, run the cheap non-fitting ones, and state in the PR which were only compile-checked.
6. Regenerate notebooks last, after the script is green.

Out of scope (tracked separately)

• autocti_workspace_test — 27 files with aplt.Output. Unverified: autocti is not installed locally and PyAutoCTI has its own plot namespace that may still export Output.
• euclid_strong_lens_modeling_pipeline/tools/ — psf_size.py, extra_galaxies_centres_gui.py.

Confirmed not bugs: PyAutoArray/test_autoarray/plot/test_output.py (there aplt is autoarray.plot, which does export Output) and the autolens_assistant markdown documenting the removal.

Also noted, not fixed: HowToLens/scripts/chapter_4_pixelizations/tutorial_3_inversions.py:76,190 plots before apply_mask with no kwarg, so it silently draws no mask — a quality gap, not a crash.

Sizing note

The Brain Feature Agent scored this large (score 9) and advised splitting into phases. Overridden to small, no phasing: the score tracks prompt prose length rather than scope (repos_affected = 2), and its "public-API change may ripple downstream" risk does not apply since no library is modified.

Original Prompt

Click to expand starting prompt

In the PyAutoLabs workspace, HowToGalaxy chapter_4_pixelizations fails in
PyAutoHeart's workspace-smoke with:

TypeError: plot_array() got an unexpected keyword argument 'mask'

Evidence: PyAutoHeart workspace-smoke run 30858578587, job
"smoke / run_notebooks (3.12, howtogalaxy, chapter_4_pixelizations)",
2026-08-03T22:49:33Z. That run installed released autolens 2026.7.29.2;
2026.8.4.1 has since published, so first confirm whether the release
already fixes it before assuming it's live.

This is a public teaching notebook so it's user-facing. Find whether the
caller or the plot_array signature is wrong, check for sibling call sites
with the same kwarg across HowToGalaxy/HowToLens/HowToFit and the
workspaces, and fix them all. Route through start_dev.

[Jammy2211]

Shipped — awaiting merge

Both PRs are open and labelled pending-release. Merge is left to a human.

Repo	Commit	PR
HowToGalaxy	5e694d3	#57
autolens_workspace_developer	88c60c8	PyAutoLabs/autolens_workspace_developer#124

Confirmed: the newer release did not fix it

PyAutoGalaxy main is at the 2026.8.4.1 release commit bf91c570 and plot_array still has no mask parameter. The failure was reproduced locally on unchanged input, matching the CI trace exactly, before any edit.

The reported error was one of three

Execution stopped at the first break, so CI never showed the other two. The tutorial is green only because it was re-run after each fix:

1. plot_array(..., mask=mask) — the wrapper has no mask; the overlay is auto-derived from array.mask, but returns None for an unmasked array, and the call sat before apply_mask. Moving it below restores the intended boundary (measured: None → 156 edge coords) rather than merely deleting the kwarg.
2. aplt.subplot_image_and_mapper — not re-exported by autogalaxy.plot; it lives in autoarray.plot, which tutorial_2_mappers.py in this same chapter already imports as aaplt.
3. inversion.reconstruction_to_native — attribute no longer exists; replaced with mapped_reconstructed_operated_data.

A correction worth recording

The first AST sweep hardcoded the alias aplt and missed a call site written aaplt. It was rewritten to resolve aliases from each file's own imports. The original inventory should not be treated as complete.

Verification

• All five chapter_4_pixelizations tutorials green locally (the CI job covers the whole chapter)
• Detector re-run on the post-fix tree: 0 — it correctly still flagged the generated notebook until that was regenerated
• Notebook regenerated via PyAutoHands and confirmed to carry every fix
• Sweep across all ~25 workspace repos: mask= appeared at exactly one logical site; HowToLens and HowToFit clean

Scope honesty on the second repo

autolens_workspace_developer has no smoke coverage and several scripts need FITS data absent from the repo, so its files are compile-checked and signature-verified (112 calls bind cleanly), not run end-to-end. Four of them still will not run — they break earlier on unrelated stale symbols (al.Preloads, al.mapper_indices_from, al.Grid2DIterate). An alias-aware scan found 56 stale symbols repo-wide; that rot is out of scope here.

Follow-ups filed in PyAutoMind (not dropped)

• aplt.Output drift in autocti_workspace_test (27 files, flagged unverified — different library, may be correct as written) and euclid_strong_lens_modeling_pipeline (2 files)
• autolens_workspace_developer broad stale-API rot — triage-first, since some may be dead experiments better condemned than modernised
• HowToLens ch4 t3 plots before apply_mask at lines 76/190, so its mask overlay never draws — quality gap, not a crash

Shipped under an explicit human acknowledgement of Heart YELLOW (score 70, no RED) for exactly two reasons; the first names this very CI run.

[Jammy2211]

Shipped and merged

Repo	PR	Merged
HowToGalaxy	#57	2026-08-04T13:41:20Z
autolens_workspace_developer	#124	2026-08-04T13:41:30Z

Post-merge verification on main: workspace-wide detector 17 → 6, all 6 being the known false positive (a local nested def plot_array(array, name, ...) in autofit_workspace_developer/projects/cosmology/src/analysis.py); zero residual aplt.Output; the merged tutorial carries all three fixes.

Caveat worth recording: HowToGalaxy's own PR CI is structurally blind to this bug — smoke_tests.txt lists only 4 chapter-1 tutorials, and no workflow runs chapter 4 or notebooks. The 6 green checks proved chapter 1 did not regress and the navigator catalogue is consistent; they said nothing about the fix. The evidence is a local run of all five chapter-4 tutorials (5/5 green). The real gate is PyAutoHeart's run_notebooks, which should go green on its next run.

Completion record: PyAutoMind/complete/2026/08/plot-array-stale-kwargs.md. Three follow-ups filed under draft/, including the HowToLens sibling whose mask overlay never draws.