How mwalmsley/zoobot-3d works
Project Type and Purpose
• This is an end-to-end machine‐learning research pipeline for galaxy‐image segmentation and (optionally) classification.
• It ingests volunteer‐annotated FITS data (GZ3D), DESI‐LS cutouts, and produces trained UNet models and evaluation artifacts (figures).
Top-Level Components
A. External Data Sources
– GZ3D FITS service (raw volunteer marks, segmentation maps, MANGA metadata)
– DESI‐LS cutout API/service
– SAMI data‐central service
– GZ DESI and GZ2 volunteer‐vote tables (parquet)
B. Data Preparation Layer (prepare_data/, deprecated/, notebooks)
– FITS scraping & download (download_gz3d_fits.py, download_centered_desi_cutouts.py)
– Vector‐to‐mask extraction (extract_gz3d_segmaps.py → zoobot_3d.segmap_utils.construct_segmap_image)
– Catalog construction & crossmatch (construct_gz3d_catalog.py, crossmatch_catalogs.ipynb)
– Final catalog tweaks (final_catalog_tweaks.ipynb)
– Auxiliary scripts (sparcfire, custom legacy)
C. Configuration (conf/config.yaml, setup.py)
D. Data Storage
– Local file hierarchy under data/ (FITS, JSON segmap, JPGs, parquet catalogs)
E. Data‐Loading & Augmentation (zoobot_3d/pytorch_dataset.py, pytorch_datamodule.py)
– LightningDataModule managing train/val/test splits, optional mask/class labels, albumentations transforms
F. Model Definition (zoobot_3d/gz3d_pytorch_model.py, custom_layers.py)
– UNet encoder/decoder, optional classification head, Dirichlet loss support
G. Training & Hyperparameter Sweep
– train.py: orchestrates training on spiral/bar segmaps only
– Slurm job scripts (slurm/train.sh, slurm/sweep.yaml, run_sweep_agent.sh, run_experiments.sh)
H. Prediction & Evaluation
– predict.py: batch inference over new galaxies
– Results notebooks (results_for_neurips/*.ipynb) generate comparison grids and expert‐vote analyses
I. Outputs
– Model checkpoints, metrics logs, paper‐ready figures under outputs/
J. CI / Packaging
– setup.py for pip install, requirements.txt (implicit)
Interactions and Data Flow
• External Data Services → Data Preparation Layer → Data Storage
• Data Storage → Data‐Loading Layer → Model
• Model + DataLoader → Training Engine (train.py via Slurm) → Outputs (checkpoints, logs)
• Checkpoints → Prediction Script (predict.py) → Evaluation Notebooks → Final Figures
• Config (conf/config.yaml) guides dataset paths, model/hparam defaults
Architectural Patterns & Principles
• Separation of concerns: Data ingestion, preprocessing, modeling, and evaluation are modular.
• Pipeline pattern: clear linear flow from raw data to figures, with branching for sweeps and predictions.
• HPC‐friendly design: Slurm scripts wrap Python entry points, enabling reproducible sweeps.
• Config‐driven: YAML config + environment variables allow swapping datasets or hyperparams.
• PyTorch Lightning (via DataModule) for standardized training loops.