fm_app

FM-APP Model Doc

Overview

FM-APP is a multi-stage framework for phenotype prediction via fMRI to sMRI knowledge transfer.

• Paper: He Z, Li W, Liu Y, et al. FM-APP, IEEE TMI, 2024, 44(10): 4010-4022
• Official code: https://github.com/ZhibinHe/FM-APP
• Primary input: fMRI ROI connectivity features
• Additional input: sMRI ROI structural features (required in Stage 2)
• Primary output: multi-phenotype prediction and zero-shot phenotype reconstruction

In NeuroClaw, this is model-level guidance. Upstream preparation should be delegated to:

• fmri-skill for fMRI preprocessing and ROI extraction
• smri-skill for structural ROI feature extraction
• hcpya-skill if HCP Young Adult download/orchestration is needed

Research use only.

---

Quick Start (From git clone)

1) Clone repository

git clone https://github.com/ZhibinHe/FM-APP.git
cd FM-APP

2) Create environment and install dependencies

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

If using GPU, install CUDA-compatible PyTorch and graph-related packages first.

3) Prepare required data

Before training, ensure these are ready:

• fMRI ROI/connectivity features from fmri-skill
• sMRI ROI structural features from smri-skill (for Stage 2)
• phenotype CSV files and text feature tensors in data/

4) Run staged pipeline

# Stage 0: data preparation (example scripts)
python 00-create-folder_hcp_4fmri.py
python 01-fetch_data_hcp_4fmri.py
python 02-process_data_hcp_4fmri.py

# Stage 1: fMRI model training
python 101-main_stage1_fmri_HCP.py

# Stage 2: fMRI-T1w alignment
python 102-main_stage2_fmri_t1w_HCP.py

# Stage 3: decoder and zero-shot inference
python 103-main_stage3_t1w_HCP.py

---

Pipeline Definition

Stage	Script pattern	Purpose	Core output
Stage 0	00-*, 01-*, 02-*	Data folder setup, ROI connectivity extraction, HDF5 packaging	raw/*.h5, processed inputs
Stage 1	101-main_stage1_fmri_HCP.py	fMRI feature extraction and phenotype regression	model/stage1_*.pth, model/stage1_dataset_*.pt
Stage 2	102-main_stage2_fmri_t1w_HCP.py	fMRI-T1w feature alignment (Sinkhorn-RPM)	model/stage2_*.pth
Stage 3	103-main_stage3_t1w_HCP.py	masked decoder training and zero-shot phenotype inference	stage-3 checkpoints and inference outputs