Segmentation of hypothalamic subunits

This functionality is available in FreeSurfer 7.2.

Author: Benjamin Billot

E-mail: benjamin.billot.18 [at]

Rather than directly contacting the author, please post your questions on this module to the FreeSurfer mailing list at freesurfer [at]

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


  1. General Description
  2. Installation
  3. Usage
  4. Frequently asked questions

1. General Description

This tool enables automated segmentation of the hypothalamus and its associated subunits in 3D T1-weighted scans of approximately 1mm isotropic resolution. It uses a convolutional neural network, which enables computing segmentations in a very short processing time (around 10 seconds with a CPU, less than a second with a GPU). More specifically, this code produces segmentation maps for five subregions (with distinct right/left labels), which comprise the following hypothalamic nuclei:


Left label

Right label

Associated nuclei




suprachiasmatic nucleus; supraoptic nucleus (SON)




preoptic area; paraventricular nucleus (PVN)




mamillary body (including medial and lateral mamillary nuclei); lateral hypothalamus; tuberomamillary nucleus (TMN)

Inferior tubular



infundibular (or arcuate) nucleus; ventromedial nucleus; SON; lateral tubular nucleus; TMN

Superior tubular



dorsomedial nucleus; PVN; lateral hypothalamus

The segmentation model was trained by applying aggressive data augmentation, which makes it robust against variability in acquisition parameters (sequence, platform, bias field, head positioning), and in anatomy (e.g. atrophy patterns linked to ageing or different pathologies). The following figure illustrates two segmentation examples in coronal slices obtained by this model for a control subject, and a subject diagnosed with Alzheimer's disease:


2. Installation

The first time you run this module, it will prompt you to install Tensorflow. Simply follow the instructions in the screen to install the CPU or GPU version.

If you have a compatible GPU, you can install the GPU version for faster processing, but this requires installing libraries (GPU driver, Cuda, CuDNN). These libraries are generally required for a GPU, and are not specific for this tool. In fact you may have already installed them. In this case you can directly use this tool without taking any further actions, as the code will automatically run on your GPU.

3. Usage

This software can be used in two modes:

The first mode follows the FreeSurfer subject directory structure and works on the bias field corrected images (nu.mgz). We recommend using this mode if you are running the main FreeSurfer recon-all scripts on your data. The second mode is more flexible and has the advantage of not having to run subjects through recon-all, if you are only interested in the hypothalamus.

Important: the network has been trained on image at approximately 1mm isotropic resolution, so it would be underperforming if presented with images of higher/lower resolutions. Depending on the version of FreeSurfer (but regardless of the used mode, i.e., FreesSurfer or any-T1), there are several options:

mri_convert <path input image> <path resampled image> --voxsize 1 1 1 -odt float

We now describe what command to use in the different modes. A summary of the following information can be found simply by typing:

mri_segment_hypothalamic_subunits -h

a. FreeSurfer subjects

This tool can be run on subjects that have been analyzed beforehand with the main FreeSurfer stream (i.e. “recon-all”). Therefore, we will assume that a command similar to the following one has already been run on each subject for which we want to segment the hypothalamic subunits:

recon-all -all --s <subject_name>

To analyze one or several subjects, simply use:

mri_segment_hypothalamic_subunits --s <subject_name> --sd <subjects_dir> --write_posteriors --threads <threads> --cpu


When running on a subject analysed with FreeSurfer, this software automatically saves the segmentation and volumes of the hypothalamic subunits in the FreeSurfer directory structure.

Important: if several subjects are processed, the outputs will be saved in each subject's directory. Additionally, a CSV file regrouping the volumes of all structures for all subjects will be saved under:


Segment all subjects in $SUBJECTS_DIR:

mri_segment_hypothalamic_subunits --s

Segment a single subject bert:

mri_segment_hypothalamic_subunits --s bert

Segment several subjects (bert and ernie):

mri_segment_hypothalamic_subunits --s bert ernie

Segment a single subject bert located in a subject directory other than $SUBJECTS_DIR:

mri_segment_hypothalamic_subunits --s bert --sd /home/user1/data/new_analysis/

Segment all subjects located in a subject directory other than $SUBJECTS_DIR:

mri_segment_hypothalamic_subunits --s --sd /home/user1/data/new_analysis/

b. Any T1 scan

You can also run this on a T1 scan that has not been processed with FreeSurfer. This tool works on scans with or without preprocessing (e.g., bias field correction, skull stripping, normalization, template registration, etc.). Depending on the version of FreeSurfer you use, there are two ways to call mri_segment_hypothalamic_subunits.

For FreeSurfer 7.2 or lower, the command line is:

mri_segment_hypothalamic_subunits --i <input> --o <output> --out_posteriors <post> --out_volumes <vol> --threads <threads>


Important: If you wish to process several scans in the any-T1 mode, we highly recommend that you put them in a single folder, rather than calling mri_segment_hypothalamic_subunits individually on each scan. This will save the time required to set up the software for each scan.

For the dev version, the command line is:

mri_segment_hypothalamic_subunits --i <input> --o <output> --post <post> --resample <resample> --vol <vol> --threads <threads> --cpu


Important 1: If you wish to process several scans in the any-T1 mode, we highly recommend that you put them in a single folder, rather than calling mri_segment_hypothalamic_subunits individually on each scan. This will save the time required to set up the software for each scan.

Important 2: Because hypothalamus_seg may resample the images at 1mm isotropic resolution, some viewers will not display them correctly when overlaying the segmentations on the original images. If that’s the case, you can use the --resample flag to obtain a resampled image that lives in the same space as the segmentation, such that any viewer can be used to visualize them together.


Segment a single scan:

mri_segment_hypothalamic_subunits --i /home/user1/data/scan.mgz --o /home/user1/data/seg.mgz

Segment a single scan, and save the resampled image and volumes:

mri_segment_hypothalamic_subunits --i /home/user1/data/scan.mgz --o /home/user1/data/seg.mgz --resample /home/user1/data/image_1mm3.mgz --vol /home/user1/data/hypothalamic_volumes.csv

Segment all scans contained in a folder, and save the posteriors and the volumes:

mri_segment_hypothalamic_subunits --i /home/user1/data/scans/ --o /home/user1/data/segmentations/ --post /home/user1/data/posteriors/ --vol /home/user1/data/hypothalamic_volumes.csv

4. Frequently asked questions (FAQ)

SO FAR, EXPERIENCE SHOWS THAT ALL BAD RESULTS ARE DUE TO INPUT SCANS AT RESOLUTION DIFFERENT THAN 1MM. That is actually why we implemented the internal resampling in the dev version. So if you're using FreeSurfer 7.2 or lower, please make sure that the input scans are at 1mm isotropic resolution. If the problem still persists, or if the results are bad and you use the dev version, please let us know, we'd be delighted to help you and to make our tool stronger ! :)

No! Because we applied aggressive augmentation during training (see paper), this tool is able to segment both processed and unprocessed data. So there is no need to apply bias field correction, skull stripping, or intensity normalization.

This is because the volumes are computed upon a soft segmentation, rather than the discrete segmentation. The same 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.

This tool can be run on Nifti (.nii/.nii.gz) and FreeSurfer (.mgz) scans.

In this case, the module segments nu.mgz, which is corrected for bias field.

If you have a multi-core machine, you can increase the number of threads with the --threads flag (up to the number of cores).

This is because the network has been trained to segment at this resolution, and could be underperforming if presented with images of different resolutions. Actually, only the images with resolutions outside the range [0.95, 1.15] are resampled. We highlight that the resampling is performed internally to avoid the dependence on any external tool.

This is probably of problem of image viewer, in the case where the images have been resampled to 1mm resolution. Indeed, if images are resampled, their segmentations are given at 1mm resolution (so not the same as the input image), and some viewers cannot cope with resolution changes. In that case we recommend to use the --resample flag to save the resamplde images, or simply to use FreeView (shipped with FreeSurfer), which is resolution-aware !