AtlasReader¶
atlasreader is a Python interface that generates coordinate tables and region labels from statistical MRI images.
This notebook will show you how to install AtlasReader, how to run the toolbox and what the different parameters allow you to do.
Installing AtlasReader¶
Provided you have pip at your disposal, installing AtlasReader is as simple as this:
pip install atlasreader
If you want to install AtlasReader directly from the source code, use the following code:
git clone https://github.com/miykael/atlasreader.git
cd atlasreader
python setup.py install
Using AtlasReader¶
License terms of AtlasReader¶
Before showcasing the toolbox, we want to point to the particular license issue that you need to consider when you are using AtlasReader.
AtlasReader itself is licensed under the BSD-3 license, but the included atlases that are used to lookup the coordinate labels are under their own license terms. For this reason, we ask you to inform yourself about the atlas specific license terms under https://github.com/miykael/atlasreader/tree/master/atlasreader/data and to cite the corresponding papers should you use AtlasReader in a publication.
We've included the following information message after every first module import, to make sure that users are aware about this issue:
The Python package you are importing, AtlasReader, is licensed under the
BSD-3 license; however, the atlases it uses are separately licensed under more
restrictive frameworks.
By using AtlasReader, you agree to abide by the license terms of the
individual atlases. Information on these terms can be found online at:
https://github.com/miykael/atlasreader/tree/master/atlasreader/data
Citing atlasreader¶
If you use AtlasReader in your publication, please cite the following paper:
Notter M. P., Gale D., Herholz P., Markello R. D., Notter-Bielser M.-L., & Whitaker K. (2019). AtlasReader: A Python package to generate coordinate tables, region labels, and informative figures from statistical MRI images. *Journal of Open Source Software, 4(34), 1257*, [https://doi.org/10.21105/joss.01257](https://doi.org/10.21105/joss.01257)Prepare an example file¶
AtlasReader can either be run through the command line interface, or directly within Python. To showcase both of those examples, let's first import relevant plotting functions for this notebook.
%matplotlib inline
from nilearn.plotting import plot_glass_brain
from IPython.display import Image
Next, let's grab an example stat map. We'll use nilearn to grab a motor task stat map from neurovault and to threshold it at a value of 3 to create some clusters. Note that you'll need the most up to date version of nilearn in order to run fetch_neurovault_motor_task().
# Get a stat map from neurovault using nilearn
from nilearn.datasets import fetch_neurovault_motor_task
motor_images = fetch_neurovault_motor_task()
stat_img = motor_images.images[0]
# Threshold image at a value of 3 to create clusters
from nilearn.image import threshold_img
stat_img = threshold_img(stat_img, threshold=3)
# Save the thresholded image into a NIfTI file
file_name = 'stat_img.nii.gz'
stat_img.to_filename(file_name)
And what does our example data look like?
plot_glass_brain(file_name, black_bg=True, colorbar=True, plot_abs=False,
display_mode='lyrz', title='Finger tapping task');
Ok, so we can see that there are a few particular clusters, if we threshold the data at a value of 3. But how big are they and in which regions are they?
To answer these questions, you can use AtlasReader. It gives you the opportunity to better understand where the peaks of those clusters are, over which regions the clusters extend, and much more. So, how is it done?
Calling AtlasReader from Python¶
If you want to run AtlasReader directly in Python, just import the create_output() function, and you're good to go:
from atlasreader import create_output
Great, so now we can run AtlasReader. The only thing that we have to provide is our stat map (either the file_name or the image object) and the cluster extent, which specifies the minimum number of contiguous voxels required for a cluster to be considered for the analysis. For this example, let's set the cluster_extent to 5.
create_output(file_name, cluster_extent=5, direction='both')
After execution, we get four different kind of files:
- An overview figure that shows the results within the whole brain at once
- For each cluster, an informative figure showing the sagittal, coronal and trasnveral plane centered at this center of the cluster
- A csv file containing relevant information about the peak of each cluster
- A csv file containing relevant information about each cluster
So, let's take a closer look at those outputs:
Overview figure¶
The overview figure shows all clusters throught the brain, plotted on a glass brain plot. The name of file is the name of provided statistical image, but with the file ending .png
Image('stat_img.png')
Informative cluster figure¶
AtlasReader creates for each cluster an informative figure, showing the cluster center in the three anatomical planes: sagittal, coronal and trasnveral. The name of those files all end in _clusterXY.png, i.e. _cluster01.png, _cluster02.png, ...:
Image('stat_img_cluster01.png')
Image('stat_img_cluster03.png')
Peak table¶
The csv file ending with _peaks.csv contains the location of each cluster's peak, it's signal value at this location, the cluster extend (in mm, not in number of voxels) and the atlas correspondence of the peak:
import pandas as pd
pd.read_csv('stat_img_peaks.csv')
Cluster table¶
The csv file ending with _clusters.csv contains the location of each cluster's peak, the mean value within the cluster, the cluster extend (in mm, not in number of voxels), as well as the membership of each cluster, given a particular atlas.
pd.read_csv('stat_img_clusters.csv')
For example, in the csv table shown above, we know that 60.17% of the second cluster is in the left postcentral and 26.32% is in the left precentral area, according to the AAL atlas.
Additional parameters¶
As mentioned before, atlasreader.create_output has many additional parameters that allow you to change the way the clusters are generated and what kind of outputs are generated. So, let's have a closer look:
- filename: Niimg_like
A 3D statistical image. - cluster_extent: int
Minimum number of contiguous voxels required to consider a cluster infilename - atlas: str or list, optional
Name of atlas(es) to consider for cluster analysis. Default:'default' - voxel_thresh: float, optional
Threshold to apply to
stat_img. Usedirectionto specify the directionality of the threshold. If a negative number is provided a percentile threshold is used instead, where the percentile is determined by the equation100 - voxel_thresh. Default:1.96 - direction: str, optional
Specifies the direction in which
voxel_threshshould be applied. Possible values are'both','pos'or'neg'. Default:'both' - prob_thresh: int, optional
Probability (percentage) threshold to apply toatlas, if it is probabilistic. Default:5 - min_distance: float, optional
Specifies the minimum distance (in mm) required between sub-peaks in a cluster. If None, sub-peaks will not be examined and only the primary cluster peak will be reported. Default:None - outdir: str or None, optional
Path to desired output directory. If None, generated files will be saved to the same folder asfilename. Default:None - glass_plot_kws: dict or None, optional
Additional keyword arguments to pass tonilearn.plotting.plot_glass_brain. - stat_plot_kws: dict or None, optional
Additional keyword arguments to pass tonilearn.plotting.plot_stat_map.
The first two, we've already used in the previous example, but let's take a closer look at the others.
atlas and voxel_thresh¶
First, let's change the atlas and the voxel_thresh parameters:
create_output(file_name, cluster_extent=5,
atlas=['destrieux', 'marsatlas'],
voxel_thresh=6)
As you can see, the usage of a higher voxel threshold created smaller clusters and caused the clusters with below threshold voxels to disapear.
Image('stat_img.png')
Additionally, the csv files now contain the information about the destrieux and marsatlas.
pd.read_csv('stat_img_clusters.csv')
Note: The three atlases from the previous example, aal, desikan_killiany, harvard_oxford are the default atlases, which can either be specified with atlas='default', atlas=['aal', 'desikan_killiany', 'harvard_oxford'] or by just omitting the atlas parameter.
If a negative number is provided for voxel_thresh, a percentile threshold is used instead, where the percentile is determined by the equation 100 - voxel_thresh. So, let's threshold the data at 99%.
create_output(file_name, cluster_extent=5,
voxel_thresh=-1)
Image('stat_img.png')
Note: This percentage term is misleading if the statistical images contains negative values. For example, 99% in the above example, is the 99 percentile of all values between -7.9 to 7.9.
pd.read_csv('stat_img_clusters.csv')
direction¶
The direction parameter allows you to specify the directionality of the thresholding. By default, the directionality is 'both', which means that the voxel_thresh value is applied to positive and negative values. Changing direction to 'pos' or 'neg' allows you to apply the threshold only to one direction and ignore everything else in the other direction.
create_output(file_name, cluster_extent=5, atlas=['aal'],
voxel_thresh=4, direction='both')
Image('stat_img.png')
create_output(file_name, cluster_extent=5, atlas=['aal'],
voxel_thresh=4, direction='pos')
Image('stat_img.png')
create_output(file_name, cluster_extent=5, atlas=['aal'],
voxel_thresh=4, direction='neg')
Image('stat_img.png')
This thresholding directionality is of course also preserved in the tables.
pd.read_csv('stat_img_clusters.csv')
prob_thresh¶
The prob_thresh parameter can be used to restrict the information in the cluster table to a given probability value. This will only influence the information in the table, but won't change the cluster size or any other outcome.
So let's take again an example from before and set the probability threshold to 33%
create_output(file_name, cluster_extent=5,
prob_thresh=33.0)
As you can see, the cluster table has now fewer entries in the atlas column, as atlas corresponances below 33% where omitted. Be carefull, if this threshold is set to high, no atlas corresponance will survive. In which case the entry is replaces by NaN.
pd.read_csv('stat_img_clusters.csv')
min_distance¶
By default, AtlasReader only shows information of the main peak in the peak table. But some clusters might be rather big with many different peaks. If you also want to extract peak information of other peaks within a given cluster, you can use the min_distance paramter. This parameter specifies the minimum distance required between sub-peaks in a cluster.
To better illustrate this example, let's focus only on the big four cluster in our dataset (i.e. we will set cluster_extent=100).
create_output(file_name, cluster_extent=100,
atlas='aal',
min_distance=10)
Image('stat_img.png')