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.

Examples using `nilearn.image.clean_img`¶

Predicted time series and residuals

nilearn.image.clean_img¶

Examples using nilearn.image.clean_img¶

Examples using `nilearn.image.clean_img`¶