lggnn

name	lggnn
description	Use this model doc whenever the user wants to run LG-GNN (Local-to-Global GNN) for fMRI phenotype prediction. LG-GNN is a PyG-based GNN with SABP (Self-Attention Brain Pooling) and mutual-information regularization. NeuroClaw adapts the original population-graph version to single-subject brain graphs.
license	MIT License (NeuroClaw custom skill - freely modifiable within the project)
layer	base
skill_type	model
dependencies	["fmri-skill","run_models"]

LG-GNN Model Doc

Overview

LG-GNN (Local-to-Global GNN) 是一种针对脑疾病诊断的两阶段图神经网络。原始论文使用 Local_GNN 提取每个被试的脑图嵌入，再通过基于人口学信息构建的 Global_GNN 进行人群图分类。NeuroClaw 改造为单被试任务：保留 Local_GNN（含 SABP + 互信息正则化的创新组件），用 MLP head 替代人口图。

• Paper: Zhang et al., 2022, "Local to Global Hierarchical Graph Neural Network for Brain Disorder Diagnosis"，MICCAI
• Official code: https://github.com/cnuzh/LG-GNN
• NeuroClaw reimplementation: models/lggnn/（去除人口图依赖，单被试 PyG 流程）
• Primary input: PyG Data graph（与 BrainGNN 共享数据格式）
• Primary output: phenotype prediction + ROI 重要性（SABP perm）+ MI loss 辅助监督

Research use only.

---

NeuroClaw 实现要点

1. 单被试改造：原版需要非影像表型数据构建人口图，NeuroClaw 仅保留 Local_GNN，用 MLP head 输出。
2. SABP 池化：Self-Attention Brain Pooling，topk 选择 ROI + tanh(score) 加权，并产生互信息估计 mi 作为辅助 loss（论文权重 0.1，loss 取 loss - 0.1 * mi 鼓励高互信息）。
3. PyG 2.7 兼容：原 torch_geometric.nn.pool.topk_pool 已重构，NeuroClaw 用 pool.select.topk + 内联 filter_adj。
4. 任务统一接口：classification (nclass=N) 与 regression (nclass=1, task='regression') 一套代码。
5. 数据复用：直接复用 BrainGNN 的 NeuroClawFCDataset，无需额外预处理。

---

Quick Start (NeuroClaw 内部)

前置条件

• conda env: neuroclaw (Python 3.11)
• 已有 data/braingnn_input/<atlas>/sub-*.pt 文件（与 BrainGNN 共享）

训练（分类，单 fold 冒烟测试）

python skills/lggnn/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/lggnn/scripts/train_reference.py \
    --atlas schaefer_100_7net \
    --labels-csv data/hcp_age_labels.csv \
    --task regression --fold 0 --n-epochs 50

---

核心文件

文件	作用
models/lggnn/net/lggnn.py	模型定义：LocalGNN (GCN×2 + SABP + GCN) + MLP head
models/lggnn/scripts/data_adapter.py	数据适配（薄封装复用 models.braingnn）
skills/lggnn/scripts/train_reference.py	K-fold CV 训练参考实现

---

模型架构

Input PyG Data (x=[N,N], edge_index, edge_attr, batch)
  -> GCNConv(N, 64) + ReLU
  -> GCNConv(64, 20) + ReLU
  -> SABP pool (ratio=0.5): topk_score + tanh weighted; 产生 mi_estimate
  -> GCNConv(20, 20) + ReLU
  -> 残差: pooled + conv3
  -> global_mean_pool
  -> MLP head: Linear(20 -> 64) + ReLU + Dropout + Linear(64 -> nclass)
Output: (logits, mi_loss)

---

关键训练参数

参数	论文默认	NeuroClaw 默认	说明
--lr	0.01	0.001	论文用 0.01，NeuroClaw 与其他模型对齐用 0.001
--wd	5e-5	5e-4	权重衰减
--hidden-dim	64	64	GCN 隐藏维度
--embed-dim	20	20	SABP 后嵌入维度
--ratio	0.9	0.5	SABP keep ratio，论文 0.9，对齐 BrainGNN 用 0.5
--dropout	0.2	0.3	MLP head dropout
--mi-weight	0.1	0.1	MI loss 权重（注意：从 loss 中减去）
--n-epochs	400	50	论文 400 ep，NeuroClaw 50 ep 与其他模型对齐

---

调试经验与注意事项

1. MI loss 符号：原论文 loss = loss_cla - 0.1 * mi_loss（最大化 MI），NeuroClaw 保持相同符号约定。
2. SABP 输出形状：池化后节点数变为 floor(ratio * N)，注意 batch 后的 graph_emb 是 [B, embed_dim]。
3. ratio 调参：论文 ratio=0.9（仅丢 10% ROI）需要 hgc=16；NeuroClaw 用 hgc=64 时 ratio=0.5 更稳定。
4. PyG 2.7 兼容：旧版 topk_pool.topk/filter_adj 已移除，使用 pool.select.topk.topk 与内联 _filter_adj。
5. MI 初始为 0：训练开始时 mi_estimate ≈ 0（因 joint 和 margin 分布相近），训练过程中应逐步变正。
6. 数据复用：与 BrainGNN 共享 NeuroClawFCDataset，无需重复加载/缓存。

---

NeuroClaw 委托规则

• ROI 生成和预处理：委托 fmri-skill
• HCP 数据下载/编排：委托 hcpya-skill / hcpa-skill / hcpd-skill / hcpep-skill
• 依赖检查：dependency-planner + conda-env-manager
• 执行路由：claw-shell

执行前需明确计划确认。

---

Reference

• Zhang Y, Zhan L, Cai W, Thompson P, Huang H. 2022. Local to Global Hierarchical Graph Neural Network for Brain Disorder Diagnosis. MICCAI.
• Official repository: https://github.com/cnuzh/LG-GNN
• 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