| Deletions are marked like this. | Additions are marked like this. |
| Line 72: | Line 72: |
|
{{{--use_cuda}}}: Use Cuda for GPU support {{{--center_crop}}}: Use image center for crop window instead of the mni152 crop template {{{--logfile}}}: set basename of logfiles; default is mri_pglands_seg.log {{{--lut}}}: Path to lookup-table (lut); default is pglands.ctab {{{--mni_template}}}: MNI label template used to set crop window; default is mni152_label_template.mgz {{{--mni_template_transform}}}: Path to affine transform for registering the mni label template to subject space. This will override the default syntax, and will apply the transform to all subjects. {{{--outbase}}}: String to use in output filename; default is "pglands" {{{--robust_norm_percent}}}: Percentile for robust normalization of input image intensities; default is 0.95 {{{--write_posteriors}}}: Flag to save label posteriors (i.e., the softmax of the output logits from the model) {{{--write_qa_stats}}}: Flag to calculate and write QA stats {{{--qa_transform}}}: Deformation from subject to mni152 space to perform QA analysis on output segmentation. Can either be a path to a single image or a suffix (will search output directory for matching filename) {{{--write_vol_stats}}}: Flag to calculate and save label volumes {{{--etiv}}}: Flag to include eTIV in volume stats; default is true in FS mode and false in normal mode. If set to true in normal mode, it will significantly increase run time {{{--tal}}}: Alternative talairach xfm transform for estimating eTIV. Can either be a path to a single transform or a suffix (will search output directory for matching filename) |
||{{{--use_cuda}}}|| Use Cuda for GPU support || ||{{{--center_crop}}}|| Use image center for crop window instead of the mni152 crop template || ||{{{--logfile}}}|| set basename of logfiles; default is mri_pglands_seg.log || ||{{{--lut}}}|| Path to lookup-table (lut); default is pglands.ctab || ||{{{--mni_template}}}|| MNI label template used to set crop window; default is mni152_label_template.mgz || ||{{{--mni_template_transform}}}|| Path to affine transform for registering the mni label template to subject space. This will override the default syntax, and will apply the transform to all subjects || ||{{{--outbase}}}|| String to use in output filename; default is "pglands" || ||{{{--robust_norm_percent}}}|| Percentile for robust normalization of input image intensities; default is 0.95 || ||{{{--write_posteriors}}}|| Flag to save label posteriors (i.e., the softmax of the output logits from the model) || ||{{{--write_qa_stats}}}|| Flag to calculate and write QA stats || ||{{{--qa_transform}}}|| Deformation from subject to mni152 space to perform QA analysis on output segmentation. Can either be a path to a single image or a suffix (will search output directory for matching filename) || ||{{{--write_vol_stats}}}|| Flag to calculate and save label volumes || ||{{{--etiv}}}|| Flag to include eTIV in volume stats; default is true in FS mode and false in normal mode. If set to true in normal mode, it will significantly increase run time || ||{{{--tal}}}|| Alternative talairach xfm transform for estimating eTIV. Can either be a path to a single transform or a suffix (will search output directory for matching filename) || |
| Line 89: | Line 90: |
|
--crop_patch_size: Isotropic size (# of voxels) for crop window; default is 96, which is expected by our model --model: Path to trained model; default is pglands_seg.pth |
||{{{--crop_patch_size}}}|| Isotropic size (# of voxels) for crop window; default is 96, which is expected by our model || ||{{{--model}}}|| Path to trained model; default is pglands_seg.pth || |
Contents
Introduction
This page describes mri_pglands_seg, a deep learning tool within FreeSurfer to automatically segment the pituitary and pineal glands in a T1-weighted image. Specifically, the pipeline target four structures: the anterior pituitary, posterior pituitary, infundibulum, and pineal gland (see below).
The package requires installation of FreeSurfer version 8.1 or later.
Those using this toolbox should cite: Automated Segmentation of the Pituitary and Pineal Glands. Larson, KL, Augustinack, JC, Mora, J, Shahzade, D, Rapalino, O, Fischl, B, Greve, DN. Human Brain Mapping 46, no. 15: e70384. 10.1002/hbm.70384. https://doi.org/10.1002/hbm.70384. PDF available here.
Basic Usage
There are two ways to run mri_pglands_seg, referred to as "normal mode" and "FreeSurfer mode". In normal mode, the user can specify one or more T1-weighted input images and either a single output directory or a corresponding list of output paths:
mri_pglands_seg --i <input1> ... <inputN> --o <output_dir>
or
mri_pglands_seg --i <input1> ... <inputN> --o <output1> ... <outputN>
If specifying a single input directory instead of a list of images, mri_pglands_seg will attempt to perform segmentation on all files within that directory with valid file extensions (e.g., .mgz, .mgh, .nii, .nii.gz).
Alternatively, FreeSurfer mode allows the user to perform segmentation on subjects processed with the recon-all pipeline, and assumes the standard filename conventions. Instead of supplying a list of inputs and outputs, the user can specify a list of subjects and the SUBJECTS_DIR environment variable (if not already set).
mri_pglands_seg --s <subjectid1> ... <subjectidN> --sd <SUBJECTS_DIR>
The output label maps for each subject will automatically be written to <SUBJECTS_DIR>/<subjectid>/mri/T1.pglands.mgz. The user can also supply an output directory as in normal mode; this will fource all outputs to be written to <output_dir>/<subjectid>.T1.pglands.mgz.
Volume stats
To record the volumes (mm3) of each segmented structure, run mri_pglands_seg with the --write_vol_stats flag, e.g.:
mri_pglands_seg --s <subjectid> --write_vol_stats
This will produce a table in the standard .stats file format with the label value, estimated volume, and number of voxels for each label. The user can also specify --etiv to include the estimated total intracranial volume for that subject within the output stats file. This is automatically included when running in FS mode.
Quality Assurance
The best way to assess the quality of predicted segmentations is to visualize all outputs using the freeview command within FreeSurfer (or your favorite viewing program). Because it can be tedious to view every single result for large datasets, we incorporated a quality assurance (QA) procedure that automatically assigns a "QA score" indicating the accuracy of each segmentations. To run this, use the --write_qa_stats flag:
mri_pglands_seg --s <subjectid> --write_qa_stats
Below is a diagram overviewing our QA procedure. A detailed description is contained within the associated journal article.
Methods overview
Images are first pre-processed by conforming them to 1 mm isotropic resolution and a size of 256x256x256 voxels. Next, image intensities are rescaled such that the average white matter (WM) value is 110. A 96x96x96 voxel window containing the target structures is then identified by affinely registering the image to a template in MNI152 space. The template is then registered back to the original image so that all segmentation occurs in the subject space. Note that this template is used only to establish a field-of-view. The image is then cropped based on this template, and robustly normalized such that all intensities are between 0 and 1.
The image is then input into the segmentation model, which predicts segmentations for each of the target structures. Our model is a standard UNet that takes the following form:
.
Following segmentation, volume stats (--write_vol_stats) and QA stats (--write_qa_stats) can be calculated for each predicted label.
Other usage options
Below is a list of other, optional command-line inputs:
--use_cuda |
Use Cuda for GPU support |
--center_crop |
Use image center for crop window instead of the mni152 crop template |
--logfile |
set basename of logfiles; default is mri_pglands_seg.log |
--lut |
Path to lookup-table (lut); default is pglands.ctab |
--mni_template |
MNI label template used to set crop window; default is mni152_label_template.mgz |
--mni_template_transform |
Path to affine transform for registering the mni label template to subject space. This will override the default syntax, and will apply the transform to all subjects |
--outbase |
String to use in output filename; default is "pglands" |
--robust_norm_percent |
Percentile for robust normalization of input image intensities; default is 0.95 |
--write_posteriors |
Flag to save label posteriors (i.e., the softmax of the output logits from the model) |
--write_qa_stats |
Flag to calculate and write QA stats |
--qa_transform |
Deformation from subject to mni152 space to perform QA analysis on output segmentation. Can either be a path to a single image or a suffix (will search output directory for matching filename) |
--write_vol_stats |
Flag to calculate and save label volumes |
--etiv |
Flag to include eTIV in volume stats; default is true in FS mode and false in normal mode. If set to true in normal mode, it will significantly increase run time |
--tal |
Alternative talairach xfm transform for estimating eTIV. Can either be a path to a single transform or a suffix (will search output directory for matching filename) |
We also have provided the option to supply a different model, in the case that the user has re-trained our existing framework to fine-tune results to their own dataset. Relevant commands for this are:
--crop_patch_size |
Isotropic size (# of voxels) for crop window; default is 96, which is expected by our model |
--model |
Path to trained model; default is pglands_seg.pth |