From NITRC Wiki

pyClusterROI

pyClusterROI is a set of python scripts that implement the spatially constrained clustering methods described in Craddock RC, et al. A whole brain fMRI atlas generated via spatially constrained spectral clustering. ''Hum Brain Mapp''. 2011 Jul 18; . This is a method for generating ROIs based on the group-level clustering of functional MRI data. A spatial constraint is imposed to ensure that the resulting ROIs are spatially coherent, i.e. the voxels in the resulting ROIs are connected. Using this package, clustering can be performed based on either the temporal correlation between voxel time courses, the spatial correlation between whole brain functional connectivity maps generated from each voxel time course, or a random approach. Group level clustering can be achieved by either clustering the average of individual connectivity maps, or a 2-level approach in which single subject data is clustered, combined, and then submitted to another clustering. These methods require the specification of the number of clusters (ROIs) that the user would like to generate.

Based on the evaluations preformed in our paper, 2-level group clustering using temporal correlation performed better than other methods. But the user might choose a different approach based on the specific analysis that is being performed. The group-mean approach requires much less computation, so it might be more appropriate for large datasets. The user might prefer spatial correlation if they specifically want to optimize for the homogeneity of FC maps generated from withen-ROI clusters. Although, evidence from the paper suggests that temporal correlation does a better job of optimizing the homogeneity of FC maps then does spatial correlation. Additionally the number of clusters generated must be determined by the type of analysis to be performed. If the desire is to reduce the dimensionality to a low number while preserving functional homogeneity and interpretability, then a clustering in the range of 150 to 200 might be optimal. On the other hand, if the desire is to provide a modest amount of dimensionality reduction, but still preserve information present at the voxel scale, 600 - 1000 ROIs might be more appropriate.

More information about the clustering approach can be found in Craddock RC, et al. A whole brain fMRI atlas generated via spatially constrained spectral clustering. ''Hum Brain Mapp''. 2011 Jul 18; . as well as a poster (Craddock ISMRM 2010 Parcellation poster).

Installation

1. The pyClusterROI package requires python, SciPy, NumPy, and PyNiFTI. These packages are available for Windows, Linux and Mac OSX. All of the development and testing of pyClusterROI was performed on Linux, so that may be the best bet.
2. Once these have been installed, download the most recent release of the pyClusterROI and unarchive the scripts into any directory.

   tar xzvf pyClusterROI.#.#.tar.gz

3. If you wish to run pyClusterROI from a directory other than the directory in which the scripts are installed, you will have to make sure that the directory containing the PyClusterROI scripts is in the Python path environment variable. This can be accompished by adding something similar to the following line to your .bashrc (for Linux and Mac OSX) or editing your environment variables (Windows)

   export PYTHONPATH=$PYTHONPATH:/home/user/pyClusterROI

4. pyClusterROI comes with a demo script that can be used to make sure that the installation is working correctly. This script requires test data that must be separately downloaded and unarchived.

   tar xzvf pyClusterROI_testdata.#.#.tar.gz

   Once this has been accomplished the demo script can be run from the pyClusterROI directory using the following command:

   python pyClusterROI_test.py

   This script will probably take about an hour to run.

Documentation

Currently there is no documentation for pyClusterROI other than the comments in the script files and the pyClusterROI_test.py demo script. This script illustrates the correct usage of every function in the pyClusterROI toolbox, please refer to it as a guide on how to use pyClusterROI.

Atlases

Parcellations derived for the paper are available for download.

The download contains five nifti files, each containing parcellations derived from the five different methods compared in the paper: 2-level r_t, 2-level r_s, mean r_t, mean r_s, and random.

The downloaded tar.gz file can be expanded using the following command on Linux, Unix, and Mac systems:

tar xzvf craddock_2011_parcellations.tar.gz

On windows systems, try doubling clicking the file and see what happens. If it doesn't expand try 7-zip.

Each nifti file contains 44 different volumes (sub-briks in AFNI lingo) which correspond to the level of clustering. Each volume contains the cluster maps, in which each voxel contains the integer value of the cluster to which it belongs. Do to the clustering method, it is very likely that the results of a clustering will result in fewer clusters then was requested, i.e. a 1000-level clustering might result in 937 clusters.

The correspondance between clustering and volume # is listed below:

1. 10 clusters
2. 20 clusters
3. 30 clusters
4. 40 clusters
5. 50 clusters
6. 60 clusters
7. 70 clusters
8. 80 clusters
9. 90 clusters
10. 100 clusters
11. 110 clusters
12. 120 clusters
13. 130 clusters
14. 140 clusters
15. 150 clusters
16. 160 clusters
17. 170 clusters
18. 180 clusters
19. 190 clusters
20. 200 clusters
21. 210 clusters
22. 220 clusters
23. 230 clusters
24. 240 clusters
25. 250 clusters
26. 260 clusters
27. 270 clusters
28. 280 clusters
29. 290 clusters
30. 300 clusters
31. 350 clusters
32. 400 clusters
33. 450 clusters
34. 500 clusters
35. 550 clusters
36. 600 clusters
37. 650 clusters
38. 700 clusters
39. 750 clusters
40. 800 clusters
41. 850 clusters
42. 900 clusters
43. 950 clusters
44. 1000 clusters

Constructing GM mask for parcellation

I have received several emails asking me how to construct a GM mask to constrain the parcellations. Creating the masks is  tricky, and the one that I used for the paper required quite alot of trial and error. The process that I used was to segment each individuals anatomical image and to average the GM probability maps across subjects. After this I applied a threshold to the averaged probability maps in order to create a binary GM mask. I chose a threshold by visual inspection, so that the mask covered all of the brain regions that I am interested in. You will notice that parts of the putamen and globus pallidus may be excluded using this procedure. You will have to try several different parameters for segmentation and thresholding and possibly erosion/dilation in order to find a happy medium. Another approach could be to use a brain atlas such as the Harvard Oxford atlas to derive your grey matter mask. Of course, probably the best way to go would be to hand segment a set of images ...

Help

Please post any questions that you have to the help forum.

Licensing

pyClusterROI is released under the GPL version 3.0 license. If you wish to use the toolbox for any purposes other than those allowable by the GPL, please contact me.