gabrielmoreira IBGNN Model Doc
Overview
IBGNN (Interpretable Brain Graph Neural Network) 是面向脑连接组分析的可解释 GNN。核心组件是 MPConv —— 在 GCN 归一化基础上，将消息计算从简单加权聚合改为 MLP([x_i, x_j, edge_attr]) 学习消息函数。模型与 post-hoc 边遮罩 explainer 配合使用，可提取对预测重要的边子图。
- Paper: Cui et al., 2022, "Interpretable Graph Neural Networks for Connectome-Based Brain Disorder Analysis"，MICCAI
- Official code: https://github.com/HennyJie/IBGNN
- NeuroClaw reimplementation:
models/ibgnn/（移除 explainer 用的 edge_flag 机制，仅保留 encoder） - Primary input: PyG Data graph（与 BrainGNN 共享数据格式）
- Primary output: phenotype prediction（可选 attention/重要边解释）
Research use only.
NeuroClaw 实现要点
- MPConv 核心：每条边的消息 =
Linear([x_i, x_j, edge_attr])，比 GCN 多一层非线性表达。 - GCN 归一化：边权 |corr| 经过对称归一化（与 GCN 相同），再注入 self-loop。
- 去除 edge_flag：原版用于 explainer 屏蔽边，普通 forward 中 edge_flag 是全 1 tensor，NeuroClaw 直接砍掉以简化代码。
- 正边权约束：
edge_attr.abs()后传入，与 BrainGNN 同样做法（softmax 类操作需要非负）。 - 任务统一接口：classification (
nclass=N) 与 regression (nclass=1, task='regression') 一套代码。 - PyG 2.7 兼容：
torch_scatter.scatter_add已被torch_geometric.utils.scatter(reduce='sum')替代。 - 数据复用：直接复用 BrainGNN 的
NeuroClawFCDataset，无需额外预处理。
Quick Start (NeuroClaw 内部)
前置条件
- conda env:
neuroclaw(Python 3.11) - 已有
data/braingnn_input/<atlas>/sub-*.pt文件（与 BrainGNN 共享）
训练（分类，单 fold 冒烟测试）
python skills/ibgnn/scripts/train_reference.py \
--atlas aal_116 \
--labels-csv data/hcp_gender_labels.csv \
--fold 0 --n-epochs 10 --batch-size 16
训练（回归，HCP age）
python skills/ibgnn/scripts/train_reference.py \
--atlas schaefer_100_7net \
--labels-csv data/hcp_age_labels.csv \
--task regression --fold 0 --n-epochs 50
核心文件
| 文件 | 作用 |
|---|---|
models/ibgnn/net/ibgnn.py |
模型定义：MPConv + IBGConv stack + MLP head |
models/ibgnn/scripts/data_adapter.py |
数据适配（薄封装复用 models.braingnn） |
skills/ibgnn/scripts/train_reference.py |
K-fold CV 训练参考实现 |
模型架构
Input PyG Data (x=[N,N], edge_index, edge_attr, batch)
-> abs(edge_attr) -> gcn_norm with self-loops
-> MPConv(N, hidden) + ReLU + Dropout
-> MPConv(hidden, hidden) (n_gnn_layers 层)
-> global_mean_pool (或 sum)
-> MLP head: Linear(hidden, hidden) + ReLU + shortcut + Linear(hidden, nclass)
Output: logits
每条边的消息：msg(i,j) = Linear([h_i; h_j; edge_weight])
关键训练参数
| 参数 | 论文默认 | NeuroClaw 默认 | 说明 |
|---|---|---|---|
--lr |
1e-4 | 1e-3 | 论文 1e-4，对齐其他模型用 1e-3 |
--wd |
1e-5 | 5e-4 | 权重衰减 |
--hidden-dim |
128 | 128 | GNN/MLP 隐藏维度 |
--n-gnn-layers |
2-3 | 2 | MPConv 堆叠层数 |
--n-mlp-layers |
1 | 1 | MLP head 深度 |
--pooling |
mean | mean | 'mean' 或 'sum' |
--n-epochs |
100 | 50 | 与其他模型对齐 |
--batch-size |
16 | 16 |
调试经验与注意事项
edge_attr.abs()必须：FC 矩阵带负相关，但 GCN 归一化和消息聚合假设非负权重，否则归一化得到 NaN。- MPConv 参数量：消息 MLP
Linear(2*hidden+1, hidden)，每层约(2H+1)*H参数，比 GCN 重 ~2 倍。 - n_gnn_layers 选择：论文 2-3 层最优；超过 3 层会过平滑。
- shortcut connection：MLP head 内
h = net(x) + shortcut(x)，避免深网络梯度衰减。 - PyG 2.7 兼容：使用
torch_geometric.utils.scatter替代已废弃的torch_scatter.scatter_add。 - 数据复用：与 BrainGNN 共享
NeuroClawFCDataset，无需重复加载/缓存。 - Explainer 未移植：原 repo 的
main_explainer.py（GNNExplainer 后处理）暂未移植，若需可补充。
NeuroClaw 委托规则
- ROI 生成和预处理：委托
fmri-skill - HCP 数据下载/编排：委托
hcpya-skill/hcpa-skill/hcpd-skill/hcpep-skill - 依赖检查：
dependency-planner+conda-env-manager - 执行路由：
claw-shell
执行前需明确计划确认。
Reference
- Cui H, Dai W, Zhu Y, Li X, He L, Yang C. 2022. Interpretable Graph Neural Networks for Connectome-Based Brain Disorder Analysis. MICCAI.
- Official repository: https://github.com/HennyJie/IBGNN
- BrainGB benchmark by same author: https://github.com/HennyJie/BrainGB
- NeuroClaw BrainGNN skill (共享数据格式):
skills/brain_gnn/SKILL.md
Created At: 2026-05-19 01:30 HKT Last Updated At: 2026-05-19 01:30 HKT Author: chengwang96