atlasreader
atlasreader copied to clipboard
Python interface for generating coordinate tables and region labels from statistical MRI images
AtlasReader
This package provides a Python interface for generating coordinate tables and region labels from statistical MRI images. It is intended for neuroscience researchers and neuroimaging enthusiasts who are looking for a quick and easy way to localize and extract relevant peak and cluster information and create informative and nice looking overview figures.
Please check out our interactive notebook on mybinder.org to see atlasreader
in action:
If you are using 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.
Installation
This package requires Python >= 3.6. Provided you have pip
at your disposal,
installing atlasreader
is as simple as this:
pip install atlasreader
If you want to build atlasreader
directly from source code, use the
following code:
git clone https://github.com/miykael/atlasreader.git
cd atlasreader
python setup.py install
Usage
AtlasReader can either be run through the command line interface or directly
within Python. The commands to do so are rather straight forward. Let's say you
want to apply AtlasReader to a statistical image called
file_name = 'stat_img.nii'
, and only want to keep clusters if they have more
than 5 voxels:
Python
from atlasreader import create_output
create_output(file_name, cluster_extent=5)
Command Line
atlasreader file_name 5
Outputs
After executing AtlasReader on a given image, four kinds of outputs are generated:
-
An overview figure that shows the results within the whole brain at once
-
For each cluster, an informative figure showing the sagittal, coronal and transversal plane centered on the main peak of the cluster
-
A csv file containing relevant information about the peak of each cluster. This table contains the cluster association and location of each peak, its signal value at this location, the cluster extent (in mm, not in number of voxels), as well as the membership of each peak, given a particular atlas.
-
A csv file containing relevant information about each cluster. Table showing relevant information for the cluster extent of each ROI. This table contains the cluster association and location of each peak, the mean value within the cluster, the cluster extent (in mm, not in number of voxels), as well as the membership of each cluster, given a particular atlas.
Additional parameters
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:
-
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
. Usedirection
to 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_thresh
should 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
. Default:None
-
stat_plot_kws: dict or None, optional
Additional keyword arguments to pass tonilearn.plotting.plot_stat_map
. Default:None
For a more detailed explanation about the toolbox and the effect of the parameters above, see the example notebook. You can checkout the notebook either interactively via mybinder.org or explore a read-only version on nbviewer.jupyter.org.
How to get involved
We're thrilled to welcome new contributors!
If you're interested in getting involved, you should start by reading our contributing guidelines.
Once you're done with that, you can take a look at our list of active issues and let us know if there's something you'd like to begin working on.
If you've found a bug, are experiencing a problem, or have a question, create a new issue with some information about it!
Licence
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