Documentation Table of Contents

• Important Notes
• Versioning
•  Introduction
  • Build and Testing Environment
  • Expected Runtime and Memory Usage
• How to Run
  • Command(s) to Run
  • Expected Inputs
  • Running with BIDS-organized Data
• Expected Outputs
• Compare to Test Data

Important Notes

• For the "Compare to Test Data" section, the container internally uses a compression method (gzip) that writes a timestamp into the metadata of the compressed file. To properly compare the output results, end users will need to unzip the NIFTI segmentation images (using gunzip) to directly compare using a checksum. Alternatively, end users can directly compare the segmentation data in the NIFTI. All this information is also described in the "Compare to Test Data" section.

Versioning

• v1.2a: No changes to the container were made. Updated documentation and included a software bill of materials.
• v1.2: Initial Zenodo Release.

Introduction

SLANT-TICV is a deep-learning-based brain segmentation algorithm. Specific information about the training, validation, etc. for the method can be found in the associated paper that the method was published in here.

The following softwares/packages are included:

• MATLAB 2021b
• Python 3.8.10
• pytorch 1.12.0
• numpy 1.23.1

We have also provided a software bill of materials generated using syft: nssSLANT_syft_SBOM.txt

Build and Testing Environment

While the build information is unfortunately unavailable, the container was tested on a  NVIDIA Titan GPU with 12 GB memory. For CPU only, the container runs successfully on computation nodes with AMD processors using the CENTOS 9 OS. 

Expected Runtime and Memory Usage

When run single-threaded 1100 times (CPU only) on T1w scans with a 170 x 256 x 256 voxel grid and 1mm isotropic voxel sizes:

• The memory usage was consistently around 19.2 GB
• The average run time was around 1h30m, with some runs taking as little as 50m and some taking as much as 2h40m

How to run

The pipeline is designed to run as a singularity container, taking in MRI as input and outputting derived MRI volumes.

Command(s) to Run

To run the singularity, please follow the intructions below:

#create the inputs and outputs directories
mkdir -p </path/to/output/dir>/{pre,post,dl} </path/to/input/dir>
#make temporary home directory
mkdir </path/to/temp/home>

#create empty file and make it executable
touch </path/to/input/dir>/empty.sh
chmod +x </path/to/input/dir>/empty.sh

#place your T1w image into the inputs directory
cp </path/to/T1/image> </path/to/input/dir>

#run the following command
singularity exec -e --contain -B </path/to/input/dir>:/opt/slant/matlab/input_pre \
-B </path/to/input/dir>:/opt/slant/matlab/input_post \
-B </path/to/output/dir>/pre:/opt/slant/matlab/output_pre \
-B </path/to/output/dir>/post:/opt/slant/matlab/output_post \
-B </path/to/output/dir>/dl:/opt/slant/dl/working_dir \
-B </path/to/temp/directory>:/tmp --home </path/to/input/dir> -B </path/to/input/dir>/empty.sh:</path/to/input/dir>/.bashrc
 <singularity_path> /opt/slant/run.sh

Expected Inputs

SLANT-TICV expects only a single input to run the container, which should be a 3D GZIP'ed T1w NIFTI volume. The file can have any prefix as long as it ends with ".nii.gz".

Running with BIDS-organized Data

While not a BIDS-App, the container can be run on BIDS data without copying or moving files in a BIDS dataset. The key is that the input directory structure must be as described relative to inside the container. By creatively binding files/folders into the container, we can achieve the same effect:

#make output sub-directories
mkdir -p </path/to/session/derivatives/directory>/{pre,post,dl}
#make temporary home directory
mkdir </path/to/temp/home>

#make empty executable
touch </path/to/temp/home>/empty.sh
chmod +x </path/to/temp/home>/empty.sh

#execute command
singularity run -e --contain -B /tmp:/tmp \
-B </path/to/T1w/NIFTI>:/opt/slant/matlab/input_pre/<name_of_file> \
-B </path/to/T1w/NIFTI>:/opt/slant/matlab/input_post/<name_of_file> \
-B </path/to/output/dir>/pre:/opt/slant/matlab/output_pre \
-B </path/to/output/dir>/post:/opt/slant/matlab/output_post \
-B </path/to/output/dir>/dl:/opt/slant/dl/working_dir \
--home </path/to/temp/home> -B </path/to/temp/home>/empty.sh:</path/to/temp/home>/.bashrc \
</path/to/singularity/container> /opt/slant/run.sh

There are no explicitly defined rules for the derivatives of a BIDS-organized dataset. However, we provide some examples here to further help users understand how to run the container with their BIDS-organized data:

#make output sub-directories
mkdir -p /BIDS_dataset/derivatives/SLANT-TICV/sub-XXX/ses-YYY/{pre,post,dl}
#make temporary home directory
mkdir </path/to/temp/home>

#make empty executable
touch </path/to/temp/home>/empty.sh
chmod +x </path/to/temp/home>/empty.sh

singularity run -e --contain -B /tmp:/tmp \
-B /BIDS_dataset/sub-XXX/ses-YYY/anat/sub-XXX_ses-YYY_T1w.nii.gz:/opt/slant/matlab/input_pre/sub-XXX_ses-YYY_T1w.nii.gz \
-B /BIDS_dataset/sub-XXX/ses-YYY/anat/sub-XXX_ses-YYY_T1w.nii.gz:/opt/slant/matlab/input_post/sub-XXX_ses-YYY_T1w.nii.gz \
-B /BIDS_dataset/derivatives/SLANT-TICV/sub-XXX/ses-YYY/pre:/opt/slant/matlab/output_pre \
-B /BIDS_dataset/derivatives/SLANT-TICV/sub-XXX/ses-YYY/post:/opt/slant/matlab/output_post \
-B /BIDS_dataset/derivatives/SLANT-TICV/sub-XXX/ses-YYY/dl:/opt/slant/dl/working_dir \
--home </path/to/temp/home> -B </path/to/temp/home>/empty.sh:</path/to/temp/home>/.bashrc \
</path/to/singularity/container> /opt/slant/run.sh

singularity run -e --contain -B /tmp:/tmp \
-B /BIDS_dataset/sub-XXX/ses-YYY/anat/sub-XXX_ses-YYY_T1w.nii.gz:/opt/slant/matlab/input_pre/sub-XXX_ses-YYY_T1w.nii.gz \
-B /BIDS_dataset/sub-XXX/ses-YYY/anat/sub-XXX_ses-YYY_T1w.nii.gz:/opt/slant/matlab/input_post/sub-XXX_ses-YYY_T1w.nii.gz \
-B /BIDS_dataset/derivatives/sub-XXX/ses-YYY/SLANT-TICV/pre:/opt/slant/matlab/output_pre \
-B /BIDS_dataset/derivatives/sub-XXX/ses-YYY/SLANT-TICV/post:/opt/slant/matlab/output_post \
-B /BIDS_dataset/derivatives/sub-XXX/ses-YYY/SLANT-TICV/dl:/opt/slant/dl/working_dir \
--home </path/to/temp/home> -B </path/to/temp/home>/empty.sh:</path/to/temp/home>/.bashrc \
</path/to/singularity/container> /opt/slant/run.sh

Expected Outputs

There is only one output for the container (a 3D volumetric segmentation labelmap as a NIFTI), with the rest being temporary files. After SLANT-TICV finishes, the output can be found at

</path/to/output/dir>/post/FinalResult/<name_of_T1>_seg.nii.gz

So if the input file was named:

inputs/sub-XXX_ses-YYY_T1w.nii.gz

The segmentation file will be:

outputs/post/FinalResult/sub-XXX_ses-YYY_T1w._seg.nii.gz

where the labels correpsond to those found in the SLANT_TICV_LUT.txt lookup table also provided on this page.

Compare to Test Data

For testing data, we use a scanning session from version 1.2.1 of the AOMIC ID1000 dataset (https://openneuro.org/datasets/ds003097/versions/1.2.1).

• Lukas Snoek and Maite van der Miesen and Andries van der Leij and Tinka Beemsterboer and Annemarie Eigenhuis and Steven Scholte (2021). AOMIC-ID1000. OpenNeuro. [Dataset] doi: 10.18112/openneuro.ds003097.v1.2.1
• The scanning session is from sub-0001
  
  • The T1w scan comes from the anat subfolder and is called sub-0001_run-1_T1w.nii.gz in the dataset

To run the test data, please run the following commands:

#create the inputs and outputs directories
mkdir inputs outputs/{pre,post,dl}

#move the test T1w image to the inputs
mv sub-0001_run-1_T1w.nii.gz inputs/

#create the empty executable
touch inputs/empty.sh
chmod +x inputs/empty.sh

#run the singularity
singularity exec -e --contain -B inputs:/opt/slant/matlab/input_pre \
-B inputs:/opt/slant/matlab/input_post \
-B outputs/pre:/opt/slant/matlab/output_pre \
-B outputs/post:/opt/slant/matlab/output_post \
-B outputs/dl:/opt/slant/dl/working_dir \
-B /tmp:/tmp --home </path/to/input/dir> \
 -B </path/to/input/dir>/empty.sh:</path/to/input/dir>/.bashrc \
<singularity_path> /opt/slant/run.sh

When done, the outputs folder you created should contain the segmentation output specified above, along with several temporary files. Please compare the outputs/post/FinalResult/sub-0001_run-1_T1w_seg.nii.gz file to the sub-0001_run-1_T1w_seg.nii.gz file provided in this repository to assess similarity/reproducibility.

NOTE: The container internally uses a compression method (gzip) that writes a timestamp into the metadata of the compressed file. To properly compare the output results, end users will need to unzip the NIFTI segmentation images (using gunzip) to directly compare using a checksum:

##run this on both files
gunzip sub-0001_run-1_T1w_seg.nii.gz

##compare the unzipped NIFTIs via checksum
md5sum sub-0001_run-1_T1w_seg.nii outputs/post/FinalResult/sub-0001_run-1_T1w_seg.nii

 Alternatively, end users can directly compare the segmentation data in the NIFTI files.