.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/plot_AAL_example.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

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

        Click :ref:`here <sphx_glr_download_auto_examples_plot_AAL_example.py>`
        to download the full example code

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_plot_AAL_example.py:


Fetching BIDS-Atlas compliant atlases
=====================================
This example demonstrates how to use :mod:`bids_atlas.datasets` to fetch
atlases that confirm to BIDS-Atlas.

.. GENERATED FROM PYTHON SOURCE LINES 10-20

Much of the functionality of the ``bids_atlas`` toolbox relies on downloading
commonly used publicly available atlases. Each atlas has its own ``function``, with certain
arguments being shared across all of them.
This specifically refers to the ``target space`` and ``resolution`` the given ``atlas`` should
be obtained in. 

Here we show how download a few atlases, using the respective ``functions`` and ``arguments``.

First of all, we are going to import ``bids_atlas`` ``dataset`` ``module``, as this will give us
access to all respective functions.

.. GENERATED FROM PYTHON SOURCE LINES 20-23

.. code-block:: default


    from bids_atlas import datasets








.. GENERATED FROM PYTHON SOURCE LINES 24-28

Lets start with the ``AAL`` ``atlas``. In order to obtain it in a ``BIDS-Atlas`` compliant manner, we only need to
use the respective function, called ``get_AAL``. If we run it without specifying any arguments, it will be provided
in the current directory and default specifications, ie 2mm resolution. The function will return a dictionary with 
the paths to atlas image, .tsv and .json files.

.. GENERATED FROM PYTHON SOURCE LINES 28-31

.. code-block:: default


    AAL_atlas = datasets.get_AAL()





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

 .. code-block:: none

    checking if atlas needs to be resampled
    atlas will be resampled to target
    Atlas will be saved to /home/runner/work/bids_atlas/bids_atlas/examples/bids_atlas_datasets/AAL
    The following files were downloaded at /home/runner/work/bids_atlas/bids_atlas/examples/bids_atlas_datasets/AAL
    AAL/
    ├─atlas-AAL_res-2_dseg.json
    ├─atlas-AAL_res-2_dseg.tsv
    └─atlas-AAL_res-2_dseg.nii.gz




.. GENERATED FROM PYTHON SOURCE LINES 32-33

Now the respective files can be accessed via their ``keys``. The path to the ``atlas image`` can be obtained via

.. GENERATED FROM PYTHON SOURCE LINES 33-36

.. code-block:: default


    AAL_atlas['AtlasImage']





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

 .. code-block:: none


    '/home/runner/work/bids_atlas/bids_atlas/examples/bids_atlas_datasets/AAL/atlas-AAL_res-2_dseg.nii.gz'



.. GENERATED FROM PYTHON SOURCE LINES 37-38

and thus easily be loaded, plotted, or utilized within an analysis.

.. GENERATED FROM PYTHON SOURCE LINES 38-43

.. code-block:: default


    from nilearn.plotting import plot_roi

    plot_roi(AAL_atlas['AtlasImage'], draw_cross=False, cmap='Set2')




.. image-sg:: /auto_examples/images/sphx_glr_plot_AAL_example_001.png
   :alt: plot AAL example
   :srcset: /auto_examples/images/sphx_glr_plot_AAL_example_001.png
   :class: sphx-glr-single-img


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

 .. code-block:: none


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



.. GENERATED FROM PYTHON SOURCE LINES 44-46

The .tsv and .json files contain important information and metadata concerning the atlas. The former entails a DataFrame
indicating the indices of the atlas and details thereof. 

.. GENERATED FROM PYTHON SOURCE LINES 46-51

.. code-block:: default


    import pandas as pd

    pd.read_csv(AAL_atlas['AtlasTSV'])






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>Index</th>
          <th>Label</th>
          <th>Hemisphere</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>2001</td>
          <td>Precentral_L</td>
          <td>left</td>
        </tr>
        <tr>
          <th>1</th>
          <td>2002</td>
          <td>Precentral_R</td>
          <td>right</td>
        </tr>
        <tr>
          <th>2</th>
          <td>2101</td>
          <td>Frontal_Sup_L</td>
          <td>left</td>
        </tr>
        <tr>
          <th>3</th>
          <td>2102</td>
          <td>Frontal_Sup_R</td>
          <td>right</td>
        </tr>
        <tr>
          <th>4</th>
          <td>2111</td>
          <td>Frontal_Sup_Orb_L</td>
          <td>left</td>
        </tr>
        <tr>
          <th>...</th>
          <td>...</td>
          <td>...</td>
          <td>...</td>
        </tr>
        <tr>
          <th>111</th>
          <td>9130</td>
          <td>Vermis_6</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>112</th>
          <td>9140</td>
          <td>Vermis_7</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>113</th>
          <td>9150</td>
          <td>Vermis_8</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>114</th>
          <td>9160</td>
          <td>Vermis_9</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>115</th>
          <td>9170</td>
          <td>Vermis_10</td>
          <td>NaN</td>
        </tr>
      </tbody>
    </table>
    <p>116 rows × 3 columns</p>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 52-53

The latter comprises the atlas' metadata following ``BIDS`` specifications.

.. GENERATED FROM PYTHON SOURCE LINES 53-60

.. code-block:: default


    import json

    with open(AAL_atlas['AtlasJson'], 'r') as AAL_atlas_json:
        AAL_atlas_json_load = json.load(AAL_atlas_json)
        AAL_atlas_json_load = json.dumps(AAL_atlas_json_load, indent=4)
        print(AAL_atlas_json_load)




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

 .. code-block:: none

    {
        "Name": "Automated Anatomical Labeling Atlas - SPM12 version",
        "Description": "AAl atlas for SPM 12. Notes: This atlas is the result of an automated anatomical parcellation\nof the spatially normalized single-subject high-resolution T1 volume provided by the\nMontreal Neurological Institute (MNI) (D. L. Collins et al., 1998, Trans. Med. Imag. 17, 463-468, PubMed).\nUsing this parcellation method, three procedures to perform the automated anatomical labeling of functional\nstudies are proposed: (1) labeling of an extremum defined by a set of coordinates, (2) percentage of voxels belonging\nto each of the AVOI intersected by a sphere centered by a set of coordinates,\nand (3) percentage of voxels belonging to each of the AVOI intersected by an activated cluster.",
        "BIDSVersion": "PLEASE ADD",
        "Curators": "PLEASE ADD",
        "HowToAcknowledge": "PLEASE ADD",
        "SourceDatasetsURLs": "PLEASE ADD",
        "License": "Unknown",
        "Funding": "PLEASE ADD",
        "ReferencesAndLinks": "http://www.gin.cnrs.fr/AAL-217?lang",
        "Species": "Homo sapiens",
        "DerivedFrom": "PLEASE ADD",
        "LevelType": "Single-subject",
        "SpecialReference": "PLEASE ADD"
    }





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

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


.. _sphx_glr_download_auto_examples_plot_AAL_example.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example


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

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

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

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


.. only:: html

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

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