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.masking.compute_multi_epi_mask¶

nilearn.masking.compute_multi_epi_mask(epi_imgs, lower_cutoff=0.2, upper_cutoff=0.85, connected=True, opening=2, threshold=0.5, target_affine=None, target_shape=None, exclude_zeros=False, n_jobs=1, memory=None, verbose=0)[source]¶

Compute a common mask for several runs or subjects of fMRI data.

Uses the mask-finding algorithms to extract masks for each run or subject, and then keep only the main connected component of the a given fraction of the intersection of all the masks.

Parameters:

epi_imgslist of Niimg-like objects

See Input and output: neuroimaging data representation. A list of arrays, each item being a subject or a run. 3D and 4D images are accepted.

Note

If 3D images are given, we suggest to use the mean image of each run.

thresholdfloat, default=0.5

The inter-run threshold: the fraction of the total number of runs in for which a voxel must be in the mask to be kept in the common mask. threshold=1 corresponds to keeping the intersection of all masks, whereas threshold=0 is the union of all masks.

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 bool : If False, no opening is performed. If True, it is equivalent to opening=1.
An int 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.

exclude_zerosbool, default=False

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.

target_affine3x3 or a 4x4 array-like, or None, default=None

If specified, the image is resampled corresponding to this new affine.

Note

This parameter is passed to nilearn.image.resample_img.

target_shapetuple or list or None, default=None

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.

Note

This parameter is passed to nilearn.image.resample_img.

memoryNone, instance of joblib.Memory, str, or pathlib.Path

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.

n_jobsint, default=1

The number of CPUs to use to do the computation. -1 means ‘all CPUs’.

verboseint, default=0

Verbosity level (0 means no message).

Returns:

mask3D nibabel.nifti1.Nifti1Image: The brain mask.