.. only:: html
.. note::
:class: sphx-glr-download-link-note
Click :ref:`here <sphx_glr_download_auto_examples_plot_3d_and_4d_niimg.py>` 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_plot_3d_and_4d_niimg.py:
3D and 4D niimgs: handling and visualizing
==========================================
Here we discover how to work with 3D and 4D niimgs.
Downloading tutorial datasets from Internet
--------------------------------------------
Nilearn comes with functions that download public data from Internet
Let's first check where the data is downloaded on our disk:
.. code-block:: default
from nilearn import datasets
print('Datasets are stored in: %r' % datasets.get_data_dirs())
.. rst-class:: sphx-glr-script-out
Out:
.. code-block:: none
Datasets are stored in: ['/home/nicolas/nilearn_data']
Let's now retrieve a motor contrast from a Neurovault repository
.. code-block:: default
motor_images = datasets.fetch_neurovault_motor_task()
motor_images.images
.. rst-class:: sphx-glr-script-out
Out:
.. code-block:: none
['/home/nicolas/nilearn_data/neurovault/collection_658/image_10426.nii.gz']
motor_images is a list of filenames. We need to take the first one
.. code-block:: default
tmap_filename = motor_images.images[0]
Visualizing a 3D file
----------------------
The file contains a 3D volume, we can easily visualize it as a
statistical map:
.. code-block:: default
from nilearn import plotting
plotting.plot_stat_map(tmap_filename)
.. image:: /auto_examples/images/sphx_glr_plot_3d_and_4d_niimg_001.png
:alt: plot 3d and 4d niimg
:class: sphx-glr-single-img
.. rst-class:: sphx-glr-script-out
Out:
.. code-block:: none
<nilearn.plotting.displays.OrthoSlicer object at 0x7fc6aadb1460>
Visualizing works better with a threshold
.. code-block:: default
plotting.plot_stat_map(tmap_filename, threshold=3)
.. image:: /auto_examples/images/sphx_glr_plot_3d_and_4d_niimg_002.png
:alt: plot 3d and 4d niimg
:class: sphx-glr-single-img
.. rst-class:: sphx-glr-script-out
Out:
.. code-block:: none
<nilearn.plotting.displays.OrthoSlicer object at 0x7fc6a81d01c0>
Visualizing one volume in a 4D file
-----------------------------------
We can download resting-state networks from the Smith 2009 study on
correspondance between rest and task
.. code-block:: default
rsn = datasets.fetch_atlas_smith_2009()['rsn10']
rsn
.. rst-class:: sphx-glr-script-out
Out:
.. code-block:: none
'/home/nicolas/nilearn_data/smith_2009/PNAS_Smith09_rsn10.nii.gz'
It is a 4D nifti file. We load it into the memory to print its
shape.
.. code-block:: default
from nilearn import image
print(image.load_img(rsn).shape)
.. rst-class:: sphx-glr-script-out
Out:
.. code-block:: none
(91, 109, 91, 10)
We can retrieve the first volume (note that Python indexing starts at 0):
.. code-block:: default
first_rsn = image.index_img(rsn, 0)
print(first_rsn.shape)
.. rst-class:: sphx-glr-script-out
Out:
.. code-block:: none
(91, 109, 91)
first_rsn is a 3D image.
We can then plot it
.. code-block:: default
plotting.plot_stat_map(first_rsn)
.. image:: /auto_examples/images/sphx_glr_plot_3d_and_4d_niimg_003.png
:alt: plot 3d and 4d niimg
:class: sphx-glr-single-img
.. rst-class:: sphx-glr-script-out
Out:
.. code-block:: none
<nilearn.plotting.displays.OrthoSlicer object at 0x7fc6c8bc4370>
Looping on all volumes in a 4D file
-----------------------------------
If we want to plot all the volumes in this 4D file, we can use iter_img
to loop on them.
Then we give a few arguments to plot_stat_map in order to have a more
compact display.
.. code-block:: default
for img in image.iter_img(rsn):
# img is now an in-memory 3D img
plotting.plot_stat_map(img, threshold=3, display_mode="z", cut_coords=1,
colorbar=False)
.. rst-class:: sphx-glr-horizontal
*
.. image:: /auto_examples/images/sphx_glr_plot_3d_and_4d_niimg_004.png
:alt: plot 3d and 4d niimg
:class: sphx-glr-multi-img
*
.. image:: /auto_examples/images/sphx_glr_plot_3d_and_4d_niimg_005.png
:alt: plot 3d and 4d niimg
:class: sphx-glr-multi-img
*
.. image:: /auto_examples/images/sphx_glr_plot_3d_and_4d_niimg_006.png
:alt: plot 3d and 4d niimg
:class: sphx-glr-multi-img
*
.. image:: /auto_examples/images/sphx_glr_plot_3d_and_4d_niimg_007.png
:alt: plot 3d and 4d niimg
:class: sphx-glr-multi-img
*
.. image:: /auto_examples/images/sphx_glr_plot_3d_and_4d_niimg_008.png
:alt: plot 3d and 4d niimg
:class: sphx-glr-multi-img
*
.. image:: /auto_examples/images/sphx_glr_plot_3d_and_4d_niimg_009.png
:alt: plot 3d and 4d niimg
:class: sphx-glr-multi-img
*
.. image:: /auto_examples/images/sphx_glr_plot_3d_and_4d_niimg_010.png
:alt: plot 3d and 4d niimg
:class: sphx-glr-multi-img
*
.. image:: /auto_examples/images/sphx_glr_plot_3d_and_4d_niimg_011.png
:alt: plot 3d and 4d niimg
:class: sphx-glr-multi-img
*
.. image:: /auto_examples/images/sphx_glr_plot_3d_and_4d_niimg_012.png
:alt: plot 3d and 4d niimg
:class: sphx-glr-multi-img
*
.. image:: /auto_examples/images/sphx_glr_plot_3d_and_4d_niimg_013.png
:alt: plot 3d and 4d niimg
:class: sphx-glr-multi-img
.. rst-class:: sphx-glr-script-out
Out:
.. code-block:: none
/home/nicolas/GitRepos/nilearn-fork/nilearn/plotting/displays.py:1750: MatplotlibDeprecationWarning: Adding an axes using the same arguments as a previous axes currently reuses the earlier instance. In a future version, a new instance will always be created and returned. Meanwhile, this warning can be suppressed, and the future behavior ensured, by passing a unique label to each axes instance.
ax = fh.add_axes([fraction * index * (x1 - x0) + x0, y0,
Looping through selected volumes in a 4D file
---------------------------------------------
If we want to plot selected volumes in this 4D file, we can use index_img
with the `slice` constructor to select the desired volumes.
Afterwards, we'll use iter_img to loop through them following the same
formula as before.
.. code-block:: default
selected_volumes = image.index_img(rsn, slice(3, 5))
If you're new to Python, one thing to note is that the slice constructor
uses 0-based indexing. You can confirm this by matching these slices
to the previous plot above.
.. code-block:: default
for img in image.iter_img(selected_volumes):
plotting.plot_stat_map(img)
.. rst-class:: sphx-glr-horizontal
*
.. image:: /auto_examples/images/sphx_glr_plot_3d_and_4d_niimg_014.png
:alt: plot 3d and 4d niimg
:class: sphx-glr-multi-img
*
.. image:: /auto_examples/images/sphx_glr_plot_3d_and_4d_niimg_015.png
:alt: plot 3d and 4d niimg
:class: sphx-glr-multi-img
plotting.show is useful to force the display of figures when running
outside IPython
.. code-block:: default
plotting.show()
|
______
To recap, neuroimaging images (niimgs as we call them) come in
different flavors:
* 3D images, containing only one brain volume
* 4D images, containing multiple brain volumes.
More details about the input formats in nilearn for 3D and 4D images is
given in the documentation section: :ref:`loading_data`.
Functions accept either 3D or 4D images, and we need to use on the one
hand :func:`nilearn.image.index_img` or :func:`nilearn.image.iter_img`
to break down 4D images into 3D images, and on the other hand
:func:`nilearn.image.concat_imgs` to group a list of 3D images into a 4D
image.
.. rst-class:: sphx-glr-timing
**Total running time of the script:** ( 0 minutes 17.437 seconds)
.. _sphx_glr_download_auto_examples_plot_3d_and_4d_niimg.py:
.. only :: html
.. container:: sphx-glr-footer
:class: sphx-glr-footer-example
.. container:: binder-badge
.. image:: images/binder_badge_logo.svg
:target: https://mybinder.org/v2/gh/nilearn/nilearn.github.io/main?filepath=examples/auto_examples/plot_3d_and_4d_niimg.ipynb
:alt: Launch binder
:width: 150 px
.. container:: sphx-glr-download sphx-glr-download-python
:download:`Download Python source code: plot_3d_and_4d_niimg.py <plot_3d_and_4d_niimg.py>`
.. container:: sphx-glr-download sphx-glr-download-jupyter
:download:`Download Jupyter notebook: plot_3d_and_4d_niimg.ipynb <plot_3d_and_4d_niimg.ipynb>`
.. only:: html
.. rst-class:: sphx-glr-signature
`Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_