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, **kwargs)[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.

Added in version 0.2.5.

Parameters:
imgs4D image Niimg-like object or 2D SurfaceImage

The signals in the last dimension are filtered (see Input and output: neuroimaging data representation for a detailed description of the valid input types).

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.

Warning

‘runs’ replaces ‘sessions’ after release 0.10.0. Using ‘session’ will result in an error after release 0.10.0.

detrendbool, default=True

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

standardizebool, default=True

If True, returned signals are set to unit variance.

confoundsnumpy.ndarray, str 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.

low_passfloat or int 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.

high_passfloat or int or None, default=None

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

t_rfloat, default=None

Repetition time, in second (sampling period). Set to None if not specified. Mandatory if used together with low_pass or high_pass.

ensure_finitebool, default=False

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

mask_imgNiimg-like object or SurfaceImage, default=None

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 / verrices are used. See Input and output: neuroimaging data representation.

kwargsdict

Keyword arguments to be passed to functions called within this function. Kwargs prefixed with 'clean__' will be passed to clean. Within clean, kwargs prefixed with 'butterworth__' will be passed to the Butterworth filter (i.e., clean__butterworth__).

Returns:
Niimg-like object or SurfaceImage

Input images, cleaned. Same shape as imgs.

Notes

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

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

References

Examples using nilearn.image.clean_img

Predicted time series and residuals

Predicted time series and residuals