AutoFMRI

Automatic Two-Stage Thresholding for fMRI Decoding

AutoFMRI addresses the dimensionality challenge in fMRI decoding — where voxel counts vastly exceed trial counts — by introducing an automatic two-stage voxel selection framework:

1. Stage 1 (Atlas-based Patch Scoring + SHAP): Partition the brain into atlas-defined regions, score each region via cross-validated classification, then compute SHAP values to identify the most informative voxels within each top-performing region.
2. Stage 2 (Refined Classification): Merge the top-k SHAP-selected voxels across the best patches and train a final classifier. Hyperparameters are automatically tuned via RandomizedSearchCV.

Installation

pip install autofmri

Or install from source:

git clone https://github.com/y10ab1/AutoFMRI.git
cd AutoFMRI
pip install -e .

Optional dependencies

# CNN support (PyTorch + skorch)
pip install autofmri[cnn]

# XGBoost support
pip install autofmri[xgboost]

# Visualization (matplotlib + seaborn)
pip install autofmri[viz]

# Everything
pip install autofmri[all]

Quick Start

from autofmri import AutoEstimator, set_seed
from autofmri.data import HaxbyDataLoader
from autofmri.models import get_model
from sklearn.model_selection import StratifiedKFold

set_seed(42)

# Load data
loader = HaxbyDataLoader(data_dir="data/haxby2001/subj4")
X, y = loader.load_volume_data()

# Train with two-stage AutoFMRI
clf = AutoEstimator(
    stage1_model=get_model("rf"),
    stage2_model=get_model("rf"),
    stage1_model_type="rf",
    stage2_model_type="rf",
    atlas_name="yeo",
    ref_img=loader.reference_img,
)

skf = StratifiedKFold(n_splits=4, shuffle=True, random_state=42)
train_idx, test_idx = next(iter(skf.split(X, y)))

clf.fit(X[train_idx], y[train_idx])
accuracy = clf.score(X[test_idx], y[test_idx])
print(f"Accuracy: {accuracy:.4f}")

CLI Usage

AutoFMRI provides a unified command-line interface:

# Two-stage AutoFMRI method
autofmri train --dataset haxby --data-dir ./data/haxby2001/subj4 \
    --method autofmri --stage1-model rf --stage2-model rf --atlas yeo

# Baseline: ROI + ANOVA feature selection
autofmri train --dataset hcp_emotion \
    --data-dir ./data/emotion --method baseline_anova --subjects 1 2 3

# Baseline: ROI + RFE
autofmri train --dataset hcp_gambling \
    --data-dir ./data/gambling --method baseline_rfe

Available options

Supported Datasets

Supported Models

Project Structure

autofmri/
├── __init__.py          # Public API
├── estimator.py         # AutoEstimator (core algorithm)
├── patchify.py          # Atlas loading & brain patchification
├── cli.py               # Unified CLI
├── models/
│   ├── factory.py       # get_model() factory
│   └── cnn.py           # 1D CNN architecture
├── data/
│   ├── base.py          # BaseFMRIDataLoader (ABC)
│   ├── haxby.py         # Haxby 2001
│   ├── hcp.py           # HCP tasks (Emotion/Gambling/Language)
│   ├── vkmc.py          # VKMC musical pitch
│   └── gtzan.py         # GTZAN music genre
└── utils/
    ├── shap.py          # SHAP value computation
    ├── image.py         # NIfTI image utilities
    └── seed.py          # Reproducibility & tSNR

Previous Repository

This project was originally developed as fMRI-feature-decoder. That repository now redirects here.

Citation

If you use AutoFMRI in your research, please cite:

@INPROCEEDINGS{10095192,
  author={Cheung, Vincent K.M. and Peng, Yueh-Po and Lin, Jing-Hua and Su, Li},
  booktitle={ICASSP 2023 - 2023 IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP)},
  title={Decoding Musical Pitch from Human Brain Activity with Automatic Voxel-Wise Whole-Brain FMRI Feature Selection},
  year={2023},
  pages={1-5},
  doi={10.1109/ICASSP49357.2023.10095192}
}

License

This project is licensed under the MIT License. See LICENSE for details.