From ab627772447f0a9e43d24bfbfbe6b890bb08452d Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Tue, 10 Mar 2026 16:36:30 +0000 Subject: [PATCH] docs(aggregator): add module-level docstrings to aggregator package Add module-level docstrings to all ten aggregator modules explaining the purpose of each module, the two public objects it exposes (a free helper function and an Agg class), and how they relate to the broader PyAutoFit database / aggregator workflow. Co-Authored-By: Claude Sonnet 4.6 --- autogalaxy/aggregator/agg_util.py | 21 +++++++++++++++++++ autogalaxy/aggregator/dataset_model.py | 12 +++++++++++ autogalaxy/aggregator/ellipse/ellipses.py | 15 +++++++++++++ autogalaxy/aggregator/ellipse/fit_ellipse.py | 16 ++++++++++++++ autogalaxy/aggregator/ellipse/multipoles.py | 16 ++++++++++++++ autogalaxy/aggregator/galaxies.py | 16 ++++++++++++++ autogalaxy/aggregator/imaging/fit_imaging.py | 16 ++++++++++++++ autogalaxy/aggregator/imaging/imaging.py | 15 +++++++++++++ .../interferometer/fit_interferometer.py | 17 +++++++++++++++ .../interferometer/interferometer.py | 17 +++++++++++++++ 10 files changed, 161 insertions(+) diff --git a/autogalaxy/aggregator/agg_util.py b/autogalaxy/aggregator/agg_util.py index cf4af7f5d..5481b9147 100644 --- a/autogalaxy/aggregator/agg_util.py +++ b/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 diff --git a/autogalaxy/aggregator/dataset_model.py b/autogalaxy/aggregator/dataset_model.py index 499082a0a..3e1c26bc3 100644 --- a/autogalaxy/aggregator/dataset_model.py +++ b/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 diff --git a/autogalaxy/aggregator/ellipse/ellipses.py b/autogalaxy/aggregator/ellipse/ellipses.py index cc4f3ee15..7ff6c96c6 100644 --- a/autogalaxy/aggregator/ellipse/ellipses.py +++ b/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 diff --git a/autogalaxy/aggregator/ellipse/fit_ellipse.py b/autogalaxy/aggregator/ellipse/fit_ellipse.py index 7f1ca263c..ad2ca9968 100644 --- a/autogalaxy/aggregator/ellipse/fit_ellipse.py +++ b/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 diff --git a/autogalaxy/aggregator/ellipse/multipoles.py b/autogalaxy/aggregator/ellipse/multipoles.py index 518259b75..59d1055da 100644 --- a/autogalaxy/aggregator/ellipse/multipoles.py +++ b/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 diff --git a/autogalaxy/aggregator/galaxies.py b/autogalaxy/aggregator/galaxies.py index 492464723..7193d659f 100644 --- a/autogalaxy/aggregator/galaxies.py +++ b/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 diff --git a/autogalaxy/aggregator/imaging/fit_imaging.py b/autogalaxy/aggregator/imaging/fit_imaging.py index aac0dc26b..6738c1096 100644 --- a/autogalaxy/aggregator/imaging/fit_imaging.py +++ b/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 diff --git a/autogalaxy/aggregator/imaging/imaging.py b/autogalaxy/aggregator/imaging/imaging.py index 648058ea5..eb81027b8 100644 --- a/autogalaxy/aggregator/imaging/imaging.py +++ b/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 diff --git a/autogalaxy/aggregator/interferometer/fit_interferometer.py b/autogalaxy/aggregator/interferometer/fit_interferometer.py index 69885be52..b7cec7dd1 100644 --- a/autogalaxy/aggregator/interferometer/fit_interferometer.py +++ b/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 diff --git a/autogalaxy/aggregator/interferometer/interferometer.py b/autogalaxy/aggregator/interferometer/interferometer.py index 117264be4..4f9f3035e 100644 --- a/autogalaxy/aggregator/interferometer/interferometer.py +++ b/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