NeuroSSM

Multiscale Differential State-Space Modeling for Context-Aware fMRI Analysis

Official implementation of NeuroSSM described in the paper NeuroSSM: Multiscale Differential State-Space Modeling for Context-Aware fMRI Analysis.

NeuroSSM is a multi-pathway state-space architecture for ROI-wise fMRI time series. It processes raw BOLD signals and first-order temporal differences across multiple temporal scales, enabling context-aware classification of resting-state and task-based fMRI scans. We also provide the implementation of Calibrated Pathway Attribution (CPA) used to analyze pathway-specific explanations with class-matched Neurosynth meta-analytic reference maps.

Overall View

NeuroSSM architecture

Multiscale Differential State-Space Block (MSD-SSB)

Running

Dependencies

We recommend creating a clean conda environment. The main dependencies are:

• python >= 3.10
• numpy
• pandas
• scipy
• scikit-learn
• PyTorch
• mamba-ssm
• einops
• tqdm
• nibabel
• nilearn
• NiMARE

Create the environment first:

conda env create -f environment.yml
conda activate neurossm

Install PyTorch before installing mamba-ssm. For CUDA 12.8, run:

python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
python -m pip install --upgrade pip setuptools wheel packaging ninja
python -m pip install mamba-ssm --no-build-isolation

If your system uses a different CUDA version, install the matching PyTorch build first, then install mamba-ssm with --no-build-isolation.

Dataset

In our work, we used three datasets: HCP-Rest, HCP-Task, and PPMI. Due to dataset licenses, we do not redistribute raw fMRI scans, ROI-extracted arrays, PPMI files, or HCP phenotype files with this repository. Users should obtain access to the datasets from the official data providers and prepare ROI-level time series before running the code.

The expected data layout is:

Dataset/Data/
├── dataset_hcpRest_schaefer.npy
├── dataset_hcpTask_schaefer.npy
├── dataset_ppmi_atlas-AAL-3V2.pickle
└── HCP_1200/
    └── Preprocessed/
        └── pheno.csv

The HCP arrays should contain ROI-wise time series using the Schaefer-400 atlas. The PPMI file should contain ROI-wise time series using the AAL3v2 atlas. The HCP phenotype file pheno.csv is required for HCP-Rest labels and the HCP-Task Q1 subject filter. Since this file is derived from HCP subject metadata, users should download or prepare it according to the HCP data-use terms. At minimum, it should include the subject identifier, release label, and gender columns used by the HCP loaders.

Data Prep

Before training, place the ROI-extracted files under Dataset/Data/ using the filenames above. The loaders expect samples in ROI × time format. If a sample is stored as time × ROI, the provided loaders transpose it when the canonical time dimension is detected.

The default settings in Dataset/datasetDetails.py use:

HCP-Rest: Schaefer-400, dynamic length = 600, target = gender
HCP-Task: Schaefer-400, dynamic length = 150, target = cognitive task
PPMI:     AAL3v2,      dynamic length = 100, target = Parkinson's disease

Train and Testing

For training and testing NeuroSSM, run tester.py with the target dataset name:

python tester.py --dataset HCP_REST --model NeuroSSM --device 0
python tester.py --dataset HCP_TASK --model NeuroSSM --device 0
python tester.py --dataset PPMI --model NeuroSSM --device 0

The available dataset names are:

HCP_REST
HCP_TASK
PPMI

Results are written under:

Results/<DATASET>/NeuroSSM/

Analysis

CPA Extraction

To extract subject-level CPA maps on the holdout set, run training/testing with the --analysis flag:

python tester.py --dataset HCP_TASK --model NeuroSSM --analysis --skip_cross_validation --seeds 0 --device 0
python tester.py --dataset PPMI --model NeuroSSM --analysis --skip_cross_validation --seeds 0 --device 0

The extracted subject-level maps are saved under:

Analysis/Explainability/<DATASET>/seed_<SEED>/subj_*.npz

Each file contains the subject-level CPA attribution outputs required for the Neurosynth reference analysis.

Neurosynth Reference Analysis

After CPA extraction, run:

python Analysis/run_cpa_analysis.py \
  --root ./Analysis/Explainability \
  --out ./Analysis/Explainability_Results

The script downloads the Neurosynth/NiMARE data on the first run and then reuses the cached files in later runs. It computes class-specific Neurosynth reference maps, applies the CPA partial-correlation reference-scoring procedure, and saves only the CPA-related ROI-space NIfTI files:

Analysis/Explainability_Results/
└── maps/
    └── <DATASET>/
        └── <CLASS>/
            ├── neurosynth_reference_score.nii.gz
            ├── neurosynth_reference_top25_mask.nii.gz
            ├── cpa_score.nii.gz
            ├── cpa_score_top25_mask.nii.gz
            └── cpa_dominant_pathway.nii.gz

The repository intentionally provides the CPA extraction code, Neurosynth-based reference scoring code, and separate NIfTI map outputs. The final paper-specific multi-panel figure, bar-plot, table-generation, and ablation-output code is not included. The saved NIfTI files can be visualized with Nilearn, MRIcroGL, FSLeyes, or another neuroimaging visualization tool.

Method Notes

CPA combines within-pathway gradient localization with ablation-based calibration of pathway importance. For each pathway, the method computes an ROI-level activation-gradient attribution map. It then ablates the pathway before fusion and uses the resulting target-logit drop as the pathway importance signal. The public Neurosynth analysis saves the final CPA reference-alignment maps only; intermediate ablation/comparison maps are not exported.