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.

7.5.1. nilearn.image.clean_img

nilearn.image.clean_img(imgs, sessions=None, detrend=True, standardize=True, confounds=None, low_pass=None, high_pass=None, t_r=2.5, ensure_finite=False)

Improve SNR on masked fMRI signals.

This function can do several things on the input signals, in the following order:

  • detrend
  • standardize
  • remove confounds
  • low- and high-pass filter

Low-pass filtering improves specificity.

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

Filtering is only meaningful on evenly-sampled signals.

New in version 0.2.5.

Parameters:

imgs: Niimg-like object

See http://nilearn.github.io/manipulating_images/input_output.html 4D image. The signals in the last dimension are filtered.

sessions : numpy array, optional

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

detrend: bool

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

standardize: bool

If True, returned signals are set to unit variance.

confounds: numpy.ndarray, str or list of

Confounds timeseries. 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, high_pass: float

Respectively low and high cutoff frequencies, in Hertz.

t_r: float, optional

Repetition time, in second (sampling period).

ensure_finite: bool, optional

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

Returns:

cleaned_img: Niimg-like object

Input images, cleaned. Same shape as imgs.

Notes

Confounds removal is based on a projection on the orthogonal of the signal space. See Friston, K. J., A. P. Holmes, K. J. Worsley, J.-P. Poline, C. D. Frith, et R. S. J. Frackowiak. “Statistical Parametric Maps in Functional Imaging: A General Linear Approach”. Human Brain Mapping 2, no 4 (1994): 189-210.