combraintf

Com-BrainTF Model Doc

Overview

Com-BrainTF (Community-aware Brain Transformer) 是一种针对 fMRI 连接组的两级 Transformer。第一级对每个脑功能社区（如 Yeo 7-network）内的 ROI 独立做 self-attention，并为每个社区维护一个可学习的 CLS token；第二级把所有社区的 CLS + 全部 ROI 节点拼接，再过一个带 DEC 池化的 Transformer，最后展平进 FC head。

• Paper: Bannadabhavi et al., 2023, "Community-Aware Transformer for Autism Prediction in fMRI Connectome"，MICCAI
• Official code: https://github.com/ubc-tea/Com-BrainTF
• NeuroClaw reimplementation: models/combraintf/（去除 hydra/omegaconf 与硬编码 node_clus_map，改为运行时从 atlas 推导）
• Primary input: dense FC 矩阵 [B, N, N]
• Primary output: phenotype prediction + DEC assignment + per-level attention

Research use only.

NeuroClaw 实现要点

1. 去除 hydra/omegaconf：原版用 hydra 配置 + DictConfig，NeuroClaw 改为纯 Python 构造函数，所有参数显式传入。
2. 动态 community partition：原版从 node_clus_map.pickle 加载 Schaefer-400 的固定社区映射；NeuroClaw 在 data_adapter.py::build_community_ids(atlas) 里根据 ROI 名自动推导：
   • schaefer_*_7net → Yeo 7-network（Vis/SomMot/DorsAttn/SalVentAttn/Limbic/Cont/Default）+ Unknown 兜底，共 8 组
   • aal_* / destrieux / dk_* / harvard_oxford_* → 7 lobe + Other = 8 组
   • 其他无语义命名的 atlas（cc200/glasser/basc/power/msdl）→ MD5 hash round-robin 8 组兜底
3. 支持任意 atlas：上层只需传 community_ids: list[int]（长度 = n_roi），模型自动按社区分组、独立 local transformer。
4. 每社区独立 CLS token：与原版一致，每个社区一个 nn.Parameter([1, d_model])，由 local_transformers[k] 持有。
5. 任务统一接口：classification (nclass=N) 与 regression (nclass=1, task='regression')。
6. 数据复用：直接复用 BNT 的 BNTDataset + bnt_collate，无需额外预处理。

Quick Start (NeuroClaw 内部)

前置条件

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

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

python skills/combraintf/scripts/train_reference.py \
    --atlas schaefer_200_7net \
    --labels-csv data/hcp_gender_labels.csv \
    --fold 0 --n-epochs 10 --batch-size 8

训练（回归，HCP age）

python skills/combraintf/scripts/train_reference.py \
    --atlas aal_116 \
    --labels-csv data/hcp_age_labels.csv \
    --task regression --fold 0 --n-epochs 50