docs(aggregator): add module-level docstrings to aggregator package

autogalaxy/aggregator/agg_util.py

@@ -1,3 +1,24 @@
+"""
+Shared utility functions for the **PyAutoGalaxy** aggregator interface.
+
+This module provides low-level helpers used by all dataset-specific aggregator classes
+(`ImagingAgg`, `FitImagingAgg`, `GalaxiesAgg`, etc.).  They centralise the logic that
+is repeated across every aggregator module so that the higher-level classes stay concise.
+
+Key functions
+-------------
+- `instance_list_from` — Converts a ``PyAutoFit`` ``Fit`` into the correct list of model
+  instances, handling both single-analysis fits and multi-analysis ``FactorGraphModel``
+  fits.
+- `mask_header_from` — Loads a ``Mask2D`` and its FITS header from a stored dataset file.
+  Used whenever a dataset must be reconstructed from the database.
+- `adapt_images_from` — Reconstructs ``AdaptImages`` objects from files stored during the
+  model-fit.  Needed so that adaptive features (e.g. an ``Hilbert`` image-mesh) reproduce
+  the same behaviour on a local machine as on the HPC cluster where the fit was run.
+- `mesh_grids_of_planes_list_from` — Loads the pre-computed image-plane mesh grids that
+  were saved during the fit, removing any stochastic variation when inspecting results
+  offline.
+"""
 from __future__ import annotations
 import numpy as np
 from typing import List, Optional

autogalaxy/aggregator/dataset_model.py

@@ -1,3 +1,15 @@
+"""
+Aggregator interface for loading ``DatasetModel`` objects from model-fit results.
+
+A ``DatasetModel`` holds dataset-level nuisance parameters (e.g. an overall background
+offset or a noise scaling factor) that form part of the fitted model.  This module
+provides the helper function ``_dataset_model_from`` which reconstructs these objects from
+a stored ``PyAutoFit`` ``Fit`` entry so that the full fit can be replicated during
+offline analysis.
+
+When no ``dataset_model`` is present in the model (the common case), ``None`` is returned
+for that entry so that downstream ``Fit*`` constructors receive a well-typed argument.
+"""
 from __future__ import annotations
 import logging
 from typing import List

autogalaxy/aggregator/ellipse/ellipses.py

@@ -1,3 +1,18 @@
+"""
+Aggregator interface for loading ``Ellipse`` objects from ellipse model-fit results.
+
+After an ellipse model-fit the best-fit ellipse parameters are stored in the output
+directory or SQLite database as part of the model JSON file.  This module reconstructs
+the list of ``Ellipse`` instances so that downstream analysis (e.g. re-plotting
+isophotes) can be performed without re-running the fit.
+
+Two public objects are provided:
+
+- ``_ellipses_from`` — a free function that accepts a single ``PyAutoFit`` ``Fit`` entry
+  and returns the list of ``Ellipse`` objects for the requested model instance.
+- ``EllipsesAgg`` — a ``PyAutoFit`` ``AggBase`` subclass wrapping an ``Aggregator`` that
+  exposes a generator of ellipse lists, one per stored model-fit.
+"""
 from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Optional, List

autogalaxy/aggregator/ellipse/fit_ellipse.py

@@ -1,3 +1,19 @@
+"""
+Aggregator interface for loading ``FitEllipse`` objects from ellipse model-fit results.
+
+This module reconstructs ``FitEllipse`` instances from the imaging dataset, fitted
+ellipses, and (optionally) multipole perturbations stored in an output directory or
+SQLite database, allowing full offline inspection of isophote fits without re-running the
+non-linear search.
+
+Two public objects are provided:
+
+- ``_fit_ellipse_from`` — a free function that accepts a single ``PyAutoFit`` ``Fit``
+  entry and returns a list of ``FitEllipse`` objects (one per ellipse in the fit).
+- ``FitEllipseAgg`` — a ``PyAutoFit`` ``AggBase`` subclass wrapping an ``Aggregator``
+  that exposes a generator of ``FitEllipse`` object lists, one entry per stored
+  model-fit.
+"""
 from __future__ import annotations
 from typing import TYPE_CHECKING, Optional, List
 

autogalaxy/aggregator/ellipse/multipoles.py

@@ -1,3 +1,19 @@
+"""
+Aggregator interface for loading ``EllipseMultipole`` objects from ellipse model-fit results.
+
+``EllipseMultipole`` objects represent higher-order harmonic perturbations (e.g. m=3, m=4
+boxy/disky distortions) on top of the base ellipse isophotes.  This module reconstructs
+the nested list of multipole objects from a stored ``PyAutoFit`` ``Fit`` entry so that
+multipole-enhanced isophote fits can be inspected offline.
+
+Two public objects are provided:
+
+- ``_multipoles_from`` — a free function that accepts a single ``PyAutoFit`` ``Fit``
+  entry and returns the nested list of ``EllipseMultipole`` objects for the requested
+  model instance.
+- ``MultipolesAgg`` — a ``PyAutoFit`` ``AggBase`` subclass wrapping an ``Aggregator``
+  that exposes a generator of multipole lists, one per stored model-fit.
+"""
 from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Optional, List

autogalaxy/aggregator/galaxies.py

@@ -1,3 +1,19 @@
+"""
+Aggregator interface for loading **PyAutoGalaxy** ``Galaxy`` objects from model-fit results.
+
+After a non-linear search completes, its outputs (best-fit parameters, adapt images, etc.)
+are written to an output directory or stored in an SQLite database.  The helpers in this
+module reconstruct ``Galaxy`` instances from those stored files so that the full galaxy
+model can be re-created and inspected without re-running the fit.
+
+Two public objects are provided:
+
+- ``_galaxies_from`` — a free function that accepts a single ``PyAutoFit`` ``Fit`` entry
+  and returns the list of ``Galaxy`` objects (or lists of lists when multiple ``Analysis``
+  objects were summed).
+- ``GalaxiesAgg`` — a ``PyAutoFit`` ``AggBase`` subclass that wraps an ``Aggregator``
+  and returns a generator of galaxy lists, one per stored model-fit.
+"""
 from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Optional, List

autogalaxy/aggregator/imaging/fit_imaging.py

@@ -1,3 +1,19 @@
+"""
+Aggregator interface for loading ``FitImaging`` objects from model-fit results.
+
+This module combines all the pieces that are needed to re-create a ``FitImaging``
+object offline — the imaging dataset, galaxy model, dataset model, and adapt images —
+and assembles them into a ``FitImaging`` instance identical to the one produced 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 that wraps an ``Aggregator``
+  and exposes a generator of ``FitImaging`` objects, enabling memory-efficient iteration
+  over large result sets.
+"""
 from __future__ import annotations
 from typing import TYPE_CHECKING, Optional, List
 

autogalaxy/aggregator/imaging/imaging.py

@@ -1,3 +1,18 @@
+"""
+Aggregator interface for loading ``Imaging`` datasets from model-fit results.
+
+After a model-fit the imaging dataset (data array, noise-map, PSF, mask, and
+over-sampling settings) is written to a FITS file in the output directory or SQLite
+database.  This module reconstructs a fully-masked ``aa.Imaging`` object from those
+stored files.
+
+Two public objects are provided:
+
+- ``_imaging_from`` — a free function that accepts a single ``PyAutoFit`` ``Fit`` entry
+  and returns a list of ``aa.Imaging`` datasets (one per summed ``Analysis``).
+- ``ImagingAgg`` — a class wrapping an ``Aggregator`` that returns a lazy generator of
+  ``Imaging`` datasets, avoiding loading all results into memory at once.
+"""
 from functools import partial
 from typing import List
 

autogalaxy/aggregator/interferometer/fit_interferometer.py

@@ -1,3 +1,20 @@
+"""
+Aggregator interface for loading ``FitInterferometer`` objects from model-fit results.
+
+This module combines all the pieces that are needed to re-create a ``FitInterferometer``
+object offline — the interferometer dataset, galaxy model, dataset model, and adapt
+images — and assembles them into a ``FitInterferometer`` instance identical to the one
+produced 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 __future__ import annotations
 from typing import TYPE_CHECKING, Optional, List
 

autogalaxy/aggregator/interferometer/interferometer.py

@@ -1,3 +1,20 @@
+"""
+Aggregator interface for loading ``Interferometer`` datasets from model-fit results.
+
+After an interferometer model-fit the dataset (complex visibilities, noise-map,
+uv-wavelengths, real-space mask, and transformer class) is written to a FITS file in
+the output directory or SQLite database.  This module reconstructs a fully-configured
+``aa.Interferometer`` object from those stored files.
+
+Two public objects are provided:
+
+- ``_interferometer_from`` — a free function that accepts a single ``PyAutoFit`` ``Fit``
+  entry and returns a list of ``aa.Interferometer`` datasets (one per summed
+  ``Analysis``).
+- ``InterferometerAgg`` — a class wrapping an ``Aggregator`` that returns a lazy
+  generator of ``Interferometer`` datasets, avoiding loading all results into memory at
+  once.
+"""
 from functools import partial
 from typing import List