.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        Click :ref:`here <sphx_glr_download_auto_examples_plot_nilearn_101.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_nilearn_101.py:


Basic nilearn example: manipulating and looking at data
=======================================================

A simple example showing how to load an existing Nifti file and use
basic nilearn functionalities.


.. code-block:: default


    # Let us use a Nifti file that is shipped with nilearn
    from nilearn.datasets import MNI152_FILE_PATH

    # Note that the variable MNI152_FILE_PATH is just a path to a Nifti file
    print('Path to MNI152 template: %r' % MNI152_FILE_PATH)





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    /home/nicolas/GitRepos/nilearn-fork/nilearn/datasets/__init__.py:93: FutureWarning: Fetchers from the nilearn.datasets module will be updated in version 0.9 to return python strings instead of bytes and Pandas dataframes instead of Numpy arrays.
      warn("Fetchers from the nilearn.datasets module will be "
    Path to MNI152 template: '/home/nicolas/GitRepos/nilearn-fork/nilearn/datasets/data/mni_icbm152_t1_tal_nlin_sym_09a_converted.nii.gz'




A first step: looking at our data
----------------------------------

Let's quickly plot this file:


.. code-block:: default

    from nilearn import plotting
    plotting.plot_img(MNI152_FILE_PATH)




.. image:: /auto_examples/images/sphx_glr_plot_nilearn_101_001.png
    :alt: plot nilearn 101
    :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    <nilearn.plotting.displays.OrthoSlicer object at 0x7fbf06f278e0>



This is not a very pretty plot. We just used the simplest possible
code. There is a whole :ref:`section of the documentation <plotting>`
on making prettier code.

**Exercise**: Try plotting one of your own files. In the above,
MNI152_FILE_PATH is nothing more than a string with a path pointing to
a nifti image. You can replace it with a string pointing to a file on
your disk. Note that it should be a 3D volume, and not a 4D volume.

Simple image manipulation: smoothing
-------------------------------------

Let's use an image-smoothing function from nilearn:
:func:`nilearn.image.smooth_img`

Functions containing 'img' can take either a filename or an image as input.

Here we give as inputs the image filename and the smoothing value in mm


.. code-block:: default

    from nilearn import image
    smooth_anat_img = image.smooth_img(MNI152_FILE_PATH, fwhm=3)

    # While we are giving a file name as input, the function returns
    # an in-memory object:
    smooth_anat_img





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    <nibabel.nifti1.Nifti1Image object at 0x7fbf06e28fd0>



This is an in-memory object. We can pass it to nilearn function, for
instance to look at it


.. code-block:: default

    plotting.plot_img(smooth_anat_img)




.. image:: /auto_examples/images/sphx_glr_plot_nilearn_101_002.png
    :alt: plot nilearn 101
    :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    <nilearn.plotting.displays.OrthoSlicer object at 0x7fbf06e63850>



We could also pass it to the smoothing function


.. code-block:: default

    more_smooth_anat_img = image.smooth_img(smooth_anat_img, fwhm=3)
    plotting.plot_img(more_smooth_anat_img)




.. image:: /auto_examples/images/sphx_glr_plot_nilearn_101_003.png
    :alt: plot nilearn 101
    :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    <nilearn.plotting.displays.OrthoSlicer object at 0x7fbf06f15d90>



Saving results to a file
-------------------------

We can save any in-memory object as follows:


.. code-block:: default

    more_smooth_anat_img.to_filename('more_smooth_anat_img.nii.gz')








Finally, calling plotting.show() is necessary to display the figure
when running as a script outside IPython


.. code-block:: default

    plotting.show()








|

______

To recap, all the nilearn tools can take data as filenames or in-memory
objects, and return brain volumes as in-memory objects. These can be
passed on to other nilearn tools, or saved to disk.


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** ( 0 minutes  3.153 seconds)


.. _sphx_glr_download_auto_examples_plot_nilearn_101.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_nilearn_101.ipynb
      :alt: Launch binder
      :width: 150 px


  .. container:: sphx-glr-download sphx-glr-download-python

     :download:`Download Python source code: plot_nilearn_101.py <plot_nilearn_101.py>`



  .. container:: sphx-glr-download sphx-glr-download-jupyter

     :download:`Download Jupyter notebook: plot_nilearn_101.ipynb <plot_nilearn_101.ipynb>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_