Open Source Hypothalamic-ForniX (OSHy-X) Atlases and Segmentation Tool for 3T and 7T

Version 0.4

OSHy-X is an atlas repository (https://osf.io/zge9t) and containerised Python script that automatically segments the hypothalamus and fornix at 3T and 7T in both T1w and T2w scans. It is designed to only run inside a container. See below for installation instructions.

OSHy-X is published in the Journal of Open Source Software. Read the paper here.

Installation

You have the option of running OSHy-X via NeuroDesk, a Docker container by itself, or an Apptainer. OSHy-X (and OSHy.py) is not designed to run outside of a container.

Neurodesk

Follow instructions here to install Neurodesk.

Docker

1. Install Docker here.
2. Open a terminal and run:

docker pull jerync/oshyx_0.4:20220614 To pull the container. Or run:

docker run --rm -v /path/to/data/folder/:/data/ jerync/oshyx_0.4:20220614 --target /data/input_file.nii.gz --outdir /data/output_directory

Apptainer (formerly Singularity)

1. Install Apptainer here.
2. Open a terminal and run apptainer build oshyx_0.4.sif docker://jerync/oshyx_0.4:20220614 to build the container.

Usage

Docker and Apptainer

``` Usage: docker run --rm -v /path/to/data:/data jerync/oshyx_0.4:20220614 [-h] -t TARGET [TARGET ...] -o OUTDIR [-c CROP] [-w WEIGHTING] [-d DENOISE] [-f FIELDCORRECTION] [-m MOSAIC] [-x TESLA] [-b BIMODAL] [-n NTHREADS]

   apptainer run --bind /path/to/data:/data oshyx_0.4.sif 
           [-h] -t TARGET [TARGET ...] -o OUTDIR [-c CROP] [-w WEIGHTING]
           [-d DENOISE] [-f FIELDCORRECTION] [-m MOSAIC] [-x TESLA]
           [-b BIMODAL] [-n NTHREADS]

Options: -h, --help Show this help message and exit -t TARGET [TARGET ...], --target TARGET [TARGET ...] A string or list of strings pointing to the target image(s). Must be a NIfTI file. For a test run, specify /OSHy/sub-test.nii.gz -o OUTDIR, --outdir OUTDIR A string pointing to the output directory. Please ensure this is within the mounted volume (Specified with the -v flag for the docker run command. -c CROP, --crop CROP Optional. A boolean indicating if the target image and priors are to be cropped. If False, whole-image priors will be used, which will improve the segmentation but significantly increase the runtime. (default: True) -w WEIGHTING, --weighting WEIGHTING A string indicating the weighting of the input image(s). This can be either T1w or T2w. (default: T1w -d DENOISE, --denoise DENOISE Optional. A boolean indicating if denoising is to be run on the target image. (default: True) -f FIELDCORRECTION, --fieldCorrection FIELDCORRECTION Optional. A boolean indicating if B1 bias field correction is to be run on the target image. (default: True) -m MOSAIC, --mosaic MOSAIC Optional. A boolean indicating if a mosaic image is to be plotted after running Joint Label Fusion. (default: True) -x TESLA, --tesla TESLA Optional. An integer (either 3 or 7) indicating the field strength. (default: 3) -b BIMODAL, --bimodal BIMODAL Optional. A boolean indicating if bimodal priors are to be used. If FALSE, then only unimodal priors (specified in --weighting) will be used.(default: False) -n NTHREADS, --nthreads NTHREADS Optional. An integer indicating the number of threads. This is passed to the global variable ITKGLOBALDEFAULTNUMBEROF_THREADS and the -j flag in Joint Label Fusion. (default: 6) ```

Output

All output is written to the output directory (specified using the -o/--outdir flag.)

Contents of the output include:

• sub-XX_Labels.nii.gz: Output from Joint Label Fusion. The label file for the left and right hemispheres of the Hypothalamus and Fornix. If --crop is True then this label file will also be cropped. The labels are as follows:
  • 1 Left Hypothalamus
  • 2 Right Hypothalamus
  • 3 Right Fornix
  • 4 Left Fornix
• sub-XX_Intensity.nii.gz: The input intensity image for Joint Label Fusion segmentation.
• sub-XX_resampled_Labels.nii.gz: sub-XX_Labels.nii.gz but resampled to the input target image.
• sub-XX_hypothalamus.nii.gz: sub-XXresampledLabels.nii.gz but with only hypothalamus labels.
• sub-XX_fornix.nii.gz: sub-XXresampledLabels.nii.gz but with only fornix labels.
• sub-XX_mosaic.png: A 16 slice coronal visualisation of the segmentation.
• *_log.txt: The log of the piecewise registration between the atlases and the target image.
• sub-XX_TargetMaskImageMajorityVoting.nii.gz: Labelled voxels where Joint Label Fusion was not performed. This is the case when 80% or more of the atlases agree on the same voxel.
• sub-XX_TargetMaskImageMajorityVoting_Mask: A mask of voxels where Joint Label Fusion segmentation is performed.
• sub-XX_volumes.csv: Volumes of the four labels (as described above). Units for volume are in mm<sup>3</sup>.

Community

We welcome any contributions to OSHy-X, whether they are reports for bugs, feature enhancements, or pull requests.

To contribute to OSHy-X please visit our contribute page and read our contributing guidelines.