# mahdisabetkish/brainssl architecture

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

- Interactive diagram: https://gitdiagram.com/mahdisabetkish/brainssl
- Repository: https://github.com/mahdisabetkish/brainssl

## Overview

brainssl is a research toolkit for label-efficient brain MRI and resting-state fMRI modeling. Users prepare public imaging data, run either the structural-MRI pretraining/fine-tuning or connectome-classification study, then evaluate results and optionally audit or export models. The graph separates those domain paths and includes the reporting layer. Relationships are limited to README claims and visible import references in the supplied source index; unsampled implementations are represented by their exact source paths, but uncertain internal calls are omitted.

Main entry points: [`src/brainssl/cli.py`](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/cli.py) (CLI router), [`src/brainssl/fmri/study.py`](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/fmri/study.py) (Connectome study), [`src/brainssl/smri/train.py`](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/smri/train.py) (Pretrain and tune), [`src/brainssl/trust/smri.py`](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/trust/smri.py) (Trust audits)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command entry"]
  node_cli["CLI router<br/>[cli.py]"]
  node_download["Data download<br/>[download.py]"]
end

subgraph group_smri["Structural MRI"]
  node_smri_prep["Volume preparation<br/>[preprocess.py]"]
  node_smri_mask["Twin masking<br/>[masking.py]"]
  node_smri_model["Bilateral U-Net<br/>[model.py]"]
  node_smri_train["Pretrain and tune<br/>[train.py]"]
  node_smri_infer["Segmentation inference<br/>[infer.py]"]
  node_smri_eval["Segmentation evaluation<br/>[evaluate.py]"]
  node_smri_metrics["Segmentation metrics<br/>[metrics.py]"]
end

subgraph group_fmri["Functional MRI"]
  node_abide["ABIDE time series<br/>[abide.py]"]
  node_connectivity["Connectome estimation<br/>[connectivity.py]"]
  node_windows["Scan windows<br/>[windows.py]"]
  node_methods["Classifiers<br/>[methods.py]"]
  node_fmri_eval["Fold evaluation<br/>[evaluate.py]"]
  node_fmri_study["Connectome study<br/>[study.py]"]
end

subgraph group_outputs["Analysis and delivery"]
  node_report_cli["Report commands<br/>[cli.py]"]
  node_report_collect["Result collection<br/>[collect.py]"]
  node_dashboard["Dashboard data<br/>[dashboard.py]"]
  node_trust["Trust audits<br/>[smri.py]"]
  node_export["Model export<br/>[cli.py]"]
  node_stats["Statistical tests<br/>[stats.py]"]
end

node_user(("Researcher"))

node_user -->|"runs commands"| node_cli
node_cli -->|"invokes download"| node_download
node_cli -->|"invokes preparation"| node_smri_prep
node_cli -->|"starts training"| node_smri_train
node_smri_train -->|"uses masking"| node_smri_mask
node_smri_train -->|"trains model"| node_smri_model
node_smri_train -->|"loads volumes"| node_smri_prep
node_cli -->|"invokes evaluation"| node_smri_eval
node_smri_eval -->|"evaluates model"| node_smri_model
node_smri_eval -.->|"scores predictions"| node_smri_metrics
node_cli -->|"starts fMRI workflow"| node_abide
node_abide -.->|"estimates matrices"| node_connectivity
node_abide -->|"supplies time series"| node_windows
node_windows -->|"estimates window views"| node_connectivity
node_cli -->|"starts study"| node_fmri_study
node_fmri_study -->|"loads subject data"| node_abide
node_fmri_study -->|"uses embeddings"| node_connectivity
node_fmri_study -->|"compares classifiers"| node_methods
node_fmri_study -->|"uses folds"| node_fmri_eval
node_cli -->|"routes reporting"| node_report_cli
node_report_cli -->|"collects results"| node_report_collect
node_report_cli -->|"builds dashboard data"| node_dashboard
node_report_collect -->|"computes statistics"| node_stats
node_cli -->|"routes trust audit"| node_trust
node_cli -->|"routes export"| node_export
node_export -->|"exports segmentation model"| node_smri_model
node_trust -->|"audits predictions"| node_smri_infer
node_trust -->|"loads test scans"| node_smri_prep
node_trust -->|"tests comparisons"| node_stats

click node_cli "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/cli.py"
click node_download "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/data/download.py"
click node_smri_prep "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/smri/preprocess.py"
click node_smri_mask "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/smri/masking.py"
click node_smri_model "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/smri/model.py"
click node_smri_train "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/smri/train.py"
click node_smri_infer "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/smri/infer.py"
click node_smri_eval "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/smri/evaluate.py"
click node_smri_metrics "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/smri/metrics.py"
click node_abide "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/fmri/abide.py"
click node_connectivity "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/fmri/connectivity.py"
click node_windows "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/fmri/windows.py"
click node_methods "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/fmri/methods.py"
click node_fmri_eval "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/fmri/evaluate.py"
click node_fmri_study "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/fmri/study.py"
click node_report_cli "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/report/cli.py"
click node_report_collect "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/report/collect.py"
click node_dashboard "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/report/dashboard.py"
click node_trust "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/trust/smri.py"
click node_export "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/export/cli.py"
click node_stats "https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/stats.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_cli,node_download toneBlue
class node_smri_prep,node_smri_mask,node_smri_model,node_smri_train,node_smri_infer,node_smri_eval,node_smri_metrics toneAmber
class node_abide,node_connectivity,node_windows,node_methods,node_fmri_eval,node_fmri_study toneMint
class node_report_cli,node_report_collect,node_dashboard,node_trust,node_export,node_stats toneRose
class node_user toneIndigo
```

## Components

### Command entry

- [CLI router](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/cli.py): `src/brainssl/cli.py`
- [Data download](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/data/download.py): `src/brainssl/data/download.py`

### Structural MRI

- [Volume preparation](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/smri/preprocess.py): `src/brainssl/smri/preprocess.py`
- [Twin masking](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/smri/masking.py): `src/brainssl/smri/masking.py`
- [Bilateral U-Net](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/smri/model.py): `src/brainssl/smri/model.py`
- [Pretrain and tune](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/smri/train.py): `src/brainssl/smri/train.py`
- [Segmentation inference](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/smri/infer.py): `src/brainssl/smri/infer.py`
- [Segmentation evaluation](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/smri/evaluate.py): `src/brainssl/smri/evaluate.py`
- [Segmentation metrics](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/smri/metrics.py): `src/brainssl/smri/metrics.py`

### Functional MRI

- [ABIDE time series](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/fmri/abide.py): `src/brainssl/fmri/abide.py`
- [Connectome estimation](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/fmri/connectivity.py): `src/brainssl/fmri/connectivity.py`
- [Scan windows](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/fmri/windows.py): `src/brainssl/fmri/windows.py`
- [Classifiers](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/fmri/methods.py): `src/brainssl/fmri/methods.py`
- [Fold evaluation](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/fmri/evaluate.py): `src/brainssl/fmri/evaluate.py`
- [Connectome study](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/fmri/study.py): `src/brainssl/fmri/study.py`

### Analysis and delivery

- [Report commands](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/report/cli.py): `src/brainssl/report/cli.py`
- [Result collection](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/report/collect.py): `src/brainssl/report/collect.py`
- [Dashboard data](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/report/dashboard.py): `src/brainssl/report/dashboard.py`
- [Trust audits](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/trust/smri.py): `src/brainssl/trust/smri.py`
- [Model export](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/export/cli.py): `src/brainssl/export/cli.py`
- [Statistical tests](https://github.com/mahdisabetkish/brainssl/blob/main/src/brainssl/stats.py): `src/brainssl/stats.py`

### Other components

- **Researcher**

## Connections

- Researcher → CLI router: runs commands (evidence: `src/brainssl/cli.py`)
- CLI router → Data download: invokes download (evidence: `src/brainssl/cli.py`)
- CLI router → Volume preparation: invokes preparation (evidence: `src/brainssl/cli.py`)
- CLI router → Pretrain and tune: starts training (evidence: `src/brainssl/cli.py`)
- Pretrain and tune → Twin masking: uses masking (evidence: `src/brainssl/smri/train.py`)
- Pretrain and tune → Bilateral U-Net: trains model (evidence: `src/brainssl/smri/train.py`)
- Pretrain and tune → Volume preparation: loads volumes (evidence: `src/brainssl/smri/train.py`)
- CLI router → Segmentation evaluation: invokes evaluation (evidence: `src/brainssl/cli.py`)
- Segmentation evaluation → Bilateral U-Net: evaluates model (evidence: `src/brainssl/smri/evaluate.py`)
- Segmentation evaluation → Segmentation metrics: scores predictions
- CLI router → ABIDE time series: starts fMRI workflow (evidence: `src/brainssl/cli.py`)
- ABIDE time series → Connectome estimation: estimates matrices
- ABIDE time series → Scan windows: supplies time series (evidence: `src/brainssl/fmri/windows.py`)
- Scan windows → Connectome estimation: estimates window views (evidence: `src/brainssl/fmri/windows.py`)
- CLI router → Connectome study: starts study (evidence: `src/brainssl/cli.py`)
- Connectome study → ABIDE time series: loads subject data (evidence: `src/brainssl/fmri/study.py`)
- Connectome study → Connectome estimation: uses embeddings (evidence: `src/brainssl/fmri/study.py`)
- Connectome study → Classifiers: compares classifiers (evidence: `src/brainssl/fmri/study.py`)
- Connectome study → Fold evaluation: uses folds (evidence: `src/brainssl/fmri/study.py`)
- CLI router → Report commands: routes reporting (evidence: `src/brainssl/cli.py`)
- Report commands → Result collection: collects results (evidence: `src/brainssl/report/cli.py`)
- Report commands → Dashboard data: builds dashboard data (evidence: `src/brainssl/cli.py`)
- Result collection → Statistical tests: computes statistics (evidence: `src/brainssl/report/collect.py`)
- CLI router → Trust audits: routes trust audit (evidence: `src/brainssl/cli.py`)
- CLI router → Model export: routes export (evidence: `src/brainssl/cli.py`)
- Model export → Bilateral U-Net: exports segmentation model
- Trust audits → Segmentation inference: audits predictions (evidence: `src/brainssl/trust/smri.py`)
- Trust audits → Volume preparation: loads test scans (evidence: `src/brainssl/trust/smri.py`)
- Trust audits → Statistical tests: tests comparisons (evidence: `src/brainssl/trust/smri.py`)