Understanding NiftiMasker and mask computation

In this example, the Nifti masker is used to automatically compute a mask.

• The default strategy is based on the background.

• Another option is to use a template.

• For raw EPI, as in resting-state or movie watching time series, we need to use the ‘epi’ strategy of the NiftiMasker.

In addition, we show here how to tweak the different parameters of the underlying routine that extract masks from EPI compute_epi_mask.

Warning

If you are using Nilearn with a version older than 0.9.0, then you should either upgrade your version or import maskers from the input_data module instead of the maskers module.

That is, you should manually replace in the following example all occurrences of:

from nilearn.maskers import NiftiMasker

with:

from nilearn.input_data import NiftiMasker

Computing a mask from the background

The default strategy to compute a mask, eg in NiftiMasker is to try to detect the background.

With data that has already been masked, this will work well, as it lies on a homogeneous background

from nilearn import image
from nilearn.datasets import fetch_development_fmri, fetch_miyawaki2008
from nilearn.maskers import NiftiMasker
from nilearn.plotting import plot_epi, plot_roi, show

miyawaki_dataset = fetch_miyawaki2008()

# print basic information on the dataset
print(
    "First functional nifti image (4D) is located "
    f"at: {miyawaki_dataset.func[0]}"
)

miyawaki_filename = miyawaki_dataset.func[0]
miyawaki_mean_img = image.mean_img(miyawaki_filename)
plot_epi(miyawaki_mean_img, title="Mean EPI image")

[fetch_miyawaki2008] Dataset found in /home/runner/nilearn_data/miyawaki2008
First functional nifti image (4D) is located at: /home/runner/nilearn_data/miyawaki2008/func/data_figure_run01.nii.gz

<nilearn.plotting.displays._slicers.OrthoSlicer object at 0x7f307915ffa0>

A NiftiMasker with the default strategy

masker = NiftiMasker(verbose=1)
masker.fit(miyawaki_filename)

# Plot the generated mask using the mask_img_ attribute
plot_roi(
    masker.mask_img_, miyawaki_mean_img, title="Mask from already masked data"
)

[NiftiMasker.fit] Loading data from
'/home/runner/nilearn_data/miyawaki2008/func/data_figure_run01.nii.gz'
[NiftiMasker.fit] Computing mask
[NiftiMasker.fit] Resampling mask
[NiftiMasker.fit] Finished fit

<nilearn.plotting.displays._slicers.OrthoSlicer object at 0x7f3079bdd000>

Plot the generated mask using the .generate_report method

report = masker.generate_report()
report

NiftiMasker Applying a mask to extract time-series from Niimg-like objects. NiftiMasker is useful when preprocessing (detrending, standardization, resampling, etc.) of in-mask :term:`voxels` is necessary. Use case: working with time series of :term:`resting-state` or task maps.

This report shows the input Nifti image overlaid with the outlines of the mask (in green). We recommend to inspect the report for the overlap between the mask and its input image.

The mask includes 5438 voxels (4.4 %) of the image.

	Value
Parameter
cmap	gray
detrend	False
high_variance_confounds	False
mask_strategy	background
memory_level	1
reports	True
standardize	False
standardize_confounds	True
verbose	1

This report was generated based on information provided at instantiation and fit time. Note that the masker can potentially perform resampling at transform time.

Computing a mask from raw EPI data

From raw EPI data, there is no uniform background, and a different strategy is necessary

# Load movie watching based brain development fMRI dataset
dataset = fetch_development_fmri(n_subjects=1)
epi_filename = dataset.func[0]

# Restrict to 100 frames to speed up computation
from nilearn.image import index_img

epi_img = index_img(epi_filename, slice(0, 100))

# To display the background
mean_img = image.mean_img(epi_img)
plot_epi(mean_img, title="Mean EPI image")

[fetch_development_fmri] Dataset found in
/home/runner/nilearn_data/development_fmri
[fetch_development_fmri] Dataset found in
/home/runner/nilearn_data/development_fmri/development_fmri
[fetch_development_fmri] Dataset found in
/home/runner/nilearn_data/development_fmri/development_fmri

<nilearn.plotting.displays._slicers.OrthoSlicer object at 0x7f30c4e93fa0>

Simple mask extraction from EPI images We need to specify an ‘epi’ mask_strategy, as this is raw EPI data

masker = NiftiMasker(mask_strategy="epi", verbose=1)
masker.fit(epi_img)
report = masker.generate_report()
report

[NiftiMasker.fit] Loading data from <nibabel.nifti1.Nifti1Image object at
0x7f30a1267760>
[NiftiMasker.fit] Computing mask
[NiftiMasker.fit] Resampling mask
[NiftiMasker.fit] Finished fit

NiftiMasker Applying a mask to extract time-series from Niimg-like objects. NiftiMasker is useful when preprocessing (detrending, standardization, resampling, etc.) of in-mask :term:`voxels` is necessary. Use case: working with time series of :term:`resting-state` or task maps.

This report shows the input Nifti image overlaid with the outlines of the mask (in green). We recommend to inspect the report for the overlap between the mask and its input image.

The mask includes 24428 voxels (16.6 %) of the image.

	Value
Parameter
cmap	gray
detrend	False
high_variance_confounds	False
mask_strategy	epi
memory_level	1
reports	True
standardize	False
standardize_confounds	True
verbose	1

This report was generated based on information provided at instantiation and fit time. Note that the masker can potentially perform resampling at transform time.

Generate mask with strong opening

We can fine-tune the outline of the mask by increasing the number of opening steps (opening=10) using the mask_args argument of the NiftiMasker. This effectively performs erosion and dilation operations on the outer voxel layers of the mask, which can for example remove remaining skull parts in the image.

masker = NiftiMasker(mask_strategy="epi", mask_args={"opening": 10}, verbose=1)
masker.fit(epi_img)
report = masker.generate_report()
report

[NiftiMasker.fit] Loading data from <nibabel.nifti1.Nifti1Image object at
0x7f30a1267760>
[NiftiMasker.fit] Computing mask
[NiftiMasker.fit] Resampling mask
[NiftiMasker.fit] Finished fit

NiftiMasker Applying a mask to extract time-series from Niimg-like objects. NiftiMasker is useful when preprocessing (detrending, standardization, resampling, etc.) of in-mask :term:`voxels` is necessary. Use case: working with time series of :term:`resting-state` or task maps.

This report shows the input Nifti image overlaid with the outlines of the mask (in green). We recommend to inspect the report for the overlap between the mask and its input image.

The mask includes 11617 voxels (7.9 %) of the image.

	Value
Parameter
cmap	gray
detrend	False
high_variance_confounds	False
mask_args	{'opening': 10}
mask_strategy	epi
memory_level	1
reports	True
standardize	False
standardize_confounds	True
verbose	1

This report was generated based on information provided at instantiation and fit time. Note that the masker can potentially perform resampling at transform time.

Generate mask with a high lower cutoff

The NiftiMasker calls the nilearn.masking.compute_epi_mask function to compute the mask from the EPI. It has two important parameters: lower_cutoff and upper_cutoff. These set the grey-value bounds in which the masking algorithm will search for its threshold (0 being the minimum of the image and 1 the maximum). We will here increase the lower cutoff to enforce selection of those voxels that appear as bright in the EPI image.

masker = NiftiMasker(
    mask_strategy="epi",
    mask_args={"upper_cutoff": 0.9, "lower_cutoff": 0.8, "opening": False},
    verbose=1,
)
masker.fit(epi_img)
report = masker.generate_report()
report

[NiftiMasker.fit] Loading data from <nibabel.nifti1.Nifti1Image object at
0x7f30a1267760>
[NiftiMasker.fit] Computing mask
[NiftiMasker.fit] Resampling mask
[NiftiMasker.fit] Finished fit

NiftiMasker Applying a mask to extract time-series from Niimg-like objects. NiftiMasker is useful when preprocessing (detrending, standardization, resampling, etc.) of in-mask :term:`voxels` is necessary. Use case: working with time series of :term:`resting-state` or task maps.

This report shows the input Nifti image overlaid with the outlines of the mask (in green). We recommend to inspect the report for the overlap between the mask and its input image.

The mask includes 24809 voxels (16.8 %) of the image.

	Value
Parameter
cmap	gray
detrend	False
high_variance_confounds	False
mask_args	{'upper_cutoff': 0.9, 'lower_cutoff': 0.8, 'opening': False}
mask_strategy	epi
memory_level	1
reports	True
standardize	False
standardize_confounds	True
verbose	1

This report was generated based on information provided at instantiation and fit time. Note that the masker can potentially perform resampling at transform time.

Computing the mask from the MNI template

A mask can also be computed from the MNI template. In this case, it is resampled to the target image. Three options are available: ‘whole-brain-template’, ‘gm-template’, and ‘wm-template’ depending on whether the whole-brain, gray matter, or white matter template should be used.

masker = NiftiMasker(mask_strategy="whole-brain-template", verbose=1)
masker.fit(epi_img)
report = masker.generate_report()
report

[NiftiMasker.fit] Loading data from <nibabel.nifti1.Nifti1Image object at
0x7f30a1267760>
[NiftiMasker.fit] Computing mask
[NiftiMasker.fit] Resampling mask
[NiftiMasker.fit] Finished fit

NiftiMasker Applying a mask to extract time-series from Niimg-like objects. NiftiMasker is useful when preprocessing (detrending, standardization, resampling, etc.) of in-mask :term:`voxels` is necessary. Use case: working with time series of :term:`resting-state` or task maps.

This report shows the input Nifti image overlaid with the outlines of the mask (in green). We recommend to inspect the report for the overlap between the mask and its input image.

The mask includes 21781 voxels (14.8 %) of the image.

	Value
Parameter
cmap	gray
detrend	False
high_variance_confounds	False
mask_strategy	whole-brain-template
memory_level	1
reports	True
standardize	False
standardize_confounds	True
verbose	1

This report was generated based on information provided at instantiation and fit time. Note that the masker can potentially perform resampling at transform time.

Compute and resample a mask

NiftiMasker also allows passing parameters directly to image.resample_img. We can specify a target_affine, a target_shape, or both. For more information on these arguments, see Visualization of affine resamplings.

The NiftiMasker report allows us to see the mask before and after resampling. Simply hover over the report to see the mask from the original image.

import numpy as np

masker = NiftiMasker(
    mask_strategy="epi", target_affine=np.eye(3) * 8, verbose=1
)
masker.fit(epi_img)
report = masker.generate_report()
report

[NiftiMasker.fit] Loading data from <nibabel.nifti1.Nifti1Image object at
0x7f30a1267760>
[NiftiMasker.fit] Computing mask
[NiftiMasker.fit] Resampling mask
[NiftiMasker.fit] Finished fit

NiftiMasker Applying a mask to extract time-series from Niimg-like objects. NiftiMasker is useful when preprocessing (detrending, standardization, resampling, etc.) of in-mask :term:`voxels` is necessary. Use case: working with time series of :term:`resting-state` or task maps.

This report shows the input Nifti image overlaid with the outlines of the mask (in green). We recommend to inspect the report for the overlap between the mask and its input image. To see the input Nifti image before resampling, hover over the displayed image.

The mask includes 3040 voxels (15.0 %) of the image.

	Value
Parameter
cmap	gray
detrend	False
high_variance_confounds	False
mask_strategy	epi
memory_level	1
reports	True
standardize	False
standardize_confounds	True
target_affine	[[8.0, 0.0, 0.0], [0.0, 8.0, 0.0], [0.0, 0.0, 8.0]]
verbose	1

This report was generated based on information provided at instantiation and fit time. Note that the masker can potentially perform resampling at transform time.

After mask computation: extracting time series

Extract time series

# trended vs detrended
trended = NiftiMasker(mask_strategy="epi", verbose=1)
detrended = NiftiMasker(mask_strategy="epi", detrend=True, verbose=1)
trended_data = trended.fit_transform(epi_img)
detrended_data = detrended.fit_transform(epi_img)

# The timeseries are numpy arrays, so we can manipulate them with numpy

print(
    f"Trended: mean {np.mean(trended_data):.2f}, "
    f"std {np.std(trended_data):.2f}"
)
print(
    f"Detrended: mean {np.mean(detrended_data):.2f}, "
    f"std {np.std(detrended_data):.2f}"
)

show()

[NiftiMasker.wrapped] Loading data from <nibabel.nifti1.Nifti1Image object at
0x7f30a1267760>
[NiftiMasker.wrapped] Computing mask
[NiftiMasker.wrapped] Resampling mask
[NiftiMasker.wrapped] Finished fit
[NiftiMasker.wrapped] Loading data from <nibabel.nifti1.Nifti1Image object at
0x7f30a1267760>
[NiftiMasker.wrapped] Extracting region signals
[NiftiMasker.wrapped] Cleaning extracted signals
[NiftiMasker.wrapped] Loading data from <nibabel.nifti1.Nifti1Image object at
0x7f30a1267760>
[NiftiMasker.wrapped] Computing mask
[NiftiMasker.wrapped] Resampling mask
[NiftiMasker.wrapped] Finished fit
[NiftiMasker.wrapped] Loading data from <nibabel.nifti1.Nifti1Image object at
0x7f30a1267760>
[NiftiMasker.wrapped] Extracting region signals
[NiftiMasker.wrapped] Cleaning extracted signals
Trended: mean 552.82, std 168.28
Detrended: mean -0.00, std 5.88

Estimated memory usage: 513 MB