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.
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.
This package requires Python >= 3.6. Provided you have
pip at your disposal,
atlasreader is as simple as this:
pip install atlasreader
If you want to build
atlasreader directly from source code, use the
git clone https://github.com/miykael/atlasreader.git cd atlasreader python setup.py install
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:
from atlasreader import create_output create_output(file_name, cluster_extent=5)
atlasreader file_name 5
After executing AtlasReader on a given image, four kinds of outputs are generated:
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.
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 in
- atlas: str or list, optional
Name of atlas(es) to consider for cluster analysis. Default:
- voxel_thresh: float, optional
Threshold to apply to
directionto 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 equation
100 - voxel_thresh. Default:
- direction: str, optional
Specifies the direction in which
voxel_threshshould be applied. Possible values are
- prob_thresh: int, optional
Probability (percentage) threshold to apply to
atlas, if it is probabilistic. Default:
- 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:
- outdir: str or None, optional
Path to desired output directory. If None, generated files will be saved to the same folder as
- glass_plot_kws: dict or None, optional
Additional keyword arguments to pass to
- stat_plot_kws: dict or None, optional
Additional keyword arguments to pass to
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!
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