braingnn git:20260505.e9ddd22A

Immutable. This exact content is served forever at /api/v1/blob/37304570c4a5e1b0.

---
name: braingnn
description: "Use this model doc whenever the user wants to run BrainGNN for fMRI phenotype prediction, including graph construction, training, and evaluation. This document focuses on model-level usage and delegates upstream preprocessing to fmri-skill (and optionally hcp-skill)."
license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
layer: base
skill_type: model
dependencies:
  - fmri-skill
  - run_models
---
# BrainGNN Model Doc

## Overview
BrainGNN is an interpretable graph neural network for fMRI analysis and phenotype prediction.

- Paper: Li et al., 2020, BrainGNN
- Official code: https://github.com/xxlya/BrainGNN_Pytorch/tree/main
- Primary input: ROI-level fMRI data (timeseries/connectivity)
- Primary output: phenotype prediction (classification/regression, task-dependent)

In NeuroClaw, this document is model-level guidance. Upstream data preparation should be delegated to:
- `fmri-skill` for fMRI preprocessing and ROI extraction
- `hcp-skill` when HCP dataset download/orchestration is needed

**Research use only.**

---

## Quick Start (From git clone)

### 1) Clone repository
```bash
git clone https://github.com/xxlya/BrainGNN_Pytorch.git
cd BrainGNN_Pytorch
```

### 2) Create environment and install dependencies
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

If using GPU, install version-matched PyTorch/PyG builds first, then install remaining requirements.

### 3) Prepare data (ROI first)
Use `fmri-skill` to prepare ROI timeseries and metadata, then arrange files under:
- `data/{dataset_name}-rest.csv`
- `data/{dataset_name}_roi/`

### 4) Run 3-phase pipeline
```bash
# Phase 1: build connectivity matrices
python 01-fetch_data.py --atlas aal3 --dataset_name adhd200 --dataset_dir data

# Phase 2: convert to graph samples
python 02-process_data.py --atlas aal3 --dataset_name adhd200 --dataset_dir data --nclass 2 --score DX

# Phase 3: train/evaluate BrainGNN
CUDA_VISIBLE_DEVICES=0 python 03-main.py \
  --atlas aal3 --dataset_name adhd200 --dataset_dir data \
  --indim 166 --nroi 166 --nclass 2 --fold 0
```

---

## Pipeline Definition

### Phase 1: Connectivity Generation (`01-fetch_data.py`)
Purpose: convert ROI timeseries to connectivity features.

Outputs:
- `data/{dataset_name}_roi/braingnn_{atlas}/*.mat`
- `data/{dataset_name}_roi/braingnn_{atlas}/valid_subject_list.pkl`

Key args:
- `--atlas`: `aal3`, `dk`, `cc200`, `ho`
- `--dataset_name`: `adhd200`, `cobre`, `UCLA`, `hcp-d`, `hcp-ep`, `ABCD`
- `--dataset_dir`: root data dir, default `data`

### Phase 2: Graph Construction (`02-process_data.py`)
Purpose: convert connectivity matrices into per-subject graph files.

Outputs:
- `data/{dataset_name}_roi/braingnn_{atlas}/raw/{subject_id}.h5`

Common args:
- `--nclass`: class count
- `--score`: label key (`DX`, `Gender`, `Age`)
- `--seed`: random seed

### Phase 3: Training and Evaluation (`03-main.py`)
Purpose: train BrainGNN with fold-wise evaluation and checkpointing.

Outputs:
- `model/{fold}.pth`
- `model/log/{fold}/` (TensorBoard)

Core model options:
- `--indim`, `--nroi`: must match atlas ROI count
- `--nclass`: output classes
- `--fold`: CV fold index
- `--n_epochs`, `--batchSize`, `--lr`, `--weightdecay`

---

## Input / Output Contract

### Required inputs
- ROI timeseries per subject
- Subject metadata CSV with labels
- Dataset name and atlas selection

### Produced outputs
- Connectivity matrices and graph files
- Trained checkpoint(s)
- Evaluation logs and metrics

---

## Atlas and Dimension Mapping

| Atlas | Typical ROI count | Required flags |
|---|---:|---|
| `aal3` | 166 | `--indim 166 --nroi 166` |
| `cc200` | 200 | `--indim 200 --nroi 200` |
| `dk` | atlas-dependent | set both flags to actual ROI count |
| `ho` | atlas-dependent | set both flags to actual ROI count |

If `--indim` or `--nroi` does not match the real ROI count, training will fail.

---

## Recommended Directory Layout

```text
BrainGNN_Pytorch/
  data/
    {dataset_name}-rest.csv
    {dataset_name}_roi/
      braingnn_{atlas}/
        *.mat
        valid_subject_list.pkl
        raw/*.h5
  model/
    {fold}.pth
    log/{fold}/
```

---

## NeuroClaw Delegation Rules

- ROI generation and preprocessing: delegate to `fmri-skill`
- HCP download/orchestration (if needed): delegate to `hcp-skill`
- Dependency checks: `dependency-planner` + `conda-env-manager`
- Execution routing: `claw-shell`

No execution before explicit plan confirmation.

---

## Limitations and Notes

- This workflow assumes ROI data already exists before Phase 1.
- GPU is strongly recommended for training speed.
- Cross-validation is controlled by running Phase 3 repeatedly with different `--fold` values.
- TensorBoard command:
```bash
tensorboard --logdir ./model/log/
```

---

## Reference

- Li X, Zhou Y, Dvornek N, Zhang M, Gao S, Zhuang J, Scheinost D, Staib L, Ventola P, Duncan J. 2020. BrainGNN.
- Official repository: https://github.com/xxlya/BrainGNN_Pytorch/tree/main
- PyG installation notes: https://pytorch-geometric.readthedocs.io/en/latest/notes/installation.html

Created At: 2026-03-28 19:53 HKT
Last Updated At: 2026-03-28 19:53 HKT
Author: chengwang96