.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_examples/06_manipulating_images/plot_mask_computation.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code or to run this example in your browser via Binder .. rst-class:: sphx-glr-example-title .. _sphx_glr_auto_examples_06_manipulating_images_plot_mask_computation.py: 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 :term:`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 :func:`nilearn.masking.compute_epi_mask`. .. include:: ../../../examples/masker_note.rst .. GENERATED FROM PYTHON SOURCE LINES 23-31 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 .. GENERATED FROM PYTHON SOURCE LINES 31-47 .. code-block:: Python import nilearn.image as image from nilearn import datasets from nilearn.maskers import NiftiMasker from nilearn.plotting import plot_epi, plot_roi, show miyawaki_dataset = datasets.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") .. image-sg:: /auto_examples/06_manipulating_images/images/sphx_glr_plot_mask_computation_001.png :alt: plot mask computation :srcset: /auto_examples/06_manipulating_images/images/sphx_glr_plot_mask_computation_001.png :class: sphx-glr-single-img .. rst-class:: sphx-glr-script-out .. code-block:: none First functional nifti image (4D) is located at: /home/himanshu/nilearn_data/miyawaki2008/func/data_figure_run01.nii.gz .. GENERATED FROM PYTHON SOURCE LINES 48-49 A NiftiMasker with the default strategy .. GENERATED FROM PYTHON SOURCE LINES 49-57 .. code-block:: Python masker = NiftiMasker() 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" ) .. image-sg:: /auto_examples/06_manipulating_images/images/sphx_glr_plot_mask_computation_002.png :alt: plot mask computation :srcset: /auto_examples/06_manipulating_images/images/sphx_glr_plot_mask_computation_002.png :class: sphx-glr-single-img .. rst-class:: sphx-glr-script-out .. code-block:: none .. GENERATED FROM PYTHON SOURCE LINES 58-59 Plot the generated mask using the .generate_report method .. GENERATED FROM PYTHON SOURCE LINES 59-63 .. code-block:: Python report = masker.generate_report() report .. raw:: html

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<voxel>` is necessary. Use case: working with time series of :term:`resting-state` or task maps.

image

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.

Parameters
Parameter Value
detrend False
dtype None
high_pass None
high_variance_confounds False
low_pass None
mask_args None
mask_img None
mask_strategy background
memory Memory(location=None)
memory_level 1
reports True
runs None
smoothing_fwhm None
standardize False
standardize_confounds True
t_r None
target_affine None
target_shape None
verbose 0


.. GENERATED FROM PYTHON SOURCE LINES 64-69 Computing a mask from raw :term:`EPI` data ------------------------------------------ From raw :term:`EPI` data, there is no uniform background, and a different strategy is necessary .. GENERATED FROM PYTHON SOURCE LINES 69-83 .. code-block:: Python # Load movie watching based brain development fMRI dataset dataset = datasets.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") .. image-sg:: /auto_examples/06_manipulating_images/images/sphx_glr_plot_mask_computation_003.png :alt: plot mask computation :srcset: /auto_examples/06_manipulating_images/images/sphx_glr_plot_mask_computation_003.png :class: sphx-glr-single-img .. rst-class:: sphx-glr-script-out .. code-block:: none .. GENERATED FROM PYTHON SOURCE LINES 84-86 Simple mask extraction from :term:`EPI` images We need to specify an 'epi' mask_strategy, as this is raw :term:`EPI` data .. GENERATED FROM PYTHON SOURCE LINES 86-91 .. code-block:: Python masker = NiftiMasker(mask_strategy="epi") masker.fit(epi_img) report = masker.generate_report() report .. raw:: html

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<voxel>` is necessary. Use case: working with time series of :term:`resting-state` or task maps.

image

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.

Parameters
Parameter Value
detrend False
dtype None
high_pass None
high_variance_confounds False
low_pass None
mask_args None
mask_img None
mask_strategy epi
memory Memory(location=None)
memory_level 1
reports True
runs None
smoothing_fwhm None
standardize False
standardize_confounds True
t_r None
target_affine None
target_shape None
verbose 0


.. GENERATED FROM PYTHON SOURCE LINES 92-101 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 :term:`erosion` and :term:`dilation` operations on the outer voxel layers of the mask, which can for example remove remaining skull parts in the image. .. GENERATED FROM PYTHON SOURCE LINES 101-106 .. code-block:: Python masker = NiftiMasker(mask_strategy="epi", mask_args=dict(opening=10)) masker.fit(epi_img) report = masker.generate_report() report .. raw:: html

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<voxel>` is necessary. Use case: working with time series of :term:`resting-state` or task maps.

image

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.

Parameters
Parameter Value
detrend False
dtype None
high_pass None
high_variance_confounds False
low_pass None
mask_args {'opening': 10}
mask_img None
mask_strategy epi
memory Memory(location=None)
memory_level 1
reports True
runs None
smoothing_fwhm None
standardize False
standardize_confounds True
t_r None
target_affine None
target_shape None
verbose 0


.. GENERATED FROM PYTHON SOURCE LINES 107-116 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 :term:`EPI` image. .. GENERATED FROM PYTHON SOURCE LINES 116-125 .. code-block:: Python masker = NiftiMasker( mask_strategy="epi", mask_args=dict(upper_cutoff=0.9, lower_cutoff=0.8, opening=False), ) masker.fit(epi_img) report = masker.generate_report() report .. raw:: html

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<voxel>` is necessary. Use case: working with time series of :term:`resting-state` or task maps.

image

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.

Parameters
Parameter Value
detrend False
dtype None
high_pass None
high_variance_confounds False
low_pass None
mask_args {'upper_cutoff': 0.9, 'lower_cutoff': 0.8, 'opening': False}
mask_img None
mask_strategy epi
memory Memory(location=None)
memory_level 1
reports True
runs None
smoothing_fwhm None
standardize False
standardize_confounds True
t_r None
target_affine None
target_shape None
verbose 0


.. GENERATED FROM PYTHON SOURCE LINES 126-134 Computing the mask from the :term:`MNI` template ------------------------------------------------ A mask can also be computed from the :term:`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. .. GENERATED FROM PYTHON SOURCE LINES 134-140 .. code-block:: Python masker = NiftiMasker(mask_strategy="whole-brain-template") masker.fit(epi_img) report = masker.generate_report() report .. raw:: html

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<voxel>` is necessary. Use case: working with time series of :term:`resting-state` or task maps.

image

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.

Parameters
Parameter Value
detrend False
dtype None
high_pass None
high_variance_confounds False
low_pass None
mask_args None
mask_img None
mask_strategy whole-brain-template
memory Memory(location=None)
memory_level 1
reports True
runs None
smoothing_fwhm None
standardize False
standardize_confounds True
t_r None
target_affine None
target_shape None
verbose 0


.. GENERATED FROM PYTHON SOURCE LINES 141-151 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 :doc:`plot_affine_transformation`. 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. .. GENERATED FROM PYTHON SOURCE LINES 151-159 .. code-block:: Python import numpy as np masker = NiftiMasker(mask_strategy="epi", target_affine=np.eye(3) * 8) masker.fit(epi_img) report = masker.generate_report() report .. raw:: html

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<voxel>` is necessary. Use case: working with time series of :term:`resting-state` or task maps.

image
overlay

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.

Parameters
Parameter Value
detrend False
dtype None
high_pass None
high_variance_confounds False
low_pass None
mask_args None
mask_img None
mask_strategy epi
memory Memory(location=None)
memory_level 1
reports True
runs None
smoothing_fwhm None
standardize False
standardize_confounds True
t_r None
target_affine [[8. 0. 0.] [0. 8. 0.] [0. 0. 8.]]
target_shape None
verbose 0


.. GENERATED FROM PYTHON SOURCE LINES 160-164 After mask computation: extracting time series ---------------------------------------------- Extract time series .. GENERATED FROM PYTHON SOURCE LINES 164-184 .. code-block:: Python # trended vs detrended trended = NiftiMasker(mask_strategy="epi") detrended = NiftiMasker(mask_strategy="epi", detrend=True) 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() .. rst-class:: sphx-glr-script-out .. code-block:: none Trended: mean 552.82, std 168.28 Detrended: mean -0.00, std 5.88 .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 14.699 seconds) **Estimated memory usage:** 508 MB .. _sphx_glr_download_auto_examples_06_manipulating_images_plot_mask_computation.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: binder-badge .. image:: images/binder_badge_logo.svg :target: https://mybinder.org/v2/gh/nilearn/nilearn/0.10.4?urlpath=lab/tree/notebooks/auto_examples/06_manipulating_images/plot_mask_computation.ipynb :alt: Launch binder :width: 150 px .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: plot_mask_computation.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_mask_computation.py ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_