# mariam186/sigma-vae architecture

> Architecture diagram of the GitHub repository mariam186/sigma-vae, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mariam186/sigma-vae
- Repository: https://github.com/mariam186/sigma-vae

## Overview

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: [`sigma_vae/train.py`](https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/train.py) (Training workflow), [`sigma_vae/trainer.py`](https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/trainer.py) (Trainer and exports), [`sigma_vae/data.py`](https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/data.py) (Data processor), [`pretrained_models`](https://github.com/mariam186/sigma-vae/tree/main/pretrained_models) (Pretrained variants)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_processor["Data processor<br/>[data.py]"]
  node_dataset["Multi-view batches<br/>[data.py]"]
end

subgraph group_model["Model and training"]
  node_runner["Training workflow<br/>[train.py]"]
  node_network["Conditional MMVAE<br/>[models.py]"]
  node_objective["Training losses<br/>[losses.py]"]
  node_trainer["Trainer and exports<br/>[trainer.py]"]
  node_weights[("Pretrained variants")]
end

subgraph group_analysis["Evaluation"]
  node_evaluation["Model evaluator<br/>[evaluation.py]"]
  node_diagnostics["Disentanglement checks<br/>[diagnostics.py]"]
end

subgraph group_interpret["Interpretation"]
  node_perturb["Latent perturbation"]
  node_maps["Perturbation maps"]
  node_subrender["Subcortical renderer"]
  node_corticalrender["Cortical renderer"]
end

node_analyst(("Researcher"))
node_csvinput["MRI view CSVs"]
node_templates[("Brain templates")]

node_analyst -->|"provides views"| node_csvinput
node_csvinput -->|"loads and aligns"| node_processor
node_processor -->|"creates batches"| node_dataset
node_analyst -->|"configures and runs"| node_runner
node_runner -->|"loads training data"| node_processor
node_runner -->|"constructs model"| node_network
node_runner -->|"configures objective"| node_objective
node_runner -->|"starts training"| node_trainer
node_trainer -->|"runs forward pass"| node_network
node_trainer -->|"computes losses"| node_objective
node_runner -->|"evaluates results"| node_evaluation
node_runner -->|"checks independence"| node_diagnostics
node_evaluation -->|"uses diagnostics"| node_diagnostics
node_analyst -->|"loads checkpoint"| node_weights
node_weights -->|"supplies model weights"| node_perturb
node_perturb -->|"generates effects"| node_maps
node_maps -->|"renders subcortical"| node_subrender
node_maps -->|"renders cortical"| node_corticalrender
node_templates -->|"provides atlas"| node_subrender
node_templates -->|"provides surfaces"| node_corticalrender

click node_processor "https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/data.py"
click node_dataset "https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/data.py"
click node_runner "https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/train.py"
click node_network "https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/models.py"
click node_objective "https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/losses.py"
click node_trainer "https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/trainer.py"
click node_weights "https://github.com/mariam186/sigma-vae/tree/main/pretrained_models"
click node_evaluation "https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/evaluation.py"
click node_diagnostics "https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/diagnostics.py"
click node_perturb "https://github.com/mariam186/sigma-vae/blob/main/interpretation/perturbation_analysis.py"
click node_subrender "https://github.com/mariam186/sigma-vae/blob/main/interpretation/render_subcortical.py"
click node_corticalrender "https://github.com/mariam186/sigma-vae/blob/main/interpretation/render_cortical_surface.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_processor,node_dataset,node_csvinput toneBlue
class node_runner,node_network,node_objective,node_trainer,node_weights,node_templates toneAmber
class node_evaluation,node_diagnostics toneMint
class node_perturb,node_maps,node_subrender,node_corticalrender toneRose
class node_analyst toneIndigo
```

## Components

### Data preparation

- [Data processor](https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/data.py): `sigma_vae/data.py`
- [Multi-view batches](https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/data.py): `sigma_vae/data.py`

### Model and training

- [Training workflow](https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/train.py): `sigma_vae/train.py`
- [Conditional MMVAE](https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/models.py): `sigma_vae/models.py`
- [Training losses](https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/losses.py): `sigma_vae/losses.py`
- [Trainer and exports](https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/trainer.py): `sigma_vae/trainer.py`
- [Pretrained variants](https://github.com/mariam186/sigma-vae/tree/main/pretrained_models): `pretrained_models`

### Evaluation

- [Model evaluator](https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/evaluation.py): `sigma_vae/evaluation.py`
- [Disentanglement checks](https://github.com/mariam186/sigma-vae/blob/main/sigma_vae/diagnostics.py): `sigma_vae/diagnostics.py`

### Interpretation

- [Latent perturbation](https://github.com/mariam186/sigma-vae/blob/main/interpretation/perturbation_analysis.py): `interpretation/perturbation_analysis.py`
- **Perturbation maps**
- [Subcortical renderer](https://github.com/mariam186/sigma-vae/blob/main/interpretation/render_subcortical.py): `interpretation/render_subcortical.py`
- [Cortical renderer](https://github.com/mariam186/sigma-vae/blob/main/interpretation/render_cortical_surface.py): `interpretation/render_cortical_surface.py`

### Other components

- **Researcher**
- **MRI view CSVs**
- **Brain templates**

## Connections

- Researcher → MRI view CSVs: provides views (evidence: `README.md`)
- MRI view CSVs → Data processor: loads and aligns (evidence: `README.md`)
- Data processor → Multi-view batches: creates batches (evidence: `sigma_vae/data.py`)
- Researcher → Training workflow: configures and runs (evidence: `README.md`)
- Training workflow → Data processor: loads training data (evidence: `sigma_vae/train.py`)
- Training workflow → Conditional MMVAE: constructs model (evidence: `sigma_vae/train.py`)
- Training workflow → Training losses: configures objective (evidence: `sigma_vae/train.py`)
- Training workflow → Trainer and exports: starts training (evidence: `sigma_vae/train.py`)
- Trainer and exports → Conditional MMVAE: runs forward pass (evidence: `sigma_vae/trainer.py`)
- Trainer and exports → Training losses: computes losses (evidence: `sigma_vae/trainer.py`)
- Training workflow → Model evaluator: evaluates results (evidence: `sigma_vae/train.py`)
- Training workflow → Disentanglement checks: checks independence (evidence: `sigma_vae/train.py`)
- Model evaluator → Disentanglement checks: uses diagnostics (evidence: `sigma_vae/evaluation.py`)
- Researcher → Pretrained variants: loads checkpoint (evidence: `README.md`)
- Pretrained variants → Latent perturbation: supplies model weights (evidence: `README.md`)
- Latent perturbation → Perturbation maps: generates effects (evidence: `README.md`)
- Perturbation maps → Subcortical renderer: renders subcortical (evidence: `README.md`)
- Perturbation maps → Cortical renderer: renders cortical (evidence: `README.md`)
- Brain templates → Subcortical renderer: provides atlas (evidence: `README.md`)
- Brain templates → Cortical renderer: provides surfaces (evidence: `README.md`)
