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.

8.8.1. nilearn.masking.compute_epi_mask

nilearn.masking.compute_epi_mask(epi_img, lower_cutoff=0.2, upper_cutoff=0.85, connected=True, opening=2, exclude_zeros=False, ensure_finite=True, target_affine=None, target_shape=None, memory=None, verbose=0)

Compute a brain mask from fMRI data in 3D or 4D numpy.ndarray.

This is based on an heuristic proposed by T.Nichols: find the least dense point of the histogram, between fractions lower_cutoff and upper_cutoff of the total image histogram.

Note

In case of failure, it is usually advisable to increase lower_cutoff.

Parameters

epi_imgNiimg-like object

See https://nilearn.github.io/stable/manipulating_images/input_output.html # noqa:E501 EPI image, used to compute the mask. 3D and 4D images are accepted.

Note

If a 3D image is given, we suggest to use the mean image.

lower_cutofffloat, optional

Lower fraction of the histogram to be discarded. Default=0.2.

upper_cutofffloat, optional

Upper fraction of the histogram to be discarded. Default=0.85.

connectedbool, optional

If connected is True, only the largest connect component is kept. Default=True.

openingbool or int, optional

This parameter determines whether a morphological opening is performed, to keep only large structures. This step is useful to remove parts of the skull that might have been included. opening can be:

• A boolean : If False, no opening is performed. If True, it is equivalent to opening=1.

• An integer n: The opening is performed via n erosions (see scipy.ndimage.binary_erosion). The largest connected component is then estimated if connected is set to True, and 2`n` dilation operations are performed (see scipy.ndimage.binary_dilation) followed by n erosions. This corresponds to 1 opening operation of order n followed by a closing operator of order n.

Note

Turning off opening (opening=False) will also prevent any smoothing applied to the image during the mask computation.

Default=2.

ensure_finitebool

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

exclude_zerosbool, optional

Consider zeros as missing values for the computation of the threshold. This option is useful if the images have been resliced with a large padding of zeros. Default=False.

target_affinenumpy.ndarray, optional.

If specified, the image is resampled corresponding to this new affine. target_affine can be a 3x3 or a 4x4 matrix. Default=None.

Note

This parameter is passed to nilearn.image.resample_img.

target_shapetuple or list, optional.

If specified, the image will be resized to match this new shape. len(target_shape) must be equal to 3.

Note

If target_shape is specified, a target_affine of shape (4, 4) must also be given.

Default=None.

Note

This parameter is passed to nilearn.image.resample_img.

memoryinstance of joblib.Memory or str

Used to cache the masking process. By default, no caching is done. If a str is given, it is the path to the caching directory.

verboseint, optional

Verbosity level (0 means no message). Default=0.

Returns

masknibabel.nifti1.Nifti1Image

The brain mask (3D image).

8.8.1.1. Examples using nilearn.masking.compute_epi_mask

NeuroImaging volumes visualization

Visualizing global patterns with a carpet plot

Predicted time series and residuals

Understanding NiftiMasker and mask computation