We in our group received with great interest the publication of the HCP-MMP1.0 parcellation by Glasser et al. (Nature)  created using data from the Human Connectome Project earlier this year. Often in our connectivity pipelines we use volume files for parcellation in native space, so we decided to try and convert the Connectome Workbench files to volume masks in native structural space to try out in future studies.
We were happy to find that someone had already gone through the trouble of generating FreeSurfer annotation files projected on fsaverage, so all we had to do was find a way to transform these annot files to each subject’s space and convert them to volume masks.
To do that, we wrote a little Linux shell script that goes through a series of conversion and transformation steps using FreeSurfer commands. It first converts the downloaded annotation files (lh.HCPMMP1.annot and rh.HCPMMP1.annot) to labels using mri_annotation2label, then takes each label from fsaverage to each subject’s space with mri_label2label, converts transformed labels back to annotation with mri_label2annot, and finally converts these to volume files (nii.gz) with mris_label2annot. Seems like too many steps, but this is how we (who are far from being FreeSurfer experts) got satisfactory results.
The default final file consists of a single .nii.gz volume containing the cortical HCP-MMP1.0 regions plus the subcortical regions from the FreeSurfer segmentation, each assigned a unique voxel value. It should be noted that the HCP-MMP1.0 parcellation includes 180 regions – 179 of them cortical, and one subcortical (hippocampus). In the final volume file, left-hemisphere cortical HCP-MMP1.0 regions will have values between 1001 and 1181, whereas right-sided regions will have values between 2001 and 2181. The correspondence between each specific region and its voxel value is given in a look-up table that is saved in each subject’s output folder. To identify the hippocampus (and other subcortical structures), one needs to check the corresponding voxel values in the FreeSurferColorLUT.txt file provided with FreeSurfer (https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/AnatomicalROI/FreeSurferColorLUT), as it is generated based on the original aseg parcellation*.
*In the previous version of the script, a few perihippocampal cortical voxels were ascribed values (1121 and 2121) that should correspond to the hippocampus in the HCPMMP1.0 parcellation. Since only the cortical regions from this parcellation are generated, these voxels are now assigned the values corresponding to the hippocampus as defined by the automatic FreeSurfer subcortical segmentation (17 and 53).
Optionally, one can choose to also generate individual volume files for each cortical and/or subcortical parcellation region. This option requires FSL. If the user chooses to create individual subcortical masks, the FreeSurferColorLUT.txt must also be available in the base ($SUBJECTS_DIR/) folder.
By default, the script also generates tables with anatomical information for each cortical region (number of vertices, area, volume, mean thickness, etc.).
- Subject data. First of all, you need to have your subjects’ structural data preprocessed with FreeSurfer.
- Shell script. Download the script from here and copy it to to your $SUBJECTS_DIR/ folder.
- Fsaverage data. If it’s not there already, copy the fsaverage folder from the FreeSurfer directory ($FREESURFER_HOME/subjects/fsaverage) to your $SUBJECTS_DIR/ folder.
- Annotation files. Download rh.HCPMMP1.annot and lh.HCPMMP1.annot from https://figshare.com/articles/HCP-MMP1_0_projected_on_fsaverage/3498446. Copy them to your $SUBJECTS_DIR/ folder or to $SUBJECTS_DIR/fsaverage/label/.
- Subject list. Create a list with the identifiers of the desired target subjects (named exactly as their corresponding names in $SUBJECTS_DIR/, of course).
- FreeSurferColorLUT.txt. If the user chooses to generate individual volume files for the subcortical from the automatic FreeSurfer segmentation, this file should be placed in the $SUBJECTS_DIR/ folder.
- Launch the script: bash create_subj_volume_parcellation.sh (this will show the compulsory and optional arguments).
- The compulsory arguments are:
- -L subject_list_name
- -a name_of_annotation_file (without hemisphere or extension; in this case, HCPMMP1)
- -d name_of_output_dir (will be created in $SUBJECTS_DIR)
- Optional arguments:
- -f and -l indicate the first and last subjects in the subject list to be processed. Eg, in order to process the third till the fifth subject, one would enter -f 3 -l 5 (whole thing takes a bit of time, so one might want to launch it in separate terminals for speed)
- -t (“YES” or “NO”, default is YES) indicates whether individual tables with anatomical data per region (number of vertices, area, volume, mean thickness, …) will be created
- -m (“YES” or “NO”, default is NO) indicates whether individual volume files for each cortical HCPMMP1.0 parcellation region should be created. This requires FSL
- -s (“YES” or “NO”, default is NO) indicates whether individual volume files for each subcortical aseg region should be created. Also requires FSL
To process the first five subjects listed in subject_list.txt, saving the results in a folder called HCPMMP_parcellation, including individual cortical (-m) and subcortical (-s) binary masks, the command would look like:
bash create_subj_volume_parcellation.sh -L subject_list.txt -f 1 -l 5 -a HCPMMP1 -d HCPMMP_parcellation -s YES -m YES
To process all subjects in subject_list.txt, saving them to HCPMMP_parcellation, without generating individual region masks:
bash create_subj_volume_parcellation.sh -L subject_list.txt -a HCPMMP1 -d HCPMMP_parcellation
- An output folder named as specified with the -d option will be created, which will contain a directory called label/, where the labels for the regions projected on fsaverage will be stored. The output directory will also contain a folder for each subject. Inside these subject folders, a .nii.gz file named as the annotation file (-a option) will contain the final parcellation volume. A look-up table will also be created inside each subject’s folder, named LUT_HCPMMP1.txt. In each subject’s folder, a directory called label/ will also be created, where the transformed labels will be stored
- In each subject’s folder, a directory called tables/ will be generated, containing the anatomical information for each cortical region
- If the -m option is set to YES, each subject’s directory will also contain a masks/ directory containing one volume .nii.gz file for each binary mask
- If the -s option is set to YES, an aseg_masks/ directory will be created, containing one .nii.gz file for each subcortical region
- Inside the original subjects’ label folders, post-transformation annotation files will be created. These are not overwritten if the script is relaunched; so, if you ran into a problem and want to start over, you should delete these files (named lh(rh).subject_HCPMMP1.annot)
- Glasser, Matthew F. A multi-modal parcellation of human cerebral cortex. Nature 536, 171–178 (11 August 2016). http://www.nature.com/nature/journal/vaop/ncurrent/full/nature18933.html
- Mills, Kathryn (2016): HCP-MMP1.0 projected on fsaverage. figshare. https://dx.doi.org/10.6084/m9.figshare.3498446.v2 Retrieved: 08 57, Nov 22, 2016 (GMT)
6 Comments Add yours
HI, thank you for your beautiful webpages. I’m trying to process HCP-MNP with freesurfer and reached to this page.
I guess I can’t find the shell-script “create_subj_volume_parcellation.sh”, which is indicated to download.
Did you retrieved it? Or how can I get it?
Please consinder and I will be greateful if you let me know about this.
Thank you for your time.
Hi Daita, thanks for your comment! You can find the script in our figshare:
If you have any questions or need further information, please feel free to contact us!
Hi, Thank you so much for your useful introduction about how to use the HCP MMP1.0 map. I wanna ask after finishing this part, are all the masks in the structural image space? So the standard space in FSL is the structural image space, right? Thank you very much.
Hi, the process will be repeated for each subject specified, and the final masks will be in each subject’s native structural space, not in the standard MNI152 space!
Thank you so much for your reply. I have got the HCP MMP1.0 map for one subject based on this instruction. But when I opened the Left-Thalamus-Proper.nii.gz mask, Certainly it’s not the left thalamus part, which is bigger than the real thalamus and kind of like the whole-brain mask. Other masks are correct except the left and right thalamus part. Do you have any idea about this error? Thank you.
I really don’t know why this particular mask would be incorrect, it is extracted directly from the FreeSurfer subcortical segmentation. Unfortunately I am currently out of the lab and unable to check why that could be, but you could open the HCPMMP1.nii.gz file and check the voxel values of the thalami there. Left thalamus voxels should have a value of 10 (49 for the right thalamus). If that is the case, can you try to extract these regions with fslmaths to see if they come out right?