HypVINN: run_prediction.py

Note

We recommend to run HypVINN with the standard run_fastsurfer.sh interfaces!

The HypVINN/run_prediction.py script enables the inference with HypVINN. In most situations, it will be called from run_fastsurfer.sh a direct call to HypVINN/run_prediction.py is not needed.

Script for Hypothalamus Segmentation.

usage: HypVINN/run_prediction.py [-h] [--sd OUT_DIR] [--sid SID]
                                 [--seg_log LOG_NAME] [--t1 ORIG_NAME]
                                 [--t2 T2] [--qc_snap]
                                 [--reg_mode {none,coreg,robust}]
                                 [--hypo_segfile HYPO_SEGFILE]
                                 [--device DEVICE]
                                 [--viewagg_device VIEWAGG_DEVICE]
                                 [--threads THREADS] [--batch_size BATCH_SIZE]
                                 [--async_io] [--allow_root]
                                 [--ckpt_ax CKPT_AX] [--ckpt_cor CKPT_COR]
                                 [--ckpt_sag CKPT_SAG] [--cfg_cor CFG_COR]
                                 [--cfg_ax CFG_AX] [--cfg_sag CFG_SAG]

Named Arguments

--sd

Directory in which evaluation results should be written. Will be created if it does not exist. Optional if full path is defined for –pred_name.

--sid

Optional: directly set the subject id to use. Can be used for single subject input. For multi-subject processing, use remove suffix if sid is not second to last element of input file passed to –t1

--seg_log

Absolute path to file in which run logs will be saved. If not set, logs will not be saved.

Default: “”

--t1

Name of T1 full head MRI. Absolute path if single image else common image name. Default: mri/orig.mgz.

Default: “mri/orig.mgz”

--t2

Path to the T2 image to process.

--qc_snap

Create qc snapshots in <sd>/<sid>/qc_snapshots.

Default: False

--reg_mode

Possible choices: none, coreg, robust

Freesurfer Registration type to run. coreg: mri_coreg, robust : mri_robust_register, none: entirely deactivates registration of T2 to T1, if both images are passed, images need to be register properly externally.

Default: “coreg”

--hypo_segfile

File pattern on where to save the hypothalamus segmentation file (default: hypothalamus.HypVINN.nii.gz).

Default: “hypothalamus.HypVINN.nii.gz”

Advanced options

--device

Select device to run inference on: cpu, or cuda (= Nvidia gpu) or specify a certain gpu (e.g. cuda:1), default: auto

Default: “auto”

--viewagg_device

Define the device, where the view aggregation should be run. By default, the program checks if you have enough memory to run the view aggregation on the gpu (cuda). The total memory is considered for this decision. If this fails, or you actively overwrote the check with setting > –viewagg_device cpu <, view agg is run on the cpu. Equivalently, if you define > –viewagg_device cuda <, view agg will be run on the gpu (no memory check will be done).

Default: “auto”

--threads

Number of threads to use (defaults to number of hardware threads: 4)

Default: 4

--batch_size

Batch size for inference. Default=1

Default: 1

--async_io

Allow asynchronous file operations (default: off). Note, this may impact the order of messages in the log, but speed up the segmentation specifically for slow file systems.

Default: False

--allow_root

Allow execution as root user.

Default: False

--ckpt_ax

axial checkpoint to load

Default: /home/runner/work/FastSurfer/FastSurfer/dev/checkpoints/HypVINN_axial_v1.1.0.pkl

--ckpt_cor

coronal checkpoint to load

Default: /home/runner/work/FastSurfer/FastSurfer/dev/checkpoints/HypVINN_coronal_v1.1.0.pkl

--ckpt_sag

sagittal checkpoint to load

Default: /home/runner/work/FastSurfer/FastSurfer/dev/checkpoints/HypVINN_sagittal_v1.1.0.pkl

--cfg_cor

Path to the coronal config file

Default: /home/runner/work/FastSurfer/FastSurfer/dev/HypVINN/config/HypVINN_coronal_v1.1.0.yaml

--cfg_ax

Path to the axial config file

Default: /home/runner/work/FastSurfer/FastSurfer/dev/HypVINN/config/HypVINN_axial_v1.1.0.yaml

--cfg_sag

Path to the sagittal config file

Default: /home/runner/work/FastSurfer/FastSurfer/dev/HypVINN/config/HypVINN_sagittal_v1.1.0.yaml

Hypothalamic subfields segmentation pipeline

Input

  • T1w image, a T2w image, or both images. Note: Input images to the tool need to be Bias-Field corrected.

Requirements

  • Same as FastSurfer.

  • If the T1w and T2w images are available and not co-registered, FreeSurfer should be sourced to run the registration code, and the mri_coreg and mri_vol2vol binaries should also be available.

Model weights

  • EUDAT (FZ Jülich) data repository: https://b2share.fz-juelich.de/records/2af6da63d5c1414b832c1f606bbd068a

  • Zenodo data repository: https://zenodo.org/records/11184216

Note: These weights (version 1.1) are retrained compared to paper (version 1.0) for better rotation generalization, performance is equivalent.

Pipeline Steps

  1. Registration (optional, only required for multi-modal input)

  2. Hypothalamus Segmentation

Running the tool

  • The HypVINN output can be obtained by running the default run_fastsurfer.sh script (for more information see FastSurfer documentation).

  • HypVINN can also be run independently by running HypVINN/run_prediction.py, however we recommend running the whole FastSurfer pipeline as it includes all the required pre-processing steps.

  • HypVINN has the following arguments:

Input and output arguments

  • --sid <name> : Subject ID, the subject data upon which to operate

  • --sd <name> : Directory in which evaluation results should be written.

  • --t1 </dir/T1**.nii.gz> : T1 image path

  • --t2 </dir/T2**.nii.gz> : T2 image path

  • --seg_log : Path to file in which run logs will be saved. If not set logs will be stored in /sd/sid/scripts/hypvinn_seg.log

Image processing options

  • --reg_mode : Ignored, if no T2 image is passed. Specifies the registration method used to register T1 and T2 images. Options are ‘coreg’ (default) for mri_coreg, ‘robust’ for mri_robust_register, and ‘none’ to skip registration (this requires T1 and T2 are externally co-registered).

  • --qc_snap: Activate the creation of QC snapshots of the predicted HypVINN segmentation in /sd/sid/qc_snapshots. The created QC snapshots are created to simplify the visual quality control process.

FastSurfer Technical parameters (see FastSurfer documentation)

  • --device

  • --viewgg_device

  • --threads

  • --batch_size

  • --async_io

  • --allow_root

Checkpoint to load

  • --ckpt_cor </dir/to/coronal/ckpt> : Coronal checkpoint to load, default = $FASTSURFER_ROOT/checkpoints/HypVINN_axial_v1.1.0.pkl

  • --ckpt_ax </dir/to/axial/ckpt> : Axial checkpoint to load, default = $FASTSURFER_ROOT/checkpoints/HypVINN_coronal_v1.1.0.pkl

  • --ckpt_sag </dir/to/sagittal/ckpt> : Sagittal checkpoint to load, default = $FASTSURFER_ROOT/checkpoints/HypVINN_sagittal_v1.1.0.pkl

CFG-file with default options for network

  • --cfg_cor </dir/to/coronal/cfg> : Coronal config file to load, default = $FASTSURFER_ROOT/HypVINN/config/HypVINN_coronal_v1.1.0.yaml

  • --cfg_ax </dir/to/axial/cfg> : Axial config file to load, default = $FASTSURFER_ROOT/HypVINN/config/HypVINN_axial_v1.1.0.yaml

  • --cfg_sag </dir/to/sagittal/cfg> : Sagittal config file to load, default = $FASTSURFER_ROOT/HypVINN/config/HypVINN_sagittal_v1.1.0.yaml

Usage

  • The Hypothalamus pipeline can be run by using a T1 a T2 or both images.

  • Is recommended that all input images are bias field corrected and when passing both T1 and T2 they need to be co-registered.

  • The Hypvinn pipeline can do the registration by itself (step 1). This step can be skipped if images are already registered externally.

  • Bias field-corrected images are generated by default by the FastSurfer pipeline; therefore, we recommend running the entire FastSurfer pipeline. If you already have a subject’s FastSurfer output without Hypvinn output, check example 5.

  1. Run HypVINN pipeline

    python HypVINN/run_prediction.py  --sid test_subject --sd /output \
                                 --t1 /data/test_subject_t1_bias_field_corrected.nii.gz \
                                 --t2 /data/test_subject_t2_bias_field_corrected.nii.gz \
                                 --reg_mode coreg \
                                 --batch_size 6

  2. Run HypVINN pipeline only using a t1

    python HypVINN/run_prediction.py  --sid test_subject --sd /output \
                                 --t1 /data/test_subject_t1_bias_field_corrected.nii.gz \
                                 --batch_size 6

  3. Run HypVINN pipeline without the registration step

    python HypVINN/run_prediction.py  --sid test_subject --sd /output \
                                 --t1 /data/test_subject_t1_bias_field_corrected.nii.gz \
                                 --t2 /data/test_subject_t2_bias_field_corrected_and_coregistered_to_t1.nii.gz \
                                 --reg_mode none \
                                 --batch_size 6

  4. Run HypVINN pipeline with creation of qc snapshots

    python HypVINN/run_prediction.py  --sid test_subject --sd /output \
                                 --t1 /data/test_subject_t1_bias_field_corrected.nii.gz \
                                 --t2 /data/test_subject_t2_bias_field_corrected.nii.gz \
                                 --reg_mode coreg \
                                 --batch_size 6 --qc_snap

  5. Run HypVINN pipeline from an existing FastSurfer subject output – recommended when FastSurfer output is there without the Hypothalamus module

    python HypVINN/run_prediction.py  --sid test_subject --sd /output \
                                 --t1 /output/test_subject/mri/orig_nu.mgz \
                                 --seg_log /output/test_subject/scripts/deep-seg.log \
                                 --batch_size 6 --qc_snap

Output

#Output Scheme
|-- output_dir
    |--sid
        |-- mri : MRI outputs
            |--hypothalamus.HypVINN.nii.gz(Hypothalamus Segmentation)
            |-- hypothalamus_mask.HypVINN.nii.gz (Hypothalamus Segmentation Mask)
            |-- transforms
                |-- t2tot1.lta (FreeSurfer registration file, only available if registration is performed)
        |-- qc_snapshots : QC outputs (optional)
            |-- hypothalamus.HypVINN_qc_screenshoot.png (Coronal quality control image)
        |-- stats : Statistics outputs
            |-- hypothalamus.HypVINN.stats (Segmentation stats)

Developer

Santiago Estrada : santiago.estrada@dzne.de

Citation

If you use the HypVINN module please cite

Santiago Estrada, David Kügler, Emad Bahrami, Peng Xu, Dilshad Mousa, Monique M.B. Breteler, N. Ahmad Aziz, Martin Reuter;
FastSurfer-HypVINN: Automated sub-segmentation of the hypothalamus and adjacent structures on high-resolutional brain MRI.
Imaging Neuroscience 2023; 1 1–32. doi: https://doi.org/10.1162/imag_a_00034