Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.

8.11.1. nilearn.signal.clean

nilearn.signal.clean(signals, sessions=None, detrend=True, standardize='zscore', confounds=None, standardize_confounds=True, low_pass=None, high_pass=None, t_r=2.5, ensure_finite=False)

Improve SNR on masked fMRI signals.

This function can do several things on the input signals, in the following order:

  • detrend

  • low- and high-pass filter

  • remove confounds

  • standardize

Low-pass filtering improves specificity.

High-pass filtering should be kept small, to keep some sensitivity.

Filtering is only meaningful on evenly-sampled signals.

According to Lindquist et al. (2018), removal of confounds will be done orthogonally to temporal filters (low- and/or high-pass filters), if both are specified.

Parameters
signals: numpy.ndarray

Timeseries. Must have shape (instant number, features number). This array is not modified.

sessionsnumpy array, optional

Add a session level to the cleaning process. Each session will be cleaned independently. Must be a 1D array of n_samples elements.

confounds: numpy.ndarray, str, DataFrame or list of

Confounds timeseries. Shape must be (instant number, confound number), or just (instant number,) The number of time instants in signals and confounds must be identical (i.e. signals.shape[0] == confounds.shape[0]). If a string is provided, it is assumed to be the name of a csv file containing signals as columns, with an optional one-line header. If a list is provided, all confounds are removed from the input signal, as if all were in the same array.

t_r: float

Repetition time, in second (sampling period). Set to None if not.

low_pass, high_pass: float

Respectively high and low cutoff frequencies, in Hertz.

detrend: bool

If detrending should be applied on timeseries (before confound removal)

standardize: {‘zscore’, ‘psc’, False}, default is ‘zscore’

Strategy to standardize the signal. ‘zscore’: the signal is z-scored. Timeseries are shifted to zero mean and scaled to unit variance. ‘psc’: Timeseries are shifted to zero mean value and scaled to percent signal change (as compared to original mean signal). False : Do not standardize the data.

standardize_confounds: boolean, optional, default is True

If standardize_confounds is True, the confounds are z-scored: their mean is put to 0 and their variance to 1 in the time dimension.

ensure_finite: bool

If True, the non-finite values (NANs and infs) found in the data will be replaced by zeros.

Returns
cleaned_signals: numpy.ndarray

Input signals, cleaned. Same shape as signals.

Notes

Confounds removal is based on a projection on the orthogonal of the signal space. See Friston, K. J., A. P. Holmes, K. J. Worsley, J.-P. Poline, C. D. Frith, et R. S. J. Frackowiak. “Statistical Parametric Maps in Functional Imaging: A General Linear Approach”. Human Brain Mapping 2, no 4 (1994): 189-210.

Orthogonalization between temporal filters and confound removal is based on suggestions in Lindquist, M., Geuter, S., Wager, T., & Caffo, B. (2018). Modular preprocessing pipelines can reintroduce artifacts into fMRI data. bioRxiv, 407676.