How mariam186/sigma-vae works
SIGMA-VAE is a multi-view normative-modeling package for structural brain MRI. Its main workflow aligns and scales subcortical, cortical-thickness, and surface-area data, trains a conditional variational autoencoder with selectable SIGReg/KL and L0 variants, then extracts latent representations and uncertainty-aware W-scores for evaluation. Separate interpretation scripts perturb active latent dimensions and render regional effects. The README documents these capabilities; source excerpts establish the core training and modeling interactions, while some interpretation wiring is documented rather than directly shown.
Main entry points: train.py Training workflow · trainer.py Trainer and exports · data.py Data processor · pretrained_models Pretrained variants
Components 16
Data preparation
- Data processor
sigma_vae/data.py - Multi-view batches
sigma_vae/data.py
Model and training
- Training workflow
sigma_vae/train.py - Conditional MMVAE
sigma_vae/models.py - Training losses
sigma_vae/losses.py - Trainer and exports
sigma_vae/trainer.py - Pretrained variants
pretrained_models
Evaluation
- Model evaluator
sigma_vae/evaluation.py - Disentanglement checks
sigma_vae/diagnostics.py
Interpretation
- Latent perturbation
interpretation/perturbation_analysis.py - Perturbation maps
- Subcortical renderer
interpretation/render_subcortical.py - Cortical renderer
interpretation/render_cortical_surface.py
Other components
- Researcher
- MRI view CSVs
- Brain templates
Connections 20
- Researcher → MRI view CSVs: provides views
README.md - MRI view CSVs → Data processor: loads and aligns
README.md - Data processor → Multi-view batches: creates batches
sigma_vae/data.py - Researcher → Training workflow: configures and runs
README.md - Training workflow → Data processor: loads training data
sigma_vae/train.py - Training workflow → Conditional MMVAE: constructs model
sigma_vae/train.py - Training workflow → Training losses: configures objective
sigma_vae/train.py - Training workflow → Trainer and exports: starts training
sigma_vae/train.py - Trainer and exports → Conditional MMVAE: runs forward pass
sigma_vae/trainer.py - Trainer and exports → Training losses: computes losses
sigma_vae/trainer.py - Training workflow → Model evaluator: evaluates results
sigma_vae/train.py - Training workflow → Disentanglement checks: checks independence
sigma_vae/train.py - Model evaluator → Disentanglement checks: uses diagnostics
sigma_vae/evaluation.py - Researcher → Pretrained variants: loads checkpoint
README.md - Pretrained variants → Latent perturbation: supplies model weights
README.md - Latent perturbation → Perturbation maps: generates effects
README.md - Perturbation maps → Subcortical renderer: renders subcortical
README.md - Perturbation maps → Cortical renderer: renders cortical
README.md - Brain templates → Subcortical renderer: provides atlas
README.md - Brain templates → Cortical renderer: provides surfaces
README.md