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.image.clean_img#
- nilearn.image.clean_img(imgs, runs=None, detrend=True, standardize=True, confounds=None, low_pass=None, high_pass=None, t_r=None, ensure_finite=False, mask_img=None)[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 Lindquist et al. (2018), removal of confounds will be done orthogonally to temporal filters (low- and/or high-pass filters), if both are specified.
New in version 0.2.5.
- Parameters
- imgsNiimg-like object
4D image. The signals in the last dimension are filtered (see http://nilearn.github.io/manipulating_images/input_output.html for a detailed description of the valid input types).
- 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.
Warning
‘runs’ replaces ‘sessions’ after release 0.10.0. Using ‘session’ will result in an error after release 0.10.0.
Default=``None``.
- detrend
bool, optional If detrending should be applied on timeseries (before confound removal). Default=True.
- standardize
bool, optional If True, returned signals are set to unit variance. Default=True.
- confounds
numpy.ndarray,strorlistof Confounds timeseries. optional 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.
- low_pass
float, optional Low cutoff frequencies, in Hertz.
- high_pass
float, optional High cutoff frequencies, in Hertz.
- t_r
float, optional Repetition time, in second (sampling period). Set to None if not specified. Mandatory if used together with low_pass or high_pass.
- ensure_finite
bool, optional If True, the non-finite values (NaNs and infs) found in the images will be replaced by zeros. Default=False.
- mask_imgNiimg-like object, optional
If provided, signal is only cleaned from voxels inside the mask. If mask is provided, it should have same shape and affine as imgs. If not provided, all voxels are used. See http://nilearn.github.io/manipulating_images/input_output.html.
- Returns
- Niimg-like object
Input images, cleaned. Same shape as imgs.
See also
Notes
Confounds removal is based on a projection on the orthogonal of the signal space [1].
Orthogonalization between temporal filters and confound removal is based on suggestions in [2].
References
- 1
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.
- 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.
