pySPFM

pySPFM#

Sparse Paradigm Free Mapping for fMRI

Latest Version PyPI - Python Version DOI CircleCI License Documentation Status Codecov

About#

pySPFM is a Python library for sparse hemodynamic deconvolution of fMRI data. It provides scikit-learn compatible estimators for detecting neural activity without requiring prior knowledge of experimental timing—making it ideal for naturalistic, resting-state, and clinical fMRI studies.

Why pySPFM?#

Traditional fMRI analysis relies on knowing when stimuli were presented. But what if you:

  • 🧠 Don’t have timing information — analyzing resting-state or naturalistic paradigms

  • 🏥 Study spontaneous events — epileptic spikes, mind wandering, or intrinsic activity

  • 🔬 Want data-driven discovery — letting the data reveal when neural events occurred

  • đź“Š Need robust estimation — reducing false positives through stability selection

pySPFM solves these problems by deconvolving the hemodynamic response function (HRF) from BOLD signals to estimate the underlying neural activity at each timepoint.

Key Features#

🎯 Sparse Deconvolution (SparseDeconvolution)#

The core algorithm for paradigm-free mapping. Estimates sparse activity-inducing signals using L1 (LASSO) or L2,1 mixed-norm regularization.

  • Univariate mode: Fast, voxel-wise independent deconvolution

  • Multivariate mode: Joint spatial regularization for whole-brain consistency

  • Multiple solvers: LARS (fast, exact) or FISTA (flexible, supports spatial grouping)

  • Automatic λ selection: BIC, AIC, MAD, and other criteria

🔄 Low-Rank Plus Sparse (LowRankPlusSparse)#

The SPLORA algorithm separates fMRI data into:

  • Low-rank component: Global/structured signals (physiological noise, drift)

  • Sparse component: Transient neuronal activity

Perfect for cleaning data while preserving neural events.

đź“Š Stability Selection (StabilitySelection)#

Robust feature selection through subsampling. Instead of a single solution, get selection frequencies that indicate how reliably each timepoint is detected across many subsampled datasets.

🔧 Flexible & Extensible#

  • scikit-learn API: fit(), transform(), get_params(), set_params()

  • Multi-echo support: Leverage information across echo times

  • Custom HRF: Use SPM, Glover, or your own HRF model

  • Block/Spike models: Detect transient events or sustained activity

Quick Start#

from pySPFM import SparseDeconvolution
import nibabel as nib
from nilearn.maskers import NiftiMasker

# Load and mask fMRI data
img = nib.load("my_fmri_data.nii.gz")
masker = NiftiMasker(mask_img="my_mask.nii.gz")
X = masker.fit_transform(img)  # (n_timepoints, n_voxels)

# Fit sparse deconvolution
model = SparseDeconvolution(tr=2.0, criterion="bic")
model.fit(X)

# Get estimated neural activity
activity = model.coef_  # (n_timepoints, n_voxels)

References#

When using pySPFM, please cite the following:

Core Methodology#

  1. Uruñuela, E., Bolton, T. A. W., Van De Ville, D., & Caballero-Gaudes, C. (2023). Hemodynamic Deconvolution Demystified: Sparsity-Driven Regularization at Work. Aperture Neuro, 3, 1–25.

  2. Caballero-Gaudes, C., Petridou, N., Francis, S. T., Dryden, I. L., & Gowland, P. A. (2013). Paradigm free mapping with sparse regression automatically detects single-trial fMRI responses. Human Brain Mapping, 34(3), 501–518.

  3. Karahanoğlu, F. I., Caballero-Gaudes, C., Lazeyras, F., & Van De Ville, D. (2013). Total activation: fMRI deconvolution through spatio-temporal regularization. NeuroImage, 73, 121–134.

Stability Selection#

  1. Uruñuela, E., Jones, S., Crawford, A., et al. (2020). Stability-based sparse paradigm free mapping algorithm for deconvolution of functional MRI data. IEEE EMBC, 1092–1095.

Multivariate / Whole-Brain Deconvolution#

  1. Uruñuela, E., Gonzalez-Castillo, J., Zheng, C., Bandettini, P. A., & Caballero-Gaudes, C. (2024). Whole-brain multivariate hemodynamic deconvolution for functional MRI with stability selection. Medical Image Analysis, 91, 103010.

Low-Rank Plus Sparse (SPLORA)#

  1. Uruñuela, E., Moia, S., & Caballero-Gaudes, C. (2021). A low rank and sparse paradigm free mapping algorithm for deconvolution of fMRI data. IEEE ISBI, 1726–1729.

Software Citation#

pySPFM — https://doi.org/10.5281/zenodo.6600095

License#

pySPFM is licensed under the GNU Lesser General Public License version 2.1.

Contents:

Indices and tables#

Contents