Lausanne Parcellation: Difference between revisions
No edit summary |
|||
Line 16: | Line 16: | ||
Next, use the <code>cd</code> command to navigate into the subject folder. | Next, use the <code>cd</code> command to navigate into the subject folder. | ||
cd FS_T1_501 | cd FS_T1_501 | ||
==== From the Linux Terminal ==== | |||
A handy dandy python script has been written to use the CMTK python interface. It can be found in the ubfs Scripts/Python directory. If it is not already in your linux path, copy it: | |||
cp ~/ubfs/cpmcnorg/Scripts/Python/subpar.py ~/bin/ | |||
Now you should be able to run the script from the shell terminal: | |||
SUBJECT_ID=FS_T1_501 | |||
subpar.py $SUBJECT_ID | |||
==== Using the iPython Interactive Shell ==== | |||
The subpar.py script described above automates the python commands described in this section. If, for whatever reason, you wish to run these steps in iPython, you will begin by launching ipython in your terminal window: | |||
ipython | ipython | ||
Line 32: | Line 40: | ||
In [1]: | In [1]: | ||
Suppose you wish to sub-parcellate the subject with ID FS_T1_501. You would type the following commands in the interactive Python shell: | Suppose you wish to sub-parcellate the subject with ID FS_T1_501. You would type the following commands in the interactive Python shell ('''In [?]:''' at the start of each line is the iPython command prompt, and does not need to be typed): | ||
import os | In [1]: import os | ||
import nipype.interfaces.cmtk as cmtk | In [2]: import nipype.interfaces.cmtk as cmtk | ||
parcellate = cmtk.Parcellate() | In [3]: parcellate = cmtk.Parcellate() | ||
parcellate.inputs.subject_id="FS_T1_501" | In [4]: parcellate.inputs.subject_id="FS_T1_501" | ||
parcellate.inputs.subjects_dir=os.environ['SUBJECTS_DIR']; | In [5]: parcellate.inputs.subjects_dir=os.environ['SUBJECTS_DIR']; | ||
parcellate.run(); | In [6]: parcellate.run(); | ||
That's it. If you had a different participant in mind, you would simply provide a different folder name for the <code>parcellate.inputs.subject_id</code> value. | That's it. If you had a different participant in mind, you would simply provide a different folder name for the <code>parcellate.inputs.subject_id</code> value. | ||
Whether you use the <code>subpar.py</code> script, or run the steps in iPython, the parcellation step will run for quite a while. | |||
==== Output ==== | ==== Output ==== | ||
When it has finished, the resulting label files can be found in multiple subdirectories of ''${SUBJECTS_DIR}/${SUBJECT_ID}/label/''. Look for subdirectories named ''regenerated_?h_###'', where '?h' will be either lh or rh, and '###' is one of the numbers 36, 60, 125, 250 and 500 (the numbers representing the numbers of regions in each subparcellation, roughly doubling each time). | When it has finished, the resulting label files can be found in multiple subdirectories of ''${SUBJECTS_DIR}/${SUBJECT_ID}/label/''. Look for subdirectories named ''regenerated_?h_###'', where '?h' will be either lh or rh, and '###' is one of the numbers 36, 60, 125, 250 and 500 (the numbers representing the numbers of regions in each subparcellation, roughly doubling each time). |
Revision as of 17:21, 13 June 2016
The Lausanne Parcellation is a workflow that subdivides the 30+ general brain regions into many smaller partitions of approximately equal size. This gives us a finer-grained partitioning of the cortex. Because they are smaller, these partitions are more likely to behave relatively more homogeneously during a particular task. Because they are of comparable size, it is more justifiable to weight them equally in your analyses.
The Lausanne 2008 parcellation scheme refers to the 2008 PLoS Biology Paper Mapping the Structural Core of Human Cerebral Cortex
Lausanne Parcellation Workflow
Recon-all
A precondition for subparcellating the cortex in surface space is that you will first require a parcellated cortical surface mesh on which to operate. You will need to take a T1 (i.e., anatomical; MPRAGE) volume to the end of the recon-all pipeline, by running the autorecon1, autorecon2 and autorecon3 steps, as outlined elsewhere.
Subparcellate Using ConnectomeMapper in Python
The Lausanne 2008 subparcellation is most easily carried out using the ConnectomeMapper Python library. This should already be installed on your workstation. I believe these libraries use calls to FreeSurfer to carry out the parcellation, but I am not totally sure that this is the case, nor what actually goes on under the hood. Nonetheless, the connectome mapper toolkit (cmtk) Python interface provides an easy way to get this done using the Python scripting language.
First, in your Linux terminal, navigate to your $SUBJECTS_DIR
cd $SUBJECTS_DIR
Hopefully this is indeed the directory that contains the folder for the subject whose surface mesh you wish to sub-parcellate. If not, you will need to navigate to the correct directory, and reset your SUBJECTS_DIR environment variable as required.
Next, use the cd
command to navigate into the subject folder.
cd FS_T1_501
From the Linux Terminal
A handy dandy python script has been written to use the CMTK python interface. It can be found in the ubfs Scripts/Python directory. If it is not already in your linux path, copy it:
cp ~/ubfs/cpmcnorg/Scripts/Python/subpar.py ~/bin/
Now you should be able to run the script from the shell terminal:
SUBJECT_ID=FS_T1_501 subpar.py $SUBJECT_ID
Using the iPython Interactive Shell
The subpar.py script described above automates the python commands described in this section. If, for whatever reason, you wish to run these steps in iPython, you will begin by launching ipython in your terminal window:
ipython
You will now find yourself in a python interactive command shell that looks something like this:
Python 2.7.6 (default, Jun 22 2015, 17:58:13) Type "copyright", "credits" or "license" for more information. IPython 1.2.1 -- An enhanced Interactive Python. ? -> Introduction and overview of IPython's features. %quickref -> Quick reference. help -> Python's own help system. object? -> Details about 'object', use 'object??' for extra details. In [1]:
Suppose you wish to sub-parcellate the subject with ID FS_T1_501. You would type the following commands in the interactive Python shell (In [?]: at the start of each line is the iPython command prompt, and does not need to be typed):
In [1]: import os In [2]: import nipype.interfaces.cmtk as cmtk In [3]: parcellate = cmtk.Parcellate() In [4]: parcellate.inputs.subject_id="FS_T1_501" In [5]: parcellate.inputs.subjects_dir=os.environ['SUBJECTS_DIR']; In [6]: parcellate.run();
That's it. If you had a different participant in mind, you would simply provide a different folder name for the parcellate.inputs.subject_id
value.
Whether you use the subpar.py
script, or run the steps in iPython, the parcellation step will run for quite a while.
Output
When it has finished, the resulting label files can be found in multiple subdirectories of ${SUBJECTS_DIR}/${SUBJECT_ID}/label/. Look for subdirectories named regenerated_?h_###, where '?h' will be either lh or rh, and '###' is one of the numbers 36, 60, 125, 250 and 500 (the numbers representing the numbers of regions in each subparcellation, roughly doubling each time).
Important: Note that empty folders with the same names will be generated in the folder you were in when you ran the cmtk in ipython (in the subject's base folder, assuming you followed the above directions). These folders are superfluous and can be deleted, though be absolutely certain you are deleting the correct folder so that you don't have to redo the above step!
Generate a Color Lookup Table (CLUT) and Merge Annotations
Unfortunately, the process doesn’t just create a single .annot file containing the ~500 labels for each hemisphere. That would be too convenient. Instead, we have to do some fussing around to merge everything all together. Freesurfer has a tool called mris_label2annot that we can use to combine it all.
Unfortunately, label colors are used as an important organizing tool. This means we’re first going to have to assign colors to each of our 500 regions in each hemisphere with a CLUT.
Gather Required Scripts
SurfLabelCLUT.m
A MATLAB function (SurfLabelCLUT.m) needs to be in your MATLAB path. If it is not, you can copy it from the ubfs folder to a directory appearing in your MATLAB path (such as your ~/Documents/MATLAB/ directory):
cp ~/ubfs/cpmcnorg/Scripts/Matlab/SurfLabelCLUT.m ~/Documents/MATLAB/
If this file can be found in your MATLAB path, then it will be available for MATLAB to use.This function generates a color table containing similar colors for the subdividsions within each broad anatomical region. For example, all the subdivisions of the Middle Temporal Gyrus (MTG) might be various shades of green, but those can be differentiated from the subdivisions of the adjacent Superior Temporal Gyrus, which might be assigned various shades of purple.
clut.sh
The MATLAB function SurfLabelCLUT.m I just described is used indirectly by a shell script I have written called clut.sh, which is also found in the ubfs folder. This shell script can be used if it exists in your Linux $PATH. You should already have a ~/bin directory where your shell scripts are kept, so this file can be copied there if it doesn't already exist:
cp ~/ubfs/cpmcnorg/Scripts/Shell/clut.sh ~/bin
Run the Scripts
These two scripts handle the dirty work in the Linux terminal by calling the clut.sh script, passing a subject id as a parameter:
clut.sh 501_001
Note that this script will use the $SUBJECTS_DIR environment variable to figure out where to start looking for the files. Your terminal window may be using the default Freesurfer directory for this value, and so you may have to first change the $SUBJECTS_DIR environment variable to the directory containing your data.
This script will call on MATLAB to generate a CLUT, and then merge all the anatomical subdivisions generated in the previous step into two .annot files called lh.lausanne.annot and rh.lausanne.annot, respectively. These .annot files will be placed in the ${SUBJECTS_DIR}/${SUBJECT_ID}/label/ folder.