From 1f57b8e3e46543091f97970b1535e16a4cc7dd25 Mon Sep 17 00:00:00 2001
From: Jammy2211 <JNightingale2211@gmail.com>
Date: Tue, 10 Mar 2026 20:04:05 +0000
Subject: [PATCH] docs(aggregator): add module-level docstrings to aggregator
 package
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add module-level docstrings to all four substantive modules in
autolens/aggregator/:

- tracer.py: TracerAgg — loads Tracer objects from PyAutoFit fit results
- fit_imaging.py: FitImagingAgg — assembles FitImaging objects offline
- fit_interferometer.py: FitInterferometerAgg — assembles FitInterferometer
  objects offline
- subhalo.py: SubhaloAgg — grid-search result collation for dark-matter
  subhalo detection

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 autolens/aggregator/fit_imaging.py        | 16 ++++++++++++++++
 autolens/aggregator/fit_interferometer.py | 17 +++++++++++++++++
 autolens/aggregator/subhalo.py            | 12 ++++++++++++
 autolens/aggregator/tracer.py             | 16 ++++++++++++++++
 4 files changed, 61 insertions(+)

diff --git a/autolens/aggregator/fit_imaging.py b/autolens/aggregator/fit_imaging.py
index 578423da1..0f9a12e8f 100644
--- a/autolens/aggregator/fit_imaging.py
+++ b/autolens/aggregator/fit_imaging.py
@@ -1,3 +1,19 @@
+"""
+Aggregator interface for loading ``FitImaging`` objects from lens model-fit results.
+
+This module assembles ``FitImaging`` instances offline by combining the imaging dataset,
+``Tracer``, dataset model, and adapt images stored in a ``PyAutoFit`` output directory or
+SQLite database — reproducing exactly the fit that was evaluated during the original
+non-linear search.
+
+Two public objects are provided:
+
+- ``_fit_imaging_from`` — a free function that accepts a single ``PyAutoFit`` ``Fit``
+  entry and returns a list of ``FitImaging`` objects (one per summed ``Analysis``).
+- ``FitImagingAgg`` — a ``PyAutoFit`` ``AggBase`` subclass wrapping an ``Aggregator``
+  that exposes a generator of ``FitImaging`` objects, enabling memory-efficient iteration
+  over large result sets.
+"""
 from typing import Optional, List
 
 import autofit as af
diff --git a/autolens/aggregator/fit_interferometer.py b/autolens/aggregator/fit_interferometer.py
index 25299d8b2..51295969d 100644
--- a/autolens/aggregator/fit_interferometer.py
+++ b/autolens/aggregator/fit_interferometer.py
@@ -1,3 +1,20 @@
+"""
+Aggregator interface for loading ``FitInterferometer`` objects from lens model-fit results.
+
+This module assembles ``FitInterferometer`` instances offline by combining the
+interferometer dataset, ``Tracer``, dataset model, and adapt images stored in a
+``PyAutoFit`` output directory or SQLite database — reproducing exactly the fit that was
+evaluated during the original non-linear search.
+
+Two public objects are provided:
+
+- ``_fit_interferometer_from`` — a free function that accepts a single ``PyAutoFit``
+  ``Fit`` entry and returns a list of ``FitInterferometer`` objects (one per summed
+  ``Analysis``).
+- ``FitInterferometerAgg`` — a ``PyAutoFit`` ``AggBase`` subclass wrapping an
+  ``Aggregator`` that exposes a generator of ``FitInterferometer`` objects, enabling
+  memory-efficient iteration over large result sets.
+"""
 from typing import Optional, List
 
 import autofit as af
diff --git a/autolens/aggregator/subhalo.py b/autolens/aggregator/subhalo.py
index 7e2b54500..b2e422a8a 100644
--- a/autolens/aggregator/subhalo.py
+++ b/autolens/aggregator/subhalo.py
@@ -1,3 +1,15 @@
+"""
+Aggregator interface for dark-matter subhalo grid-search results.
+
+``SubhaloAgg`` wraps a ``PyAutoFit`` ``GridSearchAggregator`` to provide a convenient
+interface for loading and comparing the results of a subhalo detection grid search.
+
+A subhalo grid search runs an independent non-linear search in each cell of an image-plane
+grid, with the subhalo's (y, x) centre confined to that cell's region.  ``SubhaloAgg``
+collates these per-cell results and exposes generators that yield ``FitImaging`` objects
+for the best-fit model in each cell — both the "with subhalo" fit and (optionally) the
+"no subhalo" baseline — enabling the per-cell log-evidence difference map to be computed.
+"""
 from typing import Optional
 
 import autofit as af
diff --git a/autolens/aggregator/tracer.py b/autolens/aggregator/tracer.py
index 96eaba956..470df9709 100644
--- a/autolens/aggregator/tracer.py
+++ b/autolens/aggregator/tracer.py
@@ -1,3 +1,19 @@
+"""
+Aggregator interface for loading ``Tracer`` objects from model-fit results.
+
+After a **PyAutoLens** model-fit the best-fit galaxy model parameters are stored in the
+output directory or SQLite database as part of the model JSON file.  This module
+reconstructs ``Tracer`` instances from those stored parameters so that the full
+ray-tracing model can be re-evaluated and inspected without re-running the fit.
+
+Two public objects are provided:
+
+- ``_tracer_from`` — a free function that accepts a single ``PyAutoFit`` ``Fit`` entry
+  and returns the list of ``Tracer`` objects (one per summed ``Analysis``) for the
+  requested model instance.
+- ``TracerAgg`` — a ``PyAutoFit`` ``AggBase`` subclass wrapping an ``Aggregator`` that
+  exposes a generator of tracer lists, one entry per stored model-fit.
+"""
 import logging
 from typing import List, Optional