## Please edit system and help pages ONLY in the master wiki!
## For more information, please see MoinMoin:MoinDev/Translation.
## IMPORTANT NOTE:
## When you use this page as a template for creating your project page:
##  * please remove all lines starting with two hashes (##)
##  * except the acl line, please keep that, but remove one hash, so it reads #acl ...
##  * fix the acl line so it has the correct page instead of the sample Project/...Group
##acl Project/AdminGroup:admin,read,write,delete,revert Project/ReadWriteGroup:read,write Project/ReadGroup:read
##master-page:Unknown-Page
##master-date:Unknown-Date
#format wiki
#language en

= Subregion Segmentation (currently a BETA version) =
Cross-sectional and longitudinal segmentation for the following structures: thalamus, brainstem, hippo-amygdala. This single python program will supercede the individual matlab-based programs for each structure. The results will be very close but not identical to the matlab-based routines. This is currently a beta version, meaning that we have thoroughly tested it but it has not been used externally yet.

Also, please note that the current version cannot take advantage of images other than T1 scans. If you want to use eg higher resolution T2 scans for hippocampal subfield sedimentation, please use the Matlab code.

'''''This functionality is available in [[https://surfer.nmr.mgh.harvard.edu/fswiki/ReleaseNotes|FreeSurfer 7.3+]].'''''

If you use these tools in your analysis, please cite:

 * Thalamus: [[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).

 * Hippocampus: [[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., Mc Kee, A.C., Wald, L.L., Fischl, B., and Van Leemput, K. Neuroimage, 115, July 2015, 117-137.

 * Amygdala: [[http://www.nmr.mgh.harvard.edu/~iglesias/pdf/AmygdalaAtlas.pdf|High-resolution magnetic resonance imaging reveals nuclei of the human amygdala: manual segmentation to automatic atlas]]. Saygin ZM & Kliemann D (joint 1st authors), Iglesias JE, van der Kouwe AJW, Boyd E, Reuter M, Stevens A, Van Leemput K, Mc Kee A, Frosch MP, Fischl B, Augustinack JC. Neuroimage, 155, July 2017, 370-382.

 * Brainstem: [[http://www.nmr.mgh.harvard.edu/~iglesias/pdf/Neuroimage_2015_brainstem.pdf|Bayesian segmentation of brainstem structures in MRI]]. Iglesias, J.E., Van Leemput, K., Bhatt, P., Casillas, C., Dutt, S., Schuff, N., Truran-Sacrey, D., Boxer, A., and Fischl, B.  NeuroImage, 113, June 2015, 184-195.

 * Longitudinal method: [[http://www.nmr.mgh.harvard.edu/~iglesias/pdf/Neuroimage_2016_longitudinal.pdf|Bayesian longitudinal segmentation of hippocampal substructures in brain MRI using subject-specific atlases]]. Iglesias JE, Van Leemput K, Augustinack J, Insausti R, Fischl B, Reuter M. Neuroimage, 141, November 2016, 542-555.

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

<<BR>>

=== 1. Motivation and General Description ===
This tool is a single-program python reimplementation of our cross-sectional and longitudinal subregion segmentation tools for the thalamus, hippo-amygdala, and brainstem regions and ports their implementation (was implemented in Matlab). This subregion segmentation tool accomplishes the following:

(a) This tool produces a segmentation of the thalamus into 25 different nuclei, using a probabilistic atlas built with histological data. The segmentation 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.

(b) The tool uses a probabilistic atlas built with ultra-high resolution ex vivo MRI data (~0.1 mm isotropic) to produce an automated segmentation of the hippocampal substructures and the nuclei of the amygdala. The tool can use high-resolution images when available (typically, but not necessarily, T2 weighted).

(c) This tool generates an automated segmentation of four different brainstem structures from the input T1 scan: medulla oblongata, pons, midbrain and superior cerebellar peduncle (SCP). We use a Bayesian segmentation algorithm that relies on a probabilistic atlas of the brainstem (and neighboring brain structures) built upon manual delineations of the structures on interest in 49 scans (10 for the brainstem structures, 39 for the surrounding structures).


=== 2. 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. If we want to use the longitudinal version of this tool described in (Iglesias et al., Neuroimage, 2017), then it is also a requirement that the data have been processed with the longitudinal stream of !FreeSurfer (LongitudinalProcessing).

In !FreeSurfer 7.3+, this module is called independently from recon-all. To analyze your subject "bert", you would simply type:

{{{
segment_subregions [STRUCTURE]  [SUBJ]
}}}

The required arguments [STRUCTURE] has 3 possible options: thalamus, hippo-amygdala, and brainstem, while [SUBJ] would be your subject name, in this case $SUBJECT_DIR/bert.

To segment the thalamic nuclei for subject bert, for example, in a cross-sectional analysis:

{{{
segment_subregions thalamus --cross bert
}}}

Similarly, for a longitudinal analysis, run:

{{{
segment_subregions thalamus --long-base base
}}}

Subject timepoints will be automatically inferred from the base subject's `base-tps` file. Output segmentations and computed structure volumes will be saved to the subject's `mri/` subdirectory.


=== 3. Command Arguments ===

||'''Required Positional'''||||
||structure ||Structure to segment: can be `thalamus`, `hippo-amygdala`, or `brainstem`. ||
||'''Mutually Exclusive'''||||
||--cross SUBJ ||Subject to segment in cross-sectional analysis. ||
||--long-base SUBJ ||Base subject for longitudinal analysis. Time-points are inferred automatically. ||
||'''Optional Arguments'''||||
||--sd SD ||Specify subjects directory (will override SUBJECTS_DIR env variable). ||
||--suffix SUFFIX ||Optional output file suffix. ||
||--out-dir DIR ||Use alternative output directory (only for cross-sectional). Default is the subject's `mri` directory. ||
||--debug  ||Write intermediate debugging outputs. ||
||--temp-dir DIR ||Use alternative temporary directory for debugging (but this will get deleted unless --debug is enabled). ||
||--threads THREADS ||Number of threads to use. Defaults to 1. ||
||-h, --help ||Show this help message and exit. ||


=== 4. Gathering / merging results from several subjects ===
Please see ConcatenateSubregionsResults