docs: surface datacube modeling and document 14 undocumented example folders

README.md

@@ -67,7 +67,7 @@ The examples in the `notebooks` and `scripts` folders are structured as follows:
 
 - `guides`: Guides which introduce the core features of **PyAutoLens**, including the core lensing API.
 - `imaging`: Examples for galaxy scale strong lenses observed with CCD imaging (e.g. Hubble, Euclid).
-- `interferometer`: Examples for galaxy scale strong lenses observed with an interferometer (e.g. ALMA, JVLA).
+- `interferometer`: Examples for galaxy scale strong lenses observed with an interferometer (e.g. ALMA, JVLA), for both continuum data and spectral-line data cubes.
 - `multi_dataset`: Examples for lenses observed in multiple wavebands, modeled simultaneously.
 - `point_source`: Examples for strong lens point source datasets.
 - `multi_galaxy`: Examples for multi-galaxy strong lenses (two or more co-dominant lens galaxies, no host halo).

llms.txt

@@ -30,6 +30,7 @@ If your AI can't browse GitHub, paste this entire file into the chat as context.
 - **Model a group-scale lens** → [scripts/group/modeling.py](scripts/group/modeling.py): Detailed group modeling API for systems with multiple lens galaxies.
 - **Model a point-source / quasar lens** → [scripts/point_source/modeling.py](scripts/point_source/modeling.py): Detailed point-source modeling API, fitting multiple-image positions (and fluxes).
 - **Model interferometer / ALMA (uv-plane) data** → [scripts/interferometer/modeling.py](scripts/interferometer/modeling.py): Detailed uv-plane modeling API fitting visibilities directly.
+- **Model a spectral-line data cube (e.g. ALMA CO cube)** → [scripts/interferometer/features/datacube/start_here.py](scripts/interferometer/features/datacube/start_here.py): Fit every channel simultaneously with a shared lens model and a per-channel source; [data_preparation.py](scripts/interferometer/features/datacube/data_preparation.py) covers loading a CASA-style 3D/4D FITS cube.
 - **Multi-wavelength / multi-dataset modeling** → [scripts/multi_dataset/modeling.py](scripts/multi_dataset/modeling.py): Detailed API for jointly fitting multiple datasets of one lens.
 - **Load & inspect results from `output/`** → [scripts/guides/results/start_here.py](scripts/guides/results/start_here.py): Load a completed fit back into Python (`Tracer`, `Model`, samples, model images) from a fit's `output/...` folder.
 - **Compute magnification / source flux** → [scripts/imaging/source_science.py](scripts/imaging/source_science.py): Source-science calculations — total flux, magnification, and intrinsic size of the lensed source from a fitted tracer.

notebooks/README.md

@@ -10,7 +10,7 @@ you should go into next if you are unsure.
 
 - `guides`: Step-by-step guides illustrating many important things, including the core API, analysing modeling results and much more.
 - `imaging`: Examples for galaxy scale strong lenses observed with CCD imaging (e.g. Hubble, Euclid).
-- `interferometer`: Examples for galaxy scale strong lenses observed with an interferometer (e.g. ALMA, JVLA).
+- `interferometer`: Examples for galaxy scale strong lenses observed with an interferometer (e.g. ALMA, JVLA), for both continuum data and spectral-line data cubes.
 - `point_source`: Examples for strong lens point source datasets.
 - `multi_galaxy`: Examples for multi-galaxy strong lenses (2+ co-dominant lens galaxies, no host halo).
 - `group`: Examples for group scale strong lenses.

notebooks/group/features/README.md

@@ -17,9 +17,16 @@ Core features:
 - `multi_gaussian_expansion`: Galaxy light modeled as ~10-30 Gaussian basis functions (MGE).
 - `no_lens_light`: All group galaxies have no visible light — mass-only models.
 - `pixelization`: Source galaxy reconstructed using an adaptive pixel mesh.
+- `scaling_relation`: Foreground galaxy masses tied to their luminosities through a scaling relation,
+  via the three-tier modeling API used by the production group pipelines, so model dimensionality does
+  not grow with the population.
 
 Advanced features:
 
+- `advanced/double_source_plane_lens`: Two source galaxies at two different redshifts behind multiple
+  foreground main lens galaxies.
+- `advanced/mass_stellar_dark`: Each main lens galaxy's mass decomposed into a stellar component (tied
+  to its light) and a separate dark matter halo.
 - `advanced/operated_light_profile`: PSF-convolved (operated) light profiles for group galaxies.
 - `advanced/shapelets`: Shapelet basis functions for group galaxy light.
 - `advanced/sky_background`: Modeling a uniform sky background alongside the group.

notebooks/group/features/advanced/README.md

@@ -2,6 +2,8 @@
 
 These scripts cover advanced lens modeling techniques for group-scale strong lenses.
 
+- `double_source_plane_lens`: Two source galaxies at two different redshifts, observed behind multiple foreground main lens galaxies.
+- `mass_stellar_dark`: Each main lens galaxy's mass decomposed into a stellar component (tied to its light via a mass-to-light ratio) and a separately-parameterized dark matter halo.
 - `operated_light_profile`: PSF-convolved (operated) light profiles for group galaxies.
 - `shapelets`: Shapelet basis functions for modeling complex galaxy light morphology.
 - `sky_background`: Modeling a uniform sky background in group-scale data.

notebooks/guides/results/README.md

@@ -7,4 +7,6 @@ The `results` folder contains example scripts for using the results of a **PyAut
 # Folders
 
 - `examples`: Result inspection and analysis for different aspects of the fit and lens model types.
+- `aggregator`: Loading model results (samples, posteriors, errors) via the aggregator, which is more efficient for large libraries of results.
+- `database`: Building an SQLite3 database to manage large suites of modeling results, which scales better than scraping the `output` folder.
 - `workflow`: Develop a fast workflow to inspect and manage libraries of lens modeling results, using .csv, .png and .fits files.

notebooks/imaging/data_preparation/README.md

@@ -8,3 +8,5 @@ dataset (e.g. Hubble Space Telescope) before **PyAutoLens** analysis:
 # Folders
 
 - `examples`: A folder containing example scripts of how to prepare imaging data for **PyAutoLens** analysis.
+- `gui`: Graphical user interface tools for marking up a dataset by hand — drawing a mask, and clicking the lens light centre and extra-galaxy centres.
+- `manual`: Preparing the same products manually in code, without the GUI (e.g. an irregular mask).

notebooks/imaging/features/advanced/README.md

@@ -11,6 +11,7 @@ for specific scientific topics.The following example scripts illustrating lens m
 - `sky_background`: Including the background sky in the model.
 - `subhalo`: Fitting lens models for dark matter subhalo detection and sensitivity mapping.
 - `potential_correction`: Gravitational imaging — pixelized corrections to the lensing potential reconstructed jointly with the source.
+- `los_halos`: Simulating a lens with line-of-sight (LOS) dark matter halos on multiple redshift planes, sampled from a cosmological halo mass function and ray-traced with multi-plane lensing.
 
 # Notes
 

notebooks/imaging/features/advanced/subhalo/README.md

@@ -6,5 +6,5 @@ are extended in order to perform dark matter subhalo analysis.
 
 # Files
 
-- `detection`: Extend the SLaM pipelines to perform dark matter subhalo detection.
+- `detect`: Extend the SLaM pipelines to perform dark matter subhalo detection.
 - `sensitivity`: Extend the SLaM pipelines to perform dark matter subhalo sensitivity mapping.

notebooks/interferometer/README.md

@@ -1,6 +1,10 @@
 The `interferometer` folder contains example scripts showing how to analyse galaxy-scale strong lenses with
 interferometer data (E.g. ALMA, Radio Interferometers)
 
+Both single-channel (continuum) data and spectral-line data cubes are supported. The examples below are for
+continuum data; for cubes, where every channel is fitted simultaneously with a shared lens model, see the
+`interferometer/features/datacube` package.
+
 # Start Here
 
 New users should read the `start_here` example, which gives an overview of all examples in the folder.
@@ -19,7 +23,8 @@ New users should read the `start_here` example, which gives an overview of all e
 
 # Folders
 
-- `features`: Examples illustrating different core features for interferometer analysis and lens modeling.
+- `features`: Examples illustrating different core features for interferometer analysis and lens modeling, including
+  spectral-line data cubes (`features/datacube`).
 
 # Results
 

notebooks/interferometer/data_preparation/README.md

@@ -6,6 +6,10 @@ dataset (e.g. Hubble Space Telescope) before **PyAutoLens** analysis:
 - `run_times`: An overview of interferometer run-times and how to make your analysis run as fast as possible.
 - `casa_to_autogalaxy`: Convert a dataset to **PyAutoLens** formats via CASA.
 
+# Folders
+
+- `examples`: Example scripts covering each step of preparing an interferometer dataset for **PyAutoLens** analysis.
+
 # Notes
 
 The example scripts for preparing interferometer data are still in development. If they are unclear, you should

notebooks/interferometer/features/README.md

@@ -10,6 +10,10 @@ and scientific topic of study.
 The following example scripts illustrating lens modeling where:
 
 - `pixelization`: The source is reconstructed using an adaptive rectangular or Delaunay mesh
+- `datacube`: Spectral-line data cubes (e.g. ALMA CO cubes), fitting every channel simultaneously with a shared lens model and a per-channel source.
+- `linear_light_profiles`: Light profiles whose `intensity` is solved for analytically via a linear inversion instead of being a free parameter of the non-linear search.
+- `multi_gaussian_expansion`: The source's light decomposed into many linear Gaussian components (MGE), whose intensities are solved for analytically.
+- `scaling_relation`: A population of foreground galaxies included by tying their masses to the main lens's through a luminosity scaling relation, rather than freeing each one.
 - `extra_galaxies`: Modeling which account for the light and mass of extra nearby galaxies.
 - `advanced`: Advanced features for expert users, for example shapelets, potential correction (gravitational imaging) and dark matter subhalo detection.
 

notebooks/point_source/features/README.md

@@ -18,6 +18,7 @@ The following example scripts are specific to point source datasets:
 - `deblending`: Deblend the point-source images (e.g. of a lensed quasar) from the lens galaxy light to determine the positions of the point sources and measure the lens galaxy's properties.
 - `extra_galaxies`: Include the mass of galaxies projected near the lens in the model, accounting for how they perturb the multiple image positions. Mass-only, because point-source data contains no extra galaxy light to mask or fit.
 - `multiple_sources`: Simulate and fit a strong lens with multiple lensed point sources at different redshifts (e.g. an Einstein Cross configuration).
+- `scaling_relation`: Include a population of foreground galaxies by tying their masses to the main lens's through a luminosity scaling relation, rather than freeing each one.
 
 # Notes
 

scripts/README.md

@@ -10,7 +10,7 @@ you should go into next if you are unsure.
 
 - `guides`: Step-by-step guides illustrating many important things, including the core API, analysing modeling results and much more.
 - `imaging`: Examples for galaxy scale strong lenses observed with CCD imaging (e.g. Hubble, Euclid).
-- `interferometer`: Examples for galaxy scale strong lenses observed with an interferometer (e.g. ALMA, JVLA).
+- `interferometer`: Examples for galaxy scale strong lenses observed with an interferometer (e.g. ALMA, JVLA), for both continuum data and spectral-line data cubes.
 - `point_source`: Examples for strong lens point source datasets.
 - `multi_galaxy`: Examples for multi-galaxy strong lenses (2+ co-dominant lens galaxies, no host halo).
 - `group`: Examples for group scale strong lenses.

scripts/group/features/README.md

@@ -17,9 +17,16 @@ Core features:
 - `multi_gaussian_expansion`: Galaxy light modeled as ~10-30 Gaussian basis functions (MGE).
 - `no_lens_light`: All group galaxies have no visible light — mass-only models.
 - `pixelization`: Source galaxy reconstructed using an adaptive pixel mesh.
+- `scaling_relation`: Foreground galaxy masses tied to their luminosities through a scaling relation,
+  via the three-tier modeling API used by the production group pipelines, so model dimensionality does
+  not grow with the population.
 
 Advanced features:
 
+- `advanced/double_source_plane_lens`: Two source galaxies at two different redshifts behind multiple
+  foreground main lens galaxies.
+- `advanced/mass_stellar_dark`: Each main lens galaxy's mass decomposed into a stellar component (tied
+  to its light) and a separate dark matter halo.
 - `advanced/operated_light_profile`: PSF-convolved (operated) light profiles for group galaxies.
 - `advanced/shapelets`: Shapelet basis functions for group galaxy light.
 - `advanced/sky_background`: Modeling a uniform sky background alongside the group.

scripts/group/features/advanced/README.md

@@ -2,6 +2,8 @@
 
 These scripts cover advanced lens modeling techniques for group-scale strong lenses.
 
+- `double_source_plane_lens`: Two source galaxies at two different redshifts, observed behind multiple foreground main lens galaxies.
+- `mass_stellar_dark`: Each main lens galaxy's mass decomposed into a stellar component (tied to its light via a mass-to-light ratio) and a separately-parameterized dark matter halo.
 - `operated_light_profile`: PSF-convolved (operated) light profiles for group galaxies.
 - `shapelets`: Shapelet basis functions for modeling complex galaxy light morphology.
 - `sky_background`: Modeling a uniform sky background in group-scale data.

scripts/guides/results/README.md

@@ -7,4 +7,6 @@ The `results` folder contains example scripts for using the results of a **PyAut
 # Folders
 
 - `examples`: Result inspection and analysis for different aspects of the fit and lens model types.
+- `aggregator`: Loading model results (samples, posteriors, errors) via the aggregator, which is more efficient for large libraries of results.
+- `database`: Building an SQLite3 database to manage large suites of modeling results, which scales better than scraping the `output` folder.
 - `workflow`: Develop a fast workflow to inspect and manage libraries of lens modeling results, using .csv, .png and .fits files.

scripts/imaging/data_preparation/README.md

@@ -8,3 +8,5 @@ dataset (e.g. Hubble Space Telescope) before **PyAutoLens** analysis:
 # Folders
 
 - `examples`: A folder containing example scripts of how to prepare imaging data for **PyAutoLens** analysis.
+- `gui`: Graphical user interface tools for marking up a dataset by hand — drawing a mask, and clicking the lens light centre and extra-galaxy centres.
+- `manual`: Preparing the same products manually in code, without the GUI (e.g. an irregular mask).

scripts/imaging/features/advanced/README.md

@@ -11,6 +11,7 @@ for specific scientific topics.The following example scripts illustrating lens m
 - `sky_background`: Including the background sky in the model.
 - `subhalo`: Fitting lens models for dark matter subhalo detection and sensitivity mapping.
 - `potential_correction`: Gravitational imaging — pixelized corrections to the lensing potential reconstructed jointly with the source.
+- `los_halos`: Simulating a lens with line-of-sight (LOS) dark matter halos on multiple redshift planes, sampled from a cosmological halo mass function and ray-traced with multi-plane lensing.
 
 # Notes
 

scripts/imaging/features/advanced/subhalo/README.md

@@ -6,5 +6,5 @@ are extended in order to perform dark matter subhalo analysis.
 
 # Files
 
-- `detection`: Extend the SLaM pipelines to perform dark matter subhalo detection.
+- `detect`: Extend the SLaM pipelines to perform dark matter subhalo detection.
 - `sensitivity`: Extend the SLaM pipelines to perform dark matter subhalo sensitivity mapping.

scripts/interferometer/README.md

@@ -1,6 +1,10 @@
 The `interferometer` folder contains example scripts showing how to analyse galaxy-scale strong lenses with
 interferometer data (E.g. ALMA, Radio Interferometers)
 
+Both single-channel (continuum) data and spectral-line data cubes are supported. The examples below are for
+continuum data; for cubes, where every channel is fitted simultaneously with a shared lens model, see the
+`interferometer/features/datacube` package.
+
 # Start Here
 
 New users should read the `start_here` example, which gives an overview of all examples in the folder.
@@ -19,7 +23,8 @@ New users should read the `start_here` example, which gives an overview of all e
 
 # Folders
 
-- `features`: Examples illustrating different core features for interferometer analysis and lens modeling.
+- `features`: Examples illustrating different core features for interferometer analysis and lens modeling, including
+  spectral-line data cubes (`features/datacube`).
 
 # Results
 

scripts/interferometer/data_preparation/README.md

@@ -6,6 +6,10 @@ dataset (e.g. Hubble Space Telescope) before **PyAutoLens** analysis:
 - `run_times`: An overview of interferometer run-times and how to make your analysis run as fast as possible.
 - `casa_to_autogalaxy`: Convert a dataset to **PyAutoLens** formats via CASA.
 
+# Folders
+
+- `examples`: Example scripts covering each step of preparing an interferometer dataset for **PyAutoLens** analysis.
+
 # Notes
 
 The example scripts for preparing interferometer data are still in development. If they are unclear, you should

scripts/interferometer/features/README.md

@@ -10,6 +10,10 @@ and scientific topic of study.
 The following example scripts illustrating lens modeling where:
 
 - `pixelization`: The source is reconstructed using an adaptive rectangular or Delaunay mesh
+- `datacube`: Spectral-line data cubes (e.g. ALMA CO cubes), fitting every channel simultaneously with a shared lens model and a per-channel source.
+- `linear_light_profiles`: Light profiles whose `intensity` is solved for analytically via a linear inversion instead of being a free parameter of the non-linear search.
+- `multi_gaussian_expansion`: The source's light decomposed into many linear Gaussian components (MGE), whose intensities are solved for analytically.
+- `scaling_relation`: A population of foreground galaxies included by tying their masses to the main lens's through a luminosity scaling relation, rather than freeing each one.
 - `extra_galaxies`: Modeling which account for the light and mass of extra nearby galaxies.
 - `advanced`: Advanced features for expert users, for example shapelets, potential correction (gravitational imaging) and dark matter subhalo detection.
 

scripts/point_source/features/README.md

@@ -18,6 +18,7 @@ The following example scripts are specific to point source datasets:
 - `deblending`: Deblend the point-source images (e.g. of a lensed quasar) from the lens galaxy light to determine the positions of the point sources and measure the lens galaxy's properties.
 - `extra_galaxies`: Include the mass of galaxies projected near the lens in the model, accounting for how they perturb the multiple image positions. Mass-only, because point-source data contains no extra galaxy light to mask or fit.
 - `multiple_sources`: Simulate and fit a strong lens with multiple lensed point sources at different redshifts (e.g. an Einstein Cross configuration).
+- `scaling_relation`: Include a population of foreground galaxies by tying their masses to the main lens's through a luminosity scaling relation, rather than freeing each one.
 
 # Notes