pySPFM.LowRankPlusSparse

pySPFM.LowRankPlusSparse#

class LowRankPlusSparse(*, tr, te=None, hrf_model='spm', block_model=False, criterion='mad_update', eigval_threshold=0.1, debias=True, group=0.0, factor=1.0, max_iter=100, min_iter=10, tol=1e-06, n_jobs=1)[source]#

Bases: _BaseDeconvolution

Low-rank plus sparse deconvolution (SPLORA).

This estimator implements the Sparse and Low-Rank Paradigm Free Mapping (SPLORA) algorithm, which separates fMRI data into low-rank (global/ structured) and sparse (transient neuronal) components.

Parameters:

  • tr (float) – Repetition time (TR) of the fMRI acquisition in seconds.

  • te (list of float, default=None) – Echo times in seconds 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=’mad_update’) – Criterion for lambda selection. Options: ‘mad’, ‘mad_update’, ‘ut’, ‘lut’, ‘factor’, ‘pcg’, ‘eigval’.

  • eigval_threshold (float, default=0.1) – Eigenvalue threshold for low-rank estimation. Eigenvalues below this fraction of the maximum are set to zero.

  • debias (bool, default=True) – If True, perform debiasing step to recover true amplitude.

  • group (float, default=0.0) – Weight for spatial grouping (L2,1-norm). Range [0, 1].

  • max_iter (int, default=100) – Maximum number of FISTA iterations.

  • n_jobs (int, default=1) – Number of parallel jobs for voxel-wise computation.

Variables:

  • coef (ndarray of shape (n_timepoints, n_voxels)) – Estimated sparse (neuronal) activity-inducing signals.

  • low_rank (ndarray of shape (n_timepoints, n_voxels)) – Estimated low-rank (global/structured) component.

  • lambda (ndarray of shape (n_voxels,)) – Selected regularization parameter for each voxel.

  • 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.

Examples

>>> from pySPFM import LowRankPlusSparse
>>> import numpy as np
>>> X = np.random.randn(100, 50)  # 100 timepoints, 50 voxels
>>> model = LowRankPlusSparse(tr=2.0)
>>> model.fit(X)
LowRankPlusSparse(tr=2.0)
>>> sparse_signal = model.coef_
>>> global_signal = model.low_rank_

See also

SparseDeconvolution

Standard sparse deconvolution without low-rank.

References

__repr__(N_CHAR_MAX=700)[source]#

Return a string representation of the estimator.

fit(X, y=None)[source]#

Fit the low-rank plus sparse deconvolution model.

Parameters:

  • X (array-like of shape (n_timepoints, n_voxels) or (n_timepoints * n_echoes, n_voxels)) – The fMRI timeseries data.

  • y (None) – Not used, present for API consistency.

Returns:

self (object) – Fitted estimator.

fit_transform(X, y=None, **fit_params)[source]#

Fit to data, then transform it.

Fits the estimator to X and y with optional parameters fit_params, and returns a transformed version of X.

Parameters:

  • X (array-like of shape (n_samples, n_features)) – Input samples.

  • y (array-like of shape (n_samples,) or (n_samples, n_outputs), default=None) – Target values (None for unsupervised transformations).

  • **fit_params (dict) – Additional fit parameters.

Returns:

X_new (ndarray of shape (n_samples, n_features_new)) – Transformed array.

get_fitted_signal()[source]#

Get the full fitted signal (low-rank + HRF*sparse).

Returns:

fitted (ndarray of shape (n_timepoints, n_voxels)) – The full reconstructed signal.

get_params(deep=True)[source]#

Get parameters for this estimator.

Parameters:

deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

params (dict) – Parameter names mapped to their values.

get_residuals(X)[source]#

Get the residuals after deconvolution.

Parameters:

X (array-like of shape (n_timepoints, n_voxels)) – The original fMRI data.

Returns:

residuals (ndarray of shape (n_timepoints, n_voxels)) – The residuals (X - fitted_signal).

score(X, y=None)[source]#

Return the explained variance ratio of the deconvolution.

The score is computed as \(R^2 = 1 - SS_{res} / SS_{tot}\), where \(SS_{res}\) is the residual sum of squares and \(SS_{tot}\) is the total sum of squares.

Parameters:

  • X (array-like of shape (n_timepoints, n_voxels)) – Test samples (fMRI timeseries).

  • y (None) – Not used, present for API consistency.

Returns:

score (float) – Explained variance ratio averaged across voxels.

set_params(**params)[source]#

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects. The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**params (dict) – Estimator parameters.

Returns:

self (estimator instance) – Estimator instance.

transform(X)[source]#

Apply deconvolution to the data.

For most deconvolution methods, transform returns the stored coefficients from fit, as the deconvolution is data-specific.

Parameters:

X (array-like of shape (n_timepoints, n_voxels)) – The fMRI timeseries data.

Returns:

coef (ndarray of shape (n_timepoints, n_voxels)) – The deconvolved activity-inducing or innovation signals.

Contents