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).
- runs
numpy.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.
- detrend
bool
, default=True If detrending should be applied on timeseries (before confound removal).
- standardize
bool
, default=True If True, returned signals are set to unit variance.
- confounds
numpy.ndarray
,str
orlist
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_pass
float
orint
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_pass
float
orint
or None, default=None High cutoff frequency in Hertz. If specified, signals below this frequency will be filtered out.
- t_r
float
, 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_finite
bool
, 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.
- kwargs
dict
Keyword arguments to be passed to functions called within this function. Kwargs prefixed with
'clean__'
will be passed toclean
. Withinclean
, kwargs prefixed with'butterworth__'
will be passed to the Butterworth filter (i.e.,clean__butterworth__
).
- imgs4D image Niimg-like object or 2D
- Returns:
- Niimg-like object or
SurfaceImage
Input images, cleaned. Same shape as imgs.
- Niimg-like object or
See also
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