pySPFM.SparseDeconvolution

`pySPFM`.SparseDeconvolution#

class SparseDeconvolution(*, tr, te=None, hrf_model='spm', block_model=False, criterion='bic', debias=True, group=0.0, pcg=0.8, factor=1.0, lambda_echo=-1, max_iter=400, min_iter=50, tol=1e-06, n_jobs=1, positive=False)[source]#

Bases: _BaseDeconvolution

Sparse hemodynamic deconvolution using LARS or FISTA.

This estimator implements Sparse Paradigm Free Mapping (SPFM) for deconvolution of fMRI data. It estimates activity-inducing signals (spike model) or innovation signals (block model) from BOLD timeseries.

The estimator supports two solving modes:

Univariate mode (group=0.0, default):: Each voxel is solved independently using pure L1 (LASSO) regularization. This is efficient and suitable when spatial structure is not important.
Multivariate mode (group > 0.0):: All voxels are solved jointly using L2,1 mixed-norm regularization, which encourages spatial grouping of activity across voxels at the same timepoint. This leverages spatial structure in 4D fMRI data. Requires a FISTA-compatible criterion (‘mad’, ‘factor’, etc.).

Parameters:

tr (float) – Repetition time (TR) of the fMRI acquisition in seconds.
te (list of float, default=None) – Echo times in milliseconds for multi-echo data. If None or [0], assumes single-echo data.
hrf_model (str, default=’spm’) – HRF model to use. Options are ‘spm’, ‘glover’, or a path to a custom HRF file (.1D or .txt).
block_model (bool, default=False) – If True, estimate innovation signals (block model). If False, estimate activity-inducing signals (spike model).
criterion (str, default=’bic’) – Criterion for lambda selection:
- ‘bic’, ‘aic’: Information criteria (LARS solver, univariate only).
- ‘mad’, ‘mad_update’, ‘ut’, ‘lut’, ‘factor’, ‘pcg’, ‘eigval’: Noise-based criteria (FISTA solver, supports multivariate).
debias (bool, default=True) – If True, perform debiasing step to recover true amplitude.
group (float, default=0.0) – Weight for spatial grouping using L2,1 mixed-norm regularization. Range [0, 1] where:
- group=0.0: Pure L1/LASSO (univariate, voxel-wise independent).
- group=1.0: Pure L2,1 (multivariate, maximum spatial grouping).
- 0 < group < 1: Elastic net-like mix of L1 and L2,1.
When group > 0, the solver operates on all voxels jointly (multivariate mode) and requires a FISTA-compatible criterion.
pcg (float, default=0.8) – Percentage of maximum lambda to use (for criterion=’pcg’).
factor (float, default=1.0) – Factor to multiply noise estimate for lambda selection.
max_iter (int, default=400) – Maximum number of iterations for the FISTA solver.
tol (float, default=1e-6) – Convergence tolerance.
n_jobs (int, default=1) – Number of parallel jobs. Only used in univariate mode (group=0). In multivariate mode, computation is inherently joint.
positive (bool, default=False) – If True, enforce non-negative coefficients.

Variables:

coef (ndarray of shape (n_timepoints, n_voxels)) – Estimated activity-inducing (spike) or innovation (block) signals.
lambda (ndarray of shape (n_voxels,) or float) – Selected regularization parameter. In multivariate mode, a single lambda is used for all voxels.
hrf_matrix (ndarray of shape (n_timepoints * n_echoes, n_timepoints)) – The HRF convolution matrix used for deconvolution.
n_features_in (int) – Number of voxels seen during fit.
n_iter (int) – Number of iterations run.

Examples

Univariate deconvolution (each voxel independent):

>>> from pySPFM import SparseDeconvolution
>>> import numpy as np
>>> X = np.random.randn(100, 50)  # 100 timepoints, 50 voxels
>>> model = SparseDeconvolution(tr=2.0, criterion='bic', group=0.0)
>>> model.fit(X)
SparseDeconvolution(criterion='bic', group=0.0, tr=2.0)

Multivariate deconvolution (joint spatial regularization):

>>> model = SparseDeconvolution(tr=2.0, criterion='factor', group=0.5)
>>> model.fit(X)  # All voxels solved jointly
SparseDeconvolution(criterion='factor', group=0.5, tr=2.0)

pySPFM.SparseDeconvolution

Contents

pySPFM.SparseDeconvolution#

`pySPFM`.SparseDeconvolution#