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.

nilearn.signal.clean

nilearn.signal.clean(signals, runs=None, detrend=True, standardize='zscore', sample_mask=None, confounds=None, standardize_confounds=True, filter='butterworth', low_pass=None, high_pass=None, t_r=2.5, ensure_finite=False, extrapolate=True, **kwargs)[source]

Improve SNR on masked fMRI signals.

This function can do several things on the input signals. With the default options, the procedures are performed in the following order:

  • detrend

  • low- and high-pass butterworth filter

  • remove confounds

  • standardize

Low-pass filtering improves specificity.

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

Butterworth filtering is only meaningful on evenly-sampled signals.

When performing scrubbing (censoring high-motion volumes) with butterworth filtering, the signal is processed in the following order, based on the second recommendation in Lindquist et al.[1]:

  • interpolate high motion volumes with cubic spline interpolation

  • detrend

  • low- and high-pass butterworth filter

  • censor high motion volumes

  • remove confounds

  • standardize

According to Lindquist et al.[1], removal of confounds will be done orthogonally to temporal filters (low- and/or high-pass filters), if both are specified. The censored volumes should be removed in both signals and confounds before the nuisance regression.

When performing scrubbing with cosine drift term filtering, the signal is processed in the following order, based on the first recommendation in Lindquist et al.[1]:

  • generate cosine drift term

  • censor high motion volumes in both signal and confounds

  • detrend

  • remove confounds

  • standardize

Parameters:
signalsnumpy.ndarray

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

runsnumpy.ndarray, default=None

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

confoundsnumpy.ndarray, str, pathlib.Path, pandas.DataFrame or list of confounds timeseries, default=None

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.

sample_maskNone, Any type compatible with numpy-array indexing, or list of shape: (number of scans - number of volumes removed, ) for explicit index, or (number of scans, ) for binary mask, default=None

Masks the niimgs along time/fourth dimension to perform scrubbing (remove volumes with high motion) and/or non-steady-state volumes. When passing binary mask with boolean values, True refers to volumes kept, and False for volumes removed. This masking step is applied before signal cleaning. When supplying run information, sample_mask must be a list containing sets of indexes for each run.

Added in version 0.8.0.

t_rfloat or None, default=None

Repetition time, in seconds (sampling period). Set to None if not provided. Default=2.5.

filter{‘butterworth’, ‘cosine’, False}, default=’butterworth’

Filtering methods:

  • ‘butterworth’: perform butterworth filtering.

  • ‘cosine’: generate discrete cosine transformation drift terms.

  • False: Do not perform filtering.

low_passfloat or None, default=None

Low cutoff frequency in Hertz. If specified, signals above this frequency will be filtered out. If None, no low-pass filtering will be performed.

Note

low_pass is not implemented for filter=’cosine’.

high_passfloat, default=None

High cutoff frequency in Hertz. If specified, signals below this frequency will be filtered out.

detrendbool, optional

Whether to detrend signals or not.

standardize{‘zscore_sample’, ‘zscore’, ‘psc’, True, False}, default=”zscore”

Strategy to standardize the signal:

  • ‘zscore_sample’: The signal is z-scored. Timeseries are shifted to zero mean and scaled to unit variance. Uses sample std.

  • ‘zscore’: The signal is z-scored. Timeseries are shifted to zero mean and scaled to unit variance. Uses population std by calling numpy.std with N - ddof=0.

  • ‘psc’: Timeseries are shifted to zero mean value and scaled to percent signal change (as compared to original mean signal).

  • True: The signal is z-scored (same as option zscore). Timeseries are shifted to zero mean and scaled to unit variance.

  • False: Do not standardize the data.

standardize_confoundsbool, default=True

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

ensure_finitebool, default=False

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

extrapolatebool, default=True

If True and filter=’butterworth’, censored volumes in both ends of the signal data will be interpolated before filtering. Otherwise, they will be discarded from the band-pass filtering process.

kwargsdict

Keyword arguments to be passed to functions called within clean. Kwargs prefixed with 'butterworth__' will be passed to butterworth.

Returns:
cleaned_signalsnumpy.ndarray

Input signals, cleaned. Same shape as signals unless sample_mask is applied.

See also

nilearn.image.clean_img

Notes

Confounds removal is based on a projection on the orthogonal of the signal space. See Friston et al.[2].

Orthogonalization between temporal filters and confound removal is based on suggestions in Lindquist et al.[1].

References