= Segmentation of thalamic nuclei =
'''''We are working on a single Python program that unifies all the subregion segmentation modules; please see: [[https://surfer.nmr.mgh.harvard.edu/fswiki/SubregionSegmentation]].'''''
<
>
<
>
'''''PLEASE NOTE THAT:'''''
<
>
'''''1. THERE IS A BUG IN quantifyThalamicNuclei.sh IN FREESURFER 7.0, 7.1 AND 7.1.1; PLEASE REPLACE $FREESURFER_HOME/bin/quantifyThalamicNuclei.sh BY THIS FILE: [[attachment:quantifyThalamicNuclei.sh]] (no need to rerun your subjects!)'''''
<
>
'''''2. PLEASE NOTE THAT THIS MODULE WAS MODIFIED WITH THE FREESURFER 7 RELEASE (COMPARED WITH OLDER DEV VERSIONS) FOR IMPROVED SEGMENTATION OF THE MOST LATERAL NUCLEI, INCLUDING THE LGN.'''''
<
>
'''''3. AN UPDATED METHOD FOR [[https://freesurfer.net/fswiki/ThalamicNucleiDTI|JOINT STRUCTURAL AND DIFFUSION DATA]] IS AVAILABLE FROM FREESURFER 7.4 ONWARDS.'''''
<
>
<
>
''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:
* [[https://arxiv.org/abs/1806.08634|A probabilistic atlas of the human thalamic nuclei combining ex vivo MRI and histology]]. Iglesias, J.E., Insausti, R., Lerma-Usabiaga, G., Bocchetta, M., Van Leemput, K., Greve, D., van der Kouwe, A., Caballero-Gaudes, C., Paz-Alonso, P. Neuroimage (accepted).
See also: HippocampalSubfieldsAndNucleiOfAmygdala, BrainstemSubstructures, [[https://freesurfer.net/fswiki/ThalamicNucleiDTI|ThalamicNucleiDTI]]
<
>
=== Contents ===
1. Motivation and General Description
2. Installation
3. Usage
4. Gathering the volumes from all analyzed subjects
5. Frequently asked questions
6. Multimodal integration
7. Test data
<
>
=== 1. Motivation and General Description ===
This tool produces a parcellation of the thalamus into 25 different nuclei, using a probabilistic atlas built with histological data. The parcellation is based on structural MRI, either the main T1 scan processed through recon-all, or an additional scan of a different modality, which potentially shows better contrast between the nuclei. For example, we have observed good contrast with FGATIR sequences, or those used in deep brain stimulation (DBS). The main feature exploited by the atlas is the boundary between the mediodorsal and pulvinar nuclei, and the rest of the nuclei:
<
> {{attachment:t1seg.png||height="300"}} <
><
>
Another example, using a DBS scan:
<
> {{attachment:DBSseg.png||height="270"}} <
><
>
We note that, at this point, the code cannot exploit information in diffusion MR data - this feature has been developed in a separate module [[https://freesurfer.net/fswiki/ThalamicNucleiDTI|ThalamicNucleiDTI]].
<
>
=== 2. Installation ===
This module requires the Matlab R2014b runtime, which 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/HippocampalSubfieldsAndNucleiOfAmygdala|hippocampal subfield / amygdala]] or [[https://surfer.nmr.mgh.harvard.edu/fswiki/BrainstemSubstructures |brainstem modules]], 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 requires that a whole brain T1 scan of the subject has been analyzed with the main !FreeSurfer stream ("recon-all"), i.e., we will assume that the command similar to this has already been run:
{{{
recon-all -all -s bert
}}}
where bert is the name of the subject. Bear in mind that, if this T1 scan has a voxel size smaller than 1 mm, it is possible to exploit this higher resolution by using the flag -cm in recon-all. Otherwise, both recon-all and this tool will work with a resampled version of the T1 volume at 1mm isotropic resolution.
This thalamic segmentation tool has two modes of operation: 1. Using only the main T1 volume processed with recon-all (norm.mgz); 2. Using an additional MRI volume (any MRI contrast supported; this scan ideally shows superior contrast between the thalamic nuclei).
* '''Usin the T1 scan from recon-all '''
To analyze your subject "bert", you would simply type:
{{{
segmentThalamicNuclei.sh bert [SUBJECTS_DIR]
}}}
where the second argument is optional, and can be used to override the !FreeSurfer subject directory.
The output will consist of the following three files, which can be found under the subject's mri directory (in this example, $SUBJECTS_DIR/bert/mri/):
''ThalamicNuclei.v12.T1.volumes.txt'': this text file stores the estimated volumes of the thalamic nuclei.
''ThalamicNuclei.v12.T1.mgz'': stores the discrete segmentation volumes at subvoxel resolution (0.5 mm).
''ThalamicNuclei.v12.T1.FSvoxelSpace.mgz'': stores 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).
In addition, it will generate files in the stats folder: thalamic-nuclei.lh.v12.T1.stats and thalamic-nuclei.rh.v12.T1.stats. Group data can be aggregated with something like
{{{
asegstats2table --statsfile=thalamic-nuclei.lh.v12.T1.stats --tablefile=thalamic-nuclei.lh.v12.T1.dat --subjectsfile=subjectlist
}}}
This will create a file called thalaic-nuclei.lh.v12.T1.dat with a subject for each row and the column being the volume of the given nucleus
'''Discrete segmentation''' means a segmentation where there is one label for each voxel. Note that ThalamicNuclei.v12.T1.mgz only covers a patch around the thalamus, 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 ThalamicNuclei.v12.T1.mgz:colormap=lut
}}}
On the other hand ThalamicNuclei.v12.T1.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 (1 mm vs 0.5 mm).
<
>
* '''Using an additional scan '''
If an additional MRI volume (e.g., a FGATIR scan, or a DBS scan) is available, we can use it to obtain a more reliable segmentation - particularly in the case in which its contrast is higher than that of the main T1 scan around the thalamus. In this case, the only requirement is that the additional scan is coarsely aligned to the main T1 scan.
To analyze subject bert, the command would be:
{{{
segmentThalamicNuclei.sh bert [SUBJECTS_DIR] FILE_ADDITIONAL_SCAN ANALYSIS_ID BBREGISTER_MODE
}}}
FILE_ADDITIONAL_SCAN is the additional scan to use in the segmentation, in Nifty (.nii/.nii.gz) or !FreeSurfer format (.mgh/.mgz).
ANALYSIS_ID 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 DBS volume and use the identifier "DBS", and then run it again with a FGATIR volume and use the identifier "FGATIR", 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 please note that it is possible to run multiple instances of segmentThalamicNuclei.sh in parallel, using different additional scans and ANALYSIS_ID identifiers'''. As in the T1 case, SUBJECTS_DIR is optional, and overrides the !FreeSurfer subject directory when provided.
BBREGISTER_MODE: this module relies on [[https://surfer.nmr.mgh.harvard.edu/fswiki/bbregister|BBregister]] for the registration of the additional scan to the main T1 volume. This argument specifies the contrast of the additional scan, and can be equal to 't1', 't2', or 'none'. Modes 't1' and 't2' map directly to the corresponding BBregister contrast flags, which specifies whether white matter is brighter than gray matter (t1 mode) or the other way around (t2 mode). Note that the additional volume does not have to be a T1 or T2 scan; for example, a FGATIR scan like the one in the figure above would be processed with the 't2' flag, since the gray matter is brighter than the white matter. Finally, the third mode (''none'') skips the registration (i.e., assumes that the additional scan has already been registered to the main FreeSurfer T1), and is therefore compatible with any MRI contrast.
This command generates the same three volumes as the T1 version, but also two additional volumes corresponding to the registered/resampled additional scan:
''ThalamicNuclei.v12..volumes.txt'': text file with estimated volumes.
''ThalamicNuclei.v12..mgz'': discrete segmentation at 0.5 mm.
''ThalamicNuclei.v12..FSvoxelSpace.mgz'': discrete segmentation volume in FreeSurfer voxel space.
''.thalamus..mgz'': registered additional volume, resampled to the FreeSurfer voxel space./
''.thalamus..stripped.bfcorr.mgz'': skull stripped and bias field corrected version of the volume above.
The stats file will be stats/thalamic-nuclei.lh.v12..stats. The asegstats2table command should be adjusted accordingly.
In order to visualize the outputs: let's say that you have run an analysis with id ''FGATIR'', and bbregister mode ''t2''. Then, you can for example run the following command from the subject's mri directory:
{{{
freeview -v nu.mgz -v FGATIR.thalamus.t2.mgz -v FGATIR.thalamus.t2.stripped.bfcorr.mgz -v ThalamicNuclei.v12.FGATIR.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 thalamic nuclei of all subjects and write them to a single file - which can be easily read with a spreadsheet application. This can be done with ConcatenateSubregionsResults (please note that our older tool quantifyThalamicNuclei.sh is deprecated).
<
>
=== 5. Frequently asked questions (FAQ) ===
* '''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 ThalamicNuclei.v12.T1.volumes.txt.'''
This is because the volumes are computed upon a soft segmentation, rather than the discrete labels in ThalamicNuclei.v12..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 ThalamicNuclei.v12..mgz (in voxels) is not the same as that of norm.mgz or the additional input scan.'''
The segmentations cover only a patch around the thalamus, 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 ThalamicNuclei.v12..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 (big!) bunch of files under the subject's mri directory, with the format: ''posterior_*.mgz''
* '''This module is CPU hungry'''
Indeed! The deformation of the atlas towards the input scan(s) can be parallelized but by default it will use only one CPU. If you want to set the number of cores / threads that are used, you can do that through the environment variable ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS. For example, to use two cores (tcsh/csh):
{{{
setenv ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS 2
}}}
Or, in bash:
{{{
export ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=2
}}}
* '''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 8GB 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 thalamus 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. It is in the subject's ''mri/transforms'' directory, with the name: ..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 means that bbregister failed; it is very unusual, but it can happen, particularly if the input additional scan and the T1 are not approximately registered in first place. In that case, you have two options: 1. pre-registering the images yourself with your favorite registration tool, and re-running the thalamic segmentation with BBREGISTER_MODE set to ''none''; and 2. manually (and coarsely) aligning the additional scan to the T1 (without resampling, please!) and re-running 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-..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.
* '''How reliable are the the volumes estimated from standard resolution (1 mm) T1 data?'''
The main image feature when subdiving the thalamus is the boundary between the mediodorsal and pulvinar nuclei, and all other nuclei. This boundary is faint, but visible in most T1 scans. Other than this internal boundary and the external edge of the thalamus, the segmentation needs to rely on prior knowledge encoded in the atlas. We have found the segmentations to be quite consistent.
* '''Do the volume of thalamic nuclei need to be corrected for ICV (either by including ICV as a covariate or taking the ratio of each nucleus to the ICV)? If so, might it make more sense to correct them (perhaps take the ratio of each subfield to the whole thalamus) for the volume of the thalamus (after the thalamus itself has been corrected for the ICV)? '''
Yes, volumes of thalamic nuclei need to be corrected for ICV. If you’re correcting the nuclei by whole thalamic volume: a) the question is a different one (“which fraction of the thalamic volume is attributed to each nucleus”); and b) I would not correct by ICV, because the values are already fractions / normalized (see point a).
<
>
* '''Does this module have a multispectral mode, i.e., processing the T1 and additional scans simultaneously?'''
No. We conducted some experiments and using both images simultaneously did not seem to help much, compared with using the additional volume alone.
* '''Can this module exploit structural connectivity information derived from diffusion MRI to parcellate the thalamus?'''
We released a module for the segmentation of [[https://freesurfer.net/fswiki/ThalamicNucleiDTI|joint structural and diffusion imaging]] in FreeSurfer 7.4. Whilst this new module incorporates diffusion information in the form of diffusion tensor images combined with a probabilistic tract atlas, it does not explicitly require generation of structural connectivity maps through tractography.
=== 6. Multimodal integration ===
To extract values within the nuclei from another modality (eg, DTI or fMRI), use vol2subfield. Run with --help for examples.
For old users of development versions: vol2subfield is not in FS version 6, but you can get it from https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/6.0.0-patch/vol2subfield
=== 7. Test data ===
Coming soon ...