= This page is OBSOLETE: Segmentation of hippocampal subfields = == UPDATE - An enhanced version of this module, which also segments the nuclei of the amygdala, can be found in FreeSurfer 7. == '''See HippocampalSubfieldsAndNucleiOfAmygdala for the functionality found in [[https://surfer.nmr.mgh.harvard.edu/fswiki/ReleaseNotes|FreeSurfer 7]].''' '''''This functionality corresponds to !FreeSurfer 6.0 ''''' ''Author: Juan Eugenio Iglesias'' ''E-mail: e.iglesias [at] ucl.ac.uk'' ''Rather than directly contacting the author, please post your questions on this module to the FreeSurfer mailing list at freesurfer [at] nmr.mgh.harvard.edu'' If you use these tools in your analysis, please cite: * [[http://www.nmr.mgh.harvard.edu/~iglesias/pdf/subfieldsNeuroimage2015preprint.pdf|A computational atlas of the hippocampal formation using ex vivo, ultra-high resolution MRI: Application to adaptive segmentation of in vivo MRI]]. Iglesias, J.E., Augustinack, J.C., Nguyen, K., Player, C.M., Player, A., Wright, M., Roy, N., Frosch, M.P., McKee, A.C., Wald, L.L., Fischl, B., and Van Leemput, K. Neuroimage, 115, July 2015, 117-137. See also: LongitudinalHippocampalSubfields, BrainstemSubstructures <
> === Contents === 1. Motivation and General Description 1. Installation 1. Usage 1. Gathering the volumes from all analyzed subjects 1. Frequently asked questions 1. Test data <
> === 1. Motivation and General Description === This tool generates an automated segmentation of the hippocampal subfields based on a statistical atlas built primarily upon ultra-high resolution (~0.1 mm isotropic) ex vivo MRI data. This new method can take advantage of high-resolution, dedicated images when available (typically, but not necessarily, T2 weighted), and solves a number of limitations of the in vivo atlas that was distributed with FreeSurfer 5.1-5.3, namely: (a) The image resolution of the training data used to built the atlas was insufficient for the human labelers to completely distinguish the subfields, forcing them to heavily rely on geometric criteria to trace boundaries, which affected the accuracy of their annotations. On the ex vivo images, several of these boundaries are much better visualized, so the annotations are much more reliable. (b) Related to (a): a problematic consequence of the lack of resolution in the in vivo data was that the manual delineation protocol did not include the “molecular layer”, which corresponds to the stratum radiatum, lacunosum moleculare, hippocampal sulcus and molecular layer of the dentate gyrus, and which is also known as “dark band” due to its hypointense appearance in T2 MRI. The absence of the “molecular layer” in the atlas compromised the ability of the atlas to segment high-resolution in vivo data, since this layer is the key appearance feature describing the internal structure of the hippocampus. The new, ex vivo atlas does include this layer in the model. (c) The delineation protocol of the in vivo atlas was designed for the hippocampal body and did not translate well to the hippocampal head or tail. The new atlas was created with a new, specifically designed labeling protocol. (d) Due to issues (a), (b), and (c), the volumes of the subfield in the in vivo atlas did not agree well with those from histological studies (Simic, et al., 1997, Harding, et al., 1998). The volumes derived from the new atlas agree much better with these studies (see the Neuroimage paper). Here is a coronal slice of a sample T1-weighted 1 mm scan and the corresponding segmentations given by FreeSurfer 5.3 and FreeSurfer 6.0: <
> {{attachment:samples1.png}} <
><
> And here is is a coronal slice of a sample T2-weighted scan with 0.4 mm in-plane resolution (coronal) and 2 m slice thickness, along with the segmentation given by FreeSurfer 6.0 (FreeSurfer 5.3 could not be used to segment such scans): <
> {{attachment:samples2.png}} <
><
> === 2. Installation === The hippocampal subfield module requires the Matlab R2012 runtime; the runtime is free, and therefore '''NO MATLAB LICENSES ARE REQUIRED TO USE THIS SOFTWARE.''' Please note that, if you have already installed the runtime for the [[https://surfer.nmr.mgh.harvard.edu/fswiki/BrainstemSubstructures|brainstem module]], you do not need to install it again. Instructions for the installation of the runtime can be found here: https://surfer.nmr.mgh.harvard.edu/fswiki/MatlabRuntime <
> === 3. Usage === This software has three modes of operation, depending on whether you only have a T1 scan or you have an additional MRI volume (any MRI contrast supported) containing the hippocampus (ideally of higher resolution). * '''Mode A: only T1 scan used as input for recon-all is available. ''' All you need is to append the flag -hippocampal-subfields-T1 to your recon-all command. For example, to analyze your subject "bert", you would type: {{{ recon-all -all -s bert -hippocampal-subfields-T1 }}} Or, if Bert has already undergone the FreeSurfer pipeline (recon-all -all), you can just run: {{{ recon-all -s bert -hippocampal-subfields-T1 }}} The output will consist of six files (three for each hemisphere) that can be found under the subject's mri directory (in this example, $SUBJECTS_DIR/bert/mri/): ''[lr]h.hippoSfLabels-T1.v10.mgz'': they store the discrete segmentation volume (lh for the left hemisphere, rh for the right) at 0.333 mm resolution. ''[lr]h.hippoSfLabels-T1.v10.FSvoxelSpace.mgz'': they store the discrete segmentation volume in the FreeSurfer voxel space (normally 1mm isotropic, unless higher resolution data was used in recon-all with the flag -cm). ''[lr]h.hippoSfVolumes-T1.v10.txt'': these text files store the estimated volumes of the subfields and of the whole hippocampi. Note that [lr]h.hippoSfLabels-T1.v10.mgz covers only a patch around the hippocampus, at a higher resolution than the input image. The segmentation and the image are defined in the same physical coordinates, so you can visualize them simultaneously with (run from the subject's mri directory): {{{ freeview -v nu.mgz -v lh.hippoSfLabels-T1.v10.mgz:colormap=lut -v rh.hippoSfLabels-T1.v10.mgz:colormap=lut }}} On the other hand [lr]h.hippoSfLabels-T1.v10.FSvoxelSpace.mgz lives in the same voxel space as the other FreeSurfer volumes (e.g., orig.mgz, nu.mgz, aseg.mgz), so you can use it directly to produce masks for further analyses, but its resolution is lower than that of [lr]h.hippoSfLabels-T1.v10.mgz. <
> * '''Mode B: segmentation with an additional scan ''' If an additional MRI volume (e.g., a T2 scan, but it could be proton density, or even another T1) covering the hippocampi is available, we can use it to obtain a more reliable segmentation - particularly in the case in which its resolution is higher than that of the main T1 scan (even if anisotropic). In this case, the only requirement is that the additional scan is coarsely aligned to the main T1 scan. There are two sub-modes of operation, depending on whether we want to use the main T1 and the additional scan simultaneously in the segmentation (multispectral analysis), or if we only want to use the additional scan. The former is advised when the additional scan is of comparable resolution as the T1 scan, or when the additional scan does not cover the whole hippocampal region - in that case, the T1 information will be critical to segment the hippocampal regions outside the field of view of the additional volume (see for instance Figure 12e in the Neuroimage paper). The latter is advised when the additional scan is of higher resolution than the T1 volume and it covers the whole hippocampal region. The corresponding commands would be: * Multispectral segmentation: {{{ recon-all -s -hippocampal-subfields-T1T2 }}} * Using only additional scan: {{{ recon-all -s -hippocampal-subfields-T2 }}} The string is a user defined identifier that makes it possible to run different analysis with different types of additional scans. For example, you can run the command with a T2-weighted volume and use the identifier "T2", and then run it again with a PD-weighted volume and use the identifier "PD", such that both results will coexist in the subject's mri directory (see naming convention for the generated output below). '''For a certain modality of additional scan, make sure that you use the same ID for all the subjects within a study.''' Also, if you run the both the multispectral segmentation and the segmentation with the additional scan only, using the same additional scan in both cases, you can (should!) use the same analysisID. These commands generate the following outputs: ''.FSspace.mgz'': the additional scan, rigidly registered to the T1 data. ''[lr]h.hippoSfLabels--.v10.mgz'': they store the discrete segmentation volume at 0.333 mm resolution in the physical space of the FreeSurfer T1 data (and therefore of the aligned scan ''.FSspace.mgz'' as well). ''[lr]h.hippoSfLabels--.v10.FSvoxelSpace.mgz'': they store the discrete segmentation volume in the FreeSurfer voxel space (i.e., that of nu.mgz, aseg.mgz, etc). ''[lr]h.hippoSfVolumes--.v10.txt'': these text files store the estimated volumes of the subfields and of the whole hippocampi. In order to visualize these outputs: let's say that you have run an analysis with id ''T2ADNI''. Then, you can run: * Multispectral segmentation {{{ freeview -v nu.mgz -v T2ADNI.FSspace.mgz:sample=cubic \ -v lh.hippoSfLabels-T1-T2ADNI.v10.mgz:colormap=lut -v rh.hippoSfLabels-T1-T2ADNI.v10.mgz:colormap=lut }}} * Only additional scan {{{ freeview -v nu.mgz -v T2ADNI.FSspace.mgz:sample=cubic \ -v lh.hippoSfLabels-T2ADNI.v10.mgz:colormap=lut -v rh.hippoSfLabels-T2ADNI.v10.mgz:colormap=lut }}} <
> === 4. Gathering the volumes from all analyzed subjects === Once this module has been run on a number of subjects, it is possible to collect the volumes of the hippocampal substructures from all the subjects and write them to a single file - which can be easily read with a spreadsheet application. To do so, one would run: {{{ quantifyHippocampalSubfields.sh - }}} The first argument is the name of the analysis. For Mode A (i.e., based on main T1 scan), it is simply ''T1''. For Mode B, it would be ''T1-'' (for multispectral analysis) or just '''' (for segmentation based only on the additional scan). The argument corresponds to the text file where the table with the volumes will be written. The fields are separated by spaces. Finally, the third argument corresponds to the !FreeSurfer subjects directory that we want to analyze. This argument is not necessary if the environment variable SUBJECTS_DIR has been defined. <
> === 5. Frequently asked questions (FAQ) === * '''I have longitudinal MRI data of my subjects, at different time points. Is there a longitudinal version of this tool?''' Yes! Please check LongitudinalHippocampalSubfields. * '''Are you sure that this software does not require Matlab licenses? Why does it require the Matlab runtime, then?''' The software uses compiled Matlab code that requires the runtime (which is free), but no licenses. So, if you have a computer cluster, you can run hundred of segmentations in parallel without having to worry about Matlab licenses. And yes, this is all perfectly legal ;-) * '''The sum of the number of voxels of a given structure multiplied by the volume of a voxel is not equal to the volume reported in [lr]h.hippoSfVolumes*.txt.''' This is because the volumes are computed upon a soft segmentation, rather than the discrete labels in [lr]h.hippoSfLabels*.mgz. This is the same that happens with the main recon-all stream: if you compute volumes by counting voxels in aseg.mgz, you don't get the values reported in aseg.stats. * '''The size of the image volume of [lr]h.hippoSfLabels*.mgz (in voxels) is not the same as that of norm.mgz or the additional input scan.''' The segmentation [lr]h.hippoSfLabels*.mgz covers only a patch around the hippocampus, at a higher resolution than the input image. The segmentation and the image are defined in the same physical coordinates, so that is why you can still visualize them simultaneously with FreeView using the commands listed above. The software also gives [lr]h.hippoSfLabels*.FSvoxelSpace.mgz, which is in the same voxel space as the other !FreeSurfer volumes, in case you need it to produce masks for other processing. * '''I am interested in the soft segmentations (i.e., posterior probabilities), can I have access to them?''' Yes. All you need to do is to define an environment variable WRITE_POSTERIORS and set it to 1. For example, in tcsh or csh: {{{ setenv WRITE_POSTERIORS 1 }}} Or, in bash: {{{ export WRITE_POSTERIORS=1 }}} Then, the software will write a bunch of files under the subject's mri directory, with the format: ''posterior_side____v10.mgz'' * '''This module is CPU hungry''' Indeed! The deformation of the atlas towards the input scan(s) is parallelized, but recon-all by default limits operation to one thread (which is the polite mode of operation on a cluster). If you want to increase the number of cores that the software is allowed to use, you simply need to add this flag to the end of your recon-all command: {{{ -itkthreads 4 }}} where in this example usage of four threads is specified. You can set this to whatever number is optimal for your machine (two or four per core is typical). This flag sets the environment variable ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS. * '''What are the computational requirements to run this module?''' If the input is just a standard resolution (1mm) T1 from the main !FreeSurfer pipeline (i.e., no additional scans), then the software requires approximately 10GB of RAM memory to run. If a higher resolution T1 is processed with the flag -cm, or additional scans are used, then the exact amount of required RAM memory depends on the size and resolution of the scans. * '''The volume of the whole hippocampus obtained with this module is not equal to the value reported by the main !FreeSurfer pipeline in $SUBJECTS_DIR//stats/aseg.stats.''' Yes! The reason for this is that the volumes correspond to two different analyses. We have found the estimates from this module to be slightly more accurate than FreeSurfer's in an Alzheimer's disease discrimination task (see paper). * '''What image formats are supported for the additional scan?''' For now this software supports Nifti (.nii/.nii.gz) and !FreeSurfer format (.mgh/.mgz). * '''Do you store the transform between the original additional volume and the !FreeSurfer coordinate space?''' Yes! You can find it under: . $SUBJECTS_DIR//mri/transforms/T1_to_.v10.lta <
> * '''The registration between the T1 and the additional scan failed, i.e., the T1 and ''.FSspace.mgz'' do not overlap when I open them in Freeview.''' This can happen if the input additional scan and the T1 are not approximately registered in the first place. Please align the additional scan to the T1 (without resampling, please!) and re-run the analysis. If you use Freeview (recommended), you can use tools -> Transform Volume to manually register the images, then hit the "save as" button and check the option "Do not resample voxel data when saving" * '''How can I quickly check whether the registration has failed?''' In the subject's ''mri/transforms'' directory, the software writes an animated gif (''T1_to_.v10.QC.gif'') that can be used as quality control. It flips back and forth between a central coronal slice in the T1 scan and its corresponding slice in the T2 scan. If the two images are not aligned, the problem can be fixed by prealigning the additional scan to the T1 scan, as explained above. * '''I ran recon-all -all -hippocampal-subfields-T1/T2 and, after running for hours, the code stopped because I had not installed the Matlab runtime. Do I need to rerun everything?''' No! You can just run recon-all -hippocampal-subfields-T1/T2 (that is, without the -all). Of course, that would be after installing the runtime. * '''How reliable are the subfield volumes estimated from standard resolution (1 mm) T1 data?''' When segmenting 1 mm scans, the position of the internal boundaries between the hippocampal substructures largely relies on prior knowledge acquired from our ex vivo training data and summarized in our statistical atlas. For this reason, volumes of internal subfields (especially GC-DG, CA4 and molecular layer) must be interpreted with caution, and further validation with higher resolution data should ideally be carried out to confirm the results. On the other end of the spectrum, we have substructures such as the fimbria and tail, which are reliable at 1 mm. <
> === 6. Test data === Processed data of a single subject is available here: {{{ curl -O ftp://surfer.nmr.mgh.harvard.edu/pub/data/hipposubfields-testdata.tgz }}} The data is extracted with: {{{ tar zxvf hipposubfields-testdata.tgz }}} Note: within the Martinos Center, this data is found here, but should not be modified (make a copy) as it is used for testing: {{{ /autofs/cluster/freesurfer/subjects/test/hipposubfields }}} The data is one subject from the ADNI dataset, is fully recon-d, and also includes a thick-slice hi-res T2 image. The recon-all command used to produce the subfield data was: {{{ cd hipposubfields/ADNI_135_S_4863_20-Feb-2013 recon-all \ -s ADNI_135_S_4863_20-Feb-2013 \ -hippocampal-subfields-T1 \ -hippocampal-subfields-T1T2 mri/orig/T2cor-raw.mgz T1T2 \ -hippocampal-subfields-T2 mri/orig/T2cor-raw.mgz T2 }}} To view the data: {{{ cd hipposubfields/ADNI_135_S_4863_20-Feb-2013/mri freeview -v \ T1.mgz \ T2.FSspace.mgz:sample=cubic \ lh.hippoSfLabels-T1.v10.mgz:colormap=lut:visible=0 \ rh.hippoSfLabels-T1.v10.mgz:colormap=lut:visible=0 \ lh.hippoSfLabels-T1-T2.v10.mgz:colormap=lut \ rh.hippoSfLabels-T1-T2.v10.mgz:colormap=lut \ lh.hippoSfLabels-T2.v10.mgz:colormap=lut:visible=0 \ rh.hippoSfLabels-T2.v10.mgz:colormap=lut:visible=0 }}} Note that two of the result-types are not displayed by default. The check-boxes in freeview allow turning on/off each volume to allow comparing the segmentations under the three modes (T1-only, T1-T2 and T2-only).