README.md

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
                        ITK_GLOBAL_DEFAULT_NUMBER_OF_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-XX_resampled_Labels.nii.gz but with only hypothalamus labels.
• sub-XX_fornix.nii.gz: sub-XX_resampled_Labels.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³.

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.