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.12.2. 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)[source]¶
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 1, 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.
- runs
numpy.ndarray
, optional Add a run level to the cleaning process. Each run will be cleaned independently. Must be a 1D array of n_samples elements. Default is None.
- confounds
numpy.ndarray
,str
,pandas.DataFrame
orlist
of Confounds timeseries. Shape must be (instant number, confound number), or just (instant number,) The number of time instants in
signals
andconfounds
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. Default is None.- sample_maskNone,
numpy.ndarray
,list
,tuple
, orlist
of shape: (number of scans - number of volumes removed, ) Masks the niimgs along time/fourth dimension to perform scrubbing (remove volumes with high motion) and/or non-steady-state volumes. 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.
New in version 0.8.0.
Default is None.
- t_r
float
or None, optional Repetition time, in seconds (sampling period). Set to
None
if not provided. Default=None. Default=2.5.- filter{‘butterworth’, ‘cosine’, False}, optional
Filtering methods:
‘butterworth’: perform butterworth filtering.
‘cosine’: generate discrete cosine transformation drift terms.
False: Do not perform filtering.
Default=’butterworth’.
- low_pass
float
or None, optional Low cutoff frequency in Hertz. If specified, signals above this frequency will be filtered out. If None, no low-pass filtering will be performed. Default=None.
Note
low_pass is not implemented for filter=’cosine’.
- high_pass
float
, optional High cutoff frequency in Hertz. If specified, signals below this frequency will be filtered out. Default=None.
- detrend
bool
, optional Whether to detrend signals or not.
- standardize{‘zscore’, ‘psc’, False}, optional
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).
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.
Default=”zscore”.
- standardize_confounds
bool
, optional If set to True, the confounds are z-scored: their mean is put to 0 and their variance to 1 in the time dimension. Default=True.
- ensure_finite
bool
, optional If True, the non-finite values (NANs and infs) found in the data will be replaced by zeros. Default=False.
- signals
- Returns
- cleaned_signals
numpy.ndarray
Input signals, cleaned. Same shape as signals.
- cleaned_signals
See also
Notes
Confounds removal is based on a projection on the orthogonal of the signal space. See 2.
Orthogonalization between temporal filters and confound removal is based on suggestions in 1.
References
- 1(1,2)
Martin A. Lindquist, Stephan Geuter, Tor D. Wager, and Brian S. Caffo. Modular preprocessing pipelines can reintroduce artifacts into fmri data. bioRxiv, 2018. URL: https://www.biorxiv.org/content/early/2018/09/04/407676, arXiv:https://www.biorxiv.org/content/early/2018/09/04/407676.full.pdf, doi:10.1101/407676.
- 2
K. J. Friston, A. P. Holmes, K. J. Worsley, J.-P. Poline, C. D. Frith, and R. S. J. Frackowiak. Statistical parametric maps in functional imaging: a general linear approach. Human Brain Mapping, 2(4):189–210, 1994. URL: https://onlinelibrary.wiley.com/doi/abs/10.1002/hbm.460020402, arXiv:https://onlinelibrary.wiley.com/doi/pdf/10.1002/hbm.460020402, doi:https://doi.org/10.1002/hbm.460020402.