= Segmentation of brainstem AAN nuclei =

''Authors: Mark D. Olchanyi, Juan Eugenio Iglesias, Emery N. Brown, Brian L. Edlow''

''E-mail(s): olchanyi [at] mit.edu''

''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://www.medrxiv.org/content/10.1101/2024.09.26.24314117v1|Histology-guided MRI segmentation of brainstem nuclei critical to consciousness]]. Mark David Olchanyi, Jean Augustinack, Robin L Haynes, Laura D Lewis, Nicholas Cicero, Jian Li, Christophe Destrieux, Rebecca D Folkerth, Hannah C Kinney, Bruce Fischl, Emery N Brown, Juan Eugenio Iglesias, Brian L Edlow, 
medRxiv; doi: https://doi.org/10.1101/2024.09.26.24314117

See also: [[BrainstemSubstructures]], [[ThalamicNuclei]], [[HippocampalSubfieldsAndNucleiOfAmygdala]]

<<BR>>

=== Contents ===

 1. Motivation and General Description
 2. Installation
 3. Tool usage
 4. Frequently asked questions (FAQ)

<<BR>>

=== 1. Motivation and General Description ===

The AANsegment tool generates automated segmentations of ten brainstem nuclei that are part of the ascending arousal network in MRI scans. The nuclei which we segment are listed below: 

 * ventral tegmental area (VTA) 
 * locus coeruleus (LC)
 * dorsal raphe (DR)
 * median raphe (MnR)
 * pontis oralis (PnO)
 * laterodorsal tegmental nucleus (LDTg)
 * parabrachial complex (PBC)
 * periaqueductal grey (PAG)
 * midbrain reticular formation (mRt) 
 * pedunculotegmental nucleus (PTg)

We generate segmentations with a Bayesian approach that uses a probabilistic atlas generated from five ex vivo brain specimens manually annotated with corresponding histopathological and immunohistochemical sections. Segmentations from various MRI sequences are illustrated below:

<<BR>> {{attachment:AAN_wiki_fig.png}} <<BR>><<BR>>

=== 2. Installation ===

This method requires the use of MATLAB 8.4 (2014b) runtime, which is completely free and does not require a MATLAB license. It can be downloaded from [[https://ssd.mathworks.com/supportfiles/downloads/R2014b/deployment_files/R2014b/installers/glnxa64/MCR_R2014b_glnxa64_installer.zip|https://ssd.mathworks.com/supportfiles/downloads/R2014b/deployment_files/R2014b/installers/glnxa64/MCR_R2014b_glnxa64_installer.zip]]. Further instructions to how to install MATLAB runtime can be found here: [[https://surfer.nmr.mgh.harvard.edu/fswiki/MatlabRuntime|https://surfer.nmr.mgh.harvard.edu/fswiki/MatlabRuntime]]

<<BR>>

=== 3. Tool Usage ===

We are in the process of integrating the method into a python framework, but as of current, you can run the method by calling the segmentation shell script:

{{{
SegmentAAN.sh <SUBJECT_ID> <SUBJECT_DIR> 
}}}

where <SUBJECT_ID> is the FreeSurfer subject folder name and <SUBJECT_DIR> is the directory where the subject folder is stored. <SUBJECT_DIR> is only necessary if it has not been set as an environment variable, or if you want to override it. For standard usage, the method requires a T1 volume and corresponding ASEG volume generated from the FreeSurfer recon-all stream, which is ran with the following command:

{{{
recon-all -all -s <SUBJECT_ID> 
}}}

The method will output three files:

 * ''arousalNetworkLabels.atlas_v10.mgz'': The segmentation output at 0.365mm resolution.
 * ''arousalNetworkLabels.atlas_v10.FSvoxelSpace.mgz'': The segmentation output in native resolution space (i.e., the resolution of your FreeSurfer volumes).
 * ''arousalNetworkVolumes.atlas_v10.txt'': A text file consisting of spatial volumes (in mm^3) of each arousal nucleus (split into left-right subdivisions) as well as the whole arousal network.

To visualize the output with Freeview, use the following line: 

{{{
freeview -v $SUBJECTS_DIR/$SUBJECT/T1.mgz -v  $SUBJECTS_DIR/$SUBJECT/arousalNetworkLabels.$SUFFIX.mgz:colormap=lut:lut=$FREESURFER_HOME/average/AAN/atlas/freeview.lut.txt
}}}

Where $SUFFIX is the segmentation you wish to visualize (i.e., ''atlas_v10'' or ''atlas_ v10.FSvoxelSpace''). We use a custom lookup-table for coloring each nucleus, which can be found in $FREESURFER_HOME/average/AAN/atlas/freeview.lut.txt. 

<<BR>>

=== 4. Frequently asked questions (FAQ) ===

 * '''How can I speed up computation?'''

By default, deformation of the probabilistic atlas is done with one core. If you want to parallelize the deformation with multiple cores, you can set the environment variable ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS to the number of threads you want to use. With, for example, 8 cores), this would be achieved with:

With bash:

{{{
export ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=8
}}}

With csh/tcsh:

{{{
setenv ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS 8
}}}

 * '''Which MRI sequences can I run this on?'''

Theoretically, any! However, your results may vary. We have so far tested the method on T1w, T2w, dMRI low-b, and SWI sequences with good outcomes. See the preprint for more information.