docs: fill plot.py coverage gaps vs source *_plots.py (+2 missing autolens exports)

[Jammy2211]

Overview

Direct follow-on to plot-guides-restructure. That task created the per-dataset plot.py family across both workspaces and closed the AG→AL export asymmetry via PyAutoGalaxy#538 — but it restructured, it did not enumerate. It never audited whether each plot.py demonstrates the full set of plotting functions its dataset/fit type actually has.

An audit of every public function in the source *_plots.py modules against every aplt.* call in both workspaces shows substantial gaps. Most visibly, autolens_workspace/scripts/imaging/plot.py calls subplot_fit_imaging and nothing else: subplot_fit_imaging_log10, subplot_fit_imaging_of_planes and subplot_fit_imaging_tracer appear nowhere in the entire workspace. That file's own __Visualizer__ section even names subplot_of_planes in prose while never demonstrating it, and hand-rolls a fit.model_images_of_planes_list loop in its place.

The audit also surfaced two genuine library gaps: autolens/plot/__init__.py is missing two exports, which is why the AL interferometer example has no dataset subplot while its AG counterpart does. This task fixes those first, then fills the workspace coverage.

Plan

1. Library first (PyAutoLens): add two missing exports to autolens/plot/__init__.py — subplot_interferometer_dataset and subplot_fit_interferometer_combined. This is the mirror of PyAutoGalaxy#538, which closed the same asymmetry in the other direction. Merges before the workspace leg.
2. autolens_workspace: fill five plot.py files with the dataset/fit-level functions they omit, plus a fits_* output section.
3. autogalaxy_workspace: same for two plot.py files.
4. Deliberately excluded: the *_x1_plane pair (unreachable — subplot_fit self-dispatches to them for single-plane tracers), subplot_ellipse_errors (needs a posterior), results/search plots (belong in guides/).
5. Validate by sequential test-mode runs with visualization on, then re-run the coverage matrix on the output to prove the gaps actually closed.

Detailed implementation plan

Work Classification

Both (library → workspace). Worktree root: ~/Code/PyAutoLabs-wt/plot-coverage-gaps/

Affected Repositories

• PyAutoLens (primary) — two additive exports; merges first
• autolens_workspace — five plot.py scripts
• autogalaxy_workspace — two plot.py scripts

Branch Survey

Repository	Current Branch	Dirty?
./PyAutoLens	main	clean
./autolens_workspace	main	clean
./autogalaxy_workspace	main	clean

Suggested branch: feature/plot-coverage-gaps

worktree_check_conflict flagged PyAutoLens as claimed by python-312-floor — hand-verified stale: git -C PyAutoLens worktree list shows a single canonical worktree on main, main has moved 3 commits past the claimed b40fb0ba, and python-312-floor records next-phase: none — all phases complete. Those - Repo lines are a completion record, not a live claim.

Evidence method

Enumerate every public function in the source *_plots.py modules, resolve what aplt actually exports by introspecting the installed stack (not by reading __init__.py), then grep every aplt.* call across both workspaces, bucketed as demoed-in-a-plot.py / used-elsewhere / never-used.

Implementation Steps

1. PyAutoLens — autolens/plot/__init__.py

• Add subplot_interferometer_dataset to the existing from autoarray.dataset.plot.interferometer_plots import (...) block. autogalaxy.plot exports it from that same module; autolens.plot imports only subplot_interferometer_dirty_images and fits_interferometer and skips it. Consequence: autolens_workspace/scripts/interferometer/plot.py has no dataset subplot while its autogalaxy counterpart does — the function is unreachable, so this is not a workspace gap.
• Add subplot_fit_interferometer_combined to the from autolens.interferometer.plot.fit_interferometer_plots import (...) block. It is autolens's own function, unexported, while the imaging equivalent subplot_fit_combined is exported.
• Verified by import, not by reading source: set(dir(autogalaxy.plot)) - set(dir(autolens.plot)) == {subplot_fit_imaging_list, subplot_interferometer_dataset}. (subplot_fit_imaging_list is deliberate — AL uses subplot_fit_combined instead.)
• Both changes are additive; no behaviour change. Explicitly not touching subplot_fit_dirty_images / subplot_fit_real_space, which currently resolve to the autogalaxy implementations inside autolens.plot, shadowing autolens's own versions that take lensing-specific image_plane_lines / source_plane_lines args — rebinding an exported name is a behaviour change and belongs in its own prompt.

2. autolens_workspace

• scripts/imaging/plot.py — add subplot_fit_imaging_log10; subplot_fit_imaging_of_planes (keep the existing model_images_of_planes_list section, which demos attribute access, and add the subplot the Visualizer prose already names); subplot_fit_imaging_tracer; a fits_imaging output section; one prose line noting subplot_fit auto-switches to a 2×3 layout for single-plane tracers.
• scripts/interferometer/plot.py — add subplot_interferometer_dataset (gated on the library merge), subplot_fit_interferometer_real_space, subplot_fit_interferometer_tracer, fit-level subplot_fit_dirty_images, fits_interferometer.
• scripts/weak/plot.py — add plot_data_vs_model, plot_residuals, plot_chi_squared_map, plot_convergence_map.
• scripts/cluster/plot.py — add plot_image_group_zooms, plot_critical_curves, plot_caustics.
• scripts/point_source/plot.py — add subplot_point_dataset.

3. autogalaxy_workspace

• scripts/imaging/plot.py — add subplot_fit_imaging_of_galaxy, fits_imaging.
• scripts/interferometer/plot.py — add subplot_fit_real_space, fit-level subplot_fit_dirty_images, fits_interferometer.

Note the two distinct dirty-image functions: dataset-level subplot_interferometer_dirty_images (already demoed) vs fit-level subplot_fit_dirty_images (missing from both workspaces' plot.py).

Excluded, with reasons

• subplot_fit_imaging_x1_plane / subplot_fit_imaging_log10_x1_plane — do not add as calls. subplot_fit dispatches to them itself (fit_imaging_plots.py:214, :346, :512) when len(fit.tracer.planes) == 1. On the two-plane example fits in plot.py they are unreachable by design; demoing them would teach a wrong idiom. Cover with one prose line.
• subplot_ellipse_errors — needs fit_pdf_list: List[List[FitEllipse]], one inner list per posterior sample. A standalone plot.py has no search. File as its own follow-up prompt.
• Results/search plots (subplot_parameters, log_likelihood_vs_iteration, output_figure, corner_anesthetic) — belong to guides/plot/searches.py and guides/results/. Separate audit.
• Tracer/galaxy/profile subplots stay in guides/ (guides/tracer.py, guides/galaxies.py, guides/plot/start_here.py) where already covered — do not duplicate.

Risks / trade-offs

• The fits_* sections write files. They must target an ignored output path or these scripts will leak binaries into the repo — pre-flight git diff --stat before any commit (ship_workspace has leaked binary outputs before).
• Every added call must be executed, not just written. Run sequentially: parallel workspace runs fake failures through shared state.
• Library/workspace merge order: the interferometer dataset subplot cannot land in the workspace until the PyAutoLens export merges.

Testing approach

Sequential test-mode runs with visualization on for every touched script (the restructure task's bar was 13/13 AL, 10/10 AG). Then re-run the aplt coverage matrix against the edited files to prove the gaps actually closed, rather than trusting the edit.

Key Files

• PyAutoLens/autolens/plot/__init__.py — the two additive exports
• autolens_workspace/scripts/{imaging,interferometer,weak,cluster,point_source}/plot.py
• autogalaxy_workspace/scripts/{imaging,interferometer}/plot.py

Process notes

Brain override. The Feature Agent returned too-large (score 15) and a 4-phase split (design / core_api / workspace_examples / docs). Overridden to one combined library→workspace task — it scored 3 repos, not the work; there is no design left (the audit is the design) and no core API beyond two import lines. Precedent: vacuous-jax-assertions (large/8 → small), multiband-pyloop-batching.

Heart at intake. STALE 75 — test run status unknown (no report.json), release validation stale: source moved since rehearsal (PyAutoFit, PyAutoArray, PyAutoGalaxy, PyAutoLens). Both unrelated to this docs change.

Original Prompt

Click to expand starting prompt

plot.py function coverage gaps vs the source *_plots.py modules

Direct follow-on to plot-guides-restructure (complete/2026/07). That task
created the per-dataset plot.py family and closed the AG→AL export asymmetry
via PyAutoGalaxy#538. It did not audit whether each plot.py demonstrates
the full set of plotting functions its dataset/fit type actually has — it
restructured, it did not enumerate. This task closes that.

Two legs: a small library export fix in PyAutoLens (the mirror of #538,
which went the other direction), then the workspace coverage fill.

Evidence

Method: enumerate every public function in the source *_plots.py modules,
resolve what aplt actually exports by introspecting the installed stack
(not by reading __init__.py), then grep every aplt.* call across both
workspaces, bucketed as demoed-in-a-plot.py / used-elsewhere / never-used.

Confirmed: autolens_workspace/scripts/imaging/plot.py calls
subplot_fit_imaging only. subplot_fit_imaging_log10,
subplot_fit_imaging_of_planes and subplot_fit_imaging_tracer appear
nowhere in the entire workspace. The file's own __Visualizer__ section
even names subplot_of_planes in prose while never demonstrating it, and
hand-rolls a fit.model_images_of_planes_list loop in its place.

Library leg — PyAutoLens

autolens/plot/__init__.py is missing two exports:

• subplot_interferometer_dataset — autogalaxy.plot exports it from
  autoarray.dataset.plot.interferometer_plots; autolens.plot imports only
  subplot_interferometer_dirty_images and fits_interferometer from that same
  module and skips it. Consequence: autolens_workspace/scripts/interferometer/plot.py
  has no dataset subplot while its autogalaxy counterpart does — the
  function is unreachable, so this is not a workspace gap.
• subplot_fit_interferometer_combined — autolens's own function in
  autolens/interferometer/plot/fit_interferometer_plots.py, unexported, while
  the imaging equivalent subplot_fit_combined is exported.

Verified by import, not by reading source:
set(dir(autogalaxy.plot)) - set(dir(autolens.plot)) =
{subplot_fit_imaging_list, subplot_interferometer_dataset}. (subplot_fit_imaging_list
is deliberate — AL uses subplot_fit_combined instead.)

Also noted, not in scope: aplt.subplot_fit_dirty_images and
aplt.subplot_fit_real_space resolve to the autogalaxy implementations
inside autolens.plot, shadowing autolens's own versions which take
lensing-specific image_plane_lines / source_plane_lines args. Worth a
separate prompt — changing what an existing exported name resolves to is a
behaviour change, not an additive export.

Workspace leg

Each plot.py demonstrates the dataset- and fit-level functions for its own
data type, plus a fits_* output section. Tracer/galaxy/profile subplots stay
in guides/ (guides/tracer.py, guides/galaxies.py,
guides/plot/start_here.py) where they are already covered — do not duplicate.

autolens_workspace

File	Add
scripts/imaging/plot.py	subplot_fit_imaging_log10, subplot_fit_imaging_of_planes, subplot_fit_imaging_tracer, fits_imaging
scripts/interferometer/plot.py	subplot_interferometer_dataset (needs the library leg), subplot_fit_interferometer_real_space, subplot_fit_interferometer_tracer, fit-level subplot_fit_dirty_images, fits_interferometer
scripts/weak/plot.py	plot_data_vs_model, plot_residuals, plot_chi_squared_map, plot_convergence_map
scripts/cluster/plot.py	plot_image_group_zooms, plot_critical_curves, plot_caustics
scripts/point_source/plot.py	subplot_point_dataset

autogalaxy_workspace

File	Add
scripts/imaging/plot.py	subplot_fit_imaging_of_galaxy, fits_imaging
scripts/interferometer/plot.py	subplot_fit_real_space, fit-level subplot_fit_dirty_images, fits_interferometer

Note the two distinct dirty-image functions: dataset-level
subplot_interferometer_dirty_images (already demoed) vs fit-level
subplot_fit_dirty_images (missing in both workspaces' plot.py).

Explicitly excluded

• subplot_fit_imaging_x1_plane / subplot_fit_imaging_log10_x1_plane —
  do not add as calls. subplot_fit dispatches to them itself
  (fit_imaging_plots.py:214, :346, :512) when
  len(fit.tracer.planes) == 1. On the two-plane example fits in plot.py they
  are unreachable by design; demoing them would teach a wrong idiom. Cover with
  one prose line noting subplot_fit auto-switches layout for single-plane
  tracers.
• subplot_ellipse_errors — needs fit_pdf_list: List[List[FitEllipse]],
  one inner list per posterior sample. A standalone plot.py has no search, so
  this needs a real model-fit. File as its own follow-up prompt.
• Results/search plots (subplot_parameters, log_likelihood_vs_iteration,
  output_figure, corner_anesthetic) — belong to guides/plot/searches.py
  and guides/results/, not the per-dataset plot.py. Several are used
  nowhere; a separate audit.

Validation

Sequential test-mode runs with visualization on for every touched script (the
restructure task's own bar: 13/13 AL, 10/10 AG). Parallel runs fake failures
through shared state — baseline sequentially.

Re-run the coverage matrix on the output to prove the gaps actually closed,
rather than trusting the edit.

Repos

• @PyAutoLens — autolens/plot/__init__.py, two additive exports. Merges first.
• @autolens_workspace — five plot.py scripts.
• @autogalaxy_workspace — two plot.py scripts.

Original request (verbatim)

we just finished a task refactoring all the plot.py files in the workspce, but I
think we are missing some plot fuhnctions. For example, imaging/plot.py has
subplot_fit but not subplot_fit_log10, subplot_of_planes, etc. Do a better
comparison of the *_plots.py files in the source code and the plot.py in the
workspace and fill in the gaps across autolens and autogalaxy

Scope decisions taken by the human at intake:

• Library + workspace (fix the two missing PyAutoLens exports, library merges first).
• Also add fits_* output sections to each plot.py.
• Skip subplot_ellipse_errors; file a follow-up.

[Jammy2211]

Library PR Created

PR: #668 (pending-release)
Commit: c3c00874c on feature/plot-coverage-gaps

API changes

Added-only; nothing removed, renamed, or resignatured.

• aplt.subplot_interferometer_dataset — re-export of autoarray.dataset.plot.interferometer_plots.subplot_interferometer_dataset, already exported by autogalaxy.plot
• aplt.subplot_fit_interferometer_combined — re-export of autolens's own autolens.interferometer.plot.fit_interferometer_plots.subplot_fit_interferometer_combined

aplt export count 61 → 63. set(dir(autogalaxy.plot)) - set(dir(autolens.plot)) now reduces to just {subplot_fit_imaging_list} (deliberate — AL uses subplot_fit_combined).

Verification

• Full PyAutoLens suite in the task worktree: 488 passed, 0 failed (66.75s)
• Both names resolve to the expected modules, asserted against the worktree copy of autolens rather than the installed stack
• git diff --stat = 2 files, 5 insertions, 1 deletion

Heart at ship time: verdict: stale, score 75, with red_reasons: [] and yellow_reasons: [] — both entries are stale_reasons (test run status unknown (no report.json); release validation stale: source moved since rehearsal). Out-of-date evidence rather than a failure; acknowledged by the human before ship.

Workspace impact

Option (i) new demos. Grep across all workspace scripts/ trees found the two new symbols used only by autogalaxy's own pre-existing calls (autogalaxy_workspace/scripts/interferometer/{plot,fit}.py) — which are unaffected, since AG already exported subplot_interferometer_dataset. Zero autolens usage, confirming the symbol was genuinely unreachable from autolens.plot. No migration needed.

Next: /start_workspace for the 7 plot.py files — autolens_workspace (imaging, interferometer, weak, cluster, point_source) and autogalaxy_workspace (imaging, interferometer). The AL interferometer dataset subplot depends on this PR's first export; the workspace scripts will be validated against the branch build via the shared task worktree, but the workspace PR stays behind the library-first merge gate.

[Jammy2211]

Workspace PRs Created — all three legs open

Repo	PR	Commit
PyAutoLens (library)	#668	c3c00874c
autolens_workspace	PyAutoLabs/autolens_workspace#404	72ff4e6f
autogalaxy_workspace	PyAutoLabs/autogalaxy_workspace#191	c9746d0

All three carry pending-release.

Merge order

PyAutoLens#668 must merge first. autolens_workspace/scripts/interferometer/plot.py now calls aplt.subplot_interferometer_dataset, which only exists after that PR. autogalaxy_workspace#191 has no such dependency and is safe to merge independently.

Nothing has been merged — merge stays a human decision.

What shipped

7 plot.py scripts, +302 lines of examples (plus regenerated notebooks).

• imaging (AL) — subplot_fit_imaging_of_planes, subplot_fit_imaging_log10, subplot_fit_imaging_tracer, fits_imaging
• interferometer (AL) — subplot_interferometer_dataset, fit-level subplot_fit_dirty_images, subplot_fit_interferometer_real_space, subplot_fit_interferometer_tracer, fits_interferometer
• weak (AL) — plot_convergence_map, plot_data_vs_model, plot_residuals, plot_chi_squared_map
• cluster (AL) — plot_image_group_zooms, plot_critical_curves, plot_caustics
• point_source (AL) — subplot_point_dataset
• imaging (AG) — subplot_fit_imaging_of_galaxy, use_log10 variant, fits_imaging
• interferometer (AG) — fit-level subplot_fit_dirty_images, subplot_fit_real_space, fits_interferometer

plot.py coverage: 18 → 36 of 63 exported symbols (autolens_workspace), 11 → 14 of 28 (autogalaxy_workspace).

Validation

• All 7 scripts executed sequentially in test mode with visualization on, against the branch build of PyAutoLens via a shared task worktree. 7/7 ran to completion.
• Coverage matrix re-run against the edited files rather than trusting the edits: 22/22 planned gaps closed; the excluded *_x1_plane pair confirmed called nowhere.
• Leak check clean in both repos. The fits_* sections write to output/plot/… (gitignored, verified with git check-ignore); the written FITS was opened and confirmed to hold MASK, DATA, PSF, NOISE_MAP.
• Notebook regeneration touched exactly the 7 notebooks plus the two catalogue files — no unrelated drift.

One honest gap

subplot_fit_interferometer_combined was exported in #668 for API symmetry with imaging's subplot_fit_combined, but is not demonstrated anywhere. It takes a fit_list, so its home is a multi-dataset interferometer example rather than the single-fit interferometer/plot.py — passing [fit, fit] would teach a wrong idiom. Recorded as a follow-up below.

Follow-ups filed as Mind drafts (not issues)

1. Demo subplot_fit_interferometer_combined in a multi-dataset interferometer example.
2. Demo subplot_ellipse_errors — needs a posterior fit_pdf_list, so it needs a real ellipse model-fit.
3. docs/api/plot.rst omits several already-exported symbols (subplot_imaging_dataset, subplot_imaging_dataset_list, fits_imaging, fits_interferometer, subplot_fit_interferometer_tracer, subplot_interferometer_dirty_images).
4. aplt.subplot_fit_dirty_images and aplt.subplot_fit_real_space resolve to the autogalaxy implementations inside autolens.plot, shadowing autolens's own versions which accept lensing-specific image_plane_lines / source_plane_lines. Rebinding an exported name is a behaviour change, so it was kept out of feat: export subplot_interferometer_dataset + subplot_fit_interferometer_combined #668.

[Jammy2211]

Shipped — all three PRs merged

Repo	PR	Merge commit
PyAutoLens	#668	45ac1dbaf
autogalaxy_workspace	PyAutoLabs/autogalaxy_workspace#191	6ca53f89c
autolens_workspace	PyAutoLabs/autolens_workspace#404	5b558f5c2

Merged in the required order: the library export first, then the workspaces.

Post-merge integration check

Verified against the canonical merged mains (not the task worktree — asserted autolens.__file__ is outside PyAutoLabs-wt), which is what catches a merge-order mistake that per-PR CI cannot:

• aplt.subplot_interferometer_dataset and aplt.subplot_fit_interferometer_combined both resolve on merged PyAutoLens main.
• autolens_workspace/scripts/interferometer/plot.py — the merge-order-critical script — runs to completion (exit 0) on merged mains.
• autogalaxy_workspace/scripts/interferometer/plot.py runs to completion (exit 0).
• Both canonical workspace checkouts are clean afterwards; the fits_* sections wrote only into gitignored output/plot/.

CI at merge: PyAutoLens 5/5 green; autogalaxy_workspace 10/10 green; autolens_workspace 10/10 green (both runs × both matrix legs each — the smoke matrix produces two runs per head, and all legs were checked).

Final state

plot.py coverage: 18 → 36 of 63 exported symbols (autolens_workspace), 11 → 14 of 28 (autogalaxy_workspace). 22/22 planned gaps closed, verified by re-running the coverage matrix against the edited files rather than trusting the edits.

Note the workspace mains now call aplt.subplot_interferometer_dataset, which is unreleased — both workspace PRs carried pending-release, so this is expected until the next release publishes.

Follow-ups

Recorded as Mind drafts in draft/docs/workspaces/plot_coverage_followups.md, deliberately not bulk-issued:

1. Demo subplot_fit_interferometer_combined — exported here for API symmetry but demonstrated nowhere; needs a multi-dataset interferometer context.
2. Demo subplot_ellipse_errors — needs a real posterior fit_pdf_list.
3. docs/api/plot.rst omits 6 already-exported symbols.
4. autolens.plot shadows its own subplot_fit_dirty_images with autogalaxy's — the autolens version taking image_plane_lines is reachable under no exported name at all.

Leaving this issue open for #4 in particular, which is a live (if minor) API defect. Close whenever you're happy.

[Jammy2211]

Follow-up 4 resolved — PyAutoLens#670 merged (339867e2c)

The shadowing defect is fixed additively: subplot_fit_interferometer_dirty_images now exports autolens's own function, so it is reachable for the first time.

subplot_fit_dirty_images is deliberately left bound to the autogalaxy version. The two signatures diverge (residuals_symmetric_cmap on the AG side, image_plane_lines / image_plane_line_colors on the AL side), so rebinding it would be a behaviour change rather than an additive export. This matches the convention already in the file — subplot_fit_real_space (AG) has long coexisted with subplot_fit_interferometer_real_space (AL); subplot_fit_dirty_images had simply never been given its counterpart.

Worth recording: the AL version is not a duplicate

With image_plane_lines=None it auto-derives the tracer's critical curves from the fit via _compute_critical_curve_lines and overlays them on the dirty model image — lensing information the autogalaxy version cannot produce. Verified functionally on a real FitInterferometer (1 curve derived), not just signature-checked.

Verification

• Full PyAutoLens suite: 488 passed, 0 failed. CI 5/5 green.
• Additivity asserted against the branch build and again on canonical merged main: new name → autolens.…, old name → autogalaxy.… (unchanged).
• Diff: 2 files, 2 insertions, 0 deletions.

One sub-item deliberately deferred

autolens_workspace still calls the autogalaxy-bound aplt.subplot_fit_dirty_images at 11 sites — scripts/interferometer/{fit,modeling,plot}.py, four scripts/interferometer/features/*/fit.py, and scripts/multi/features/imaging_and_interferometer/modeling.py. All pass fit=fit only, so all 11 could switch to the new name and gain critical-curve overlays for free.

Not done here: that is a visual change across 11 lens examples and deserves its own review pass rather than riding along with an export fix. Recorded in draft/docs/workspaces/plot_coverage_followups.md.

Follow-ups 1-3 (demo subplot_fit_interferometer_combined, demo subplot_ellipse_errors, docs/api/plot.rst omissions) remain open in that same file.

[Jammy2211]

Closing — all four PRs merged

PR	Merge commit
PyAutoLens#668 — the two missing exports	45ac1dbaf
autogalaxy_workspace#191 — 2 plot.py files	6ca53f89c
autolens_workspace#404 — 5 plot.py files	5b558f5c2
PyAutoLens#670 — subplot_fit_interferometer_dirty_images (follow-up 4)	339867e2c

plot.py coverage: 18 → 36 of 63 exported symbols (autolens_workspace), 11 → 14 of 28 (autogalaxy_workspace). 22/22 planned gaps closed, verified by re-running the coverage matrix against the edited files.

Remaining work is tracked as Mind drafts in draft/docs/workspaces/plot_coverage_followups.md, deliberately not bulk-issued:

1. Demo subplot_fit_interferometer_combined — exported, demonstrated nowhere (needs a multi-dataset interferometer context).
2. Demo subplot_ellipse_errors — needs a real posterior fit_pdf_list.
3. docs/api/plot.rst omits 6 already-exported symbols and has no dataset heading.
4. (sub-item) Switch the 11 autolens_workspace call sites from subplot_fit_dirty_images to subplot_fit_interferometer_dirty_images — a visual change across 11 lens examples, wants its own review pass.

Note the workspace mains call aplt.subplot_interferometer_dataset, which is unreleased; both workspace PRs carried pending-release, so this resolves at the next release.