Fetching BIDS-Atlas compliant atlases

This example demonstrates how to use bids_atlas.datasets to fetch atlases that confirm to BIDS-Atlas.

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.

from bids_atlas import datasets

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.

AAL_atlas = datasets.get_AAL()

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

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

AAL_atlas['AtlasImage']

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

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

from nilearn.plotting import plot_roi

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

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

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.

import pandas as pd

pd.read_csv(AAL_atlas['AtlasTSV'])

	Index	Label	Hemisphere
0	2001	Precentral_L	left
1	2002	Precentral_R	right
2	2101	Frontal_Sup_L	left
3	2102	Frontal_Sup_R	right
4	2111	Frontal_Sup_Orb_L	left
...	...	...	...
111	9130	Vermis_6	NaN
112	9140	Vermis_7	NaN
113	9150	Vermis_8	NaN
114	9160	Vermis_9	NaN
115	9170	Vermis_10	NaN

116 rows × 3 columns

The latter comprises the atlas’ metadata following BIDS specifications.

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)

{
    "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"
}