Documentation Table of Contents

• 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
• How to Apply Transform Files
• Compare to Test Data

Versioning

• v1.4: Bugfix when running container without T1 segmentation as input. Also added software bill of materials (generated using syft): WMAtlas_syft_SBOM.txt.
• v1.3: initial Zenodo release

Introduction: Atlas Registration to Diffusion MRI Space

Singularity container that, given a T1-weighted (T1w) structural MRI and diffusion MRI (dMRI) scan, registers the structural atlas of your choosing to the Diffusion MRI space. Also, provided an LUT file of the ROIs in the atlas, will calculate the mean, median, and stdev of the DTI metrics inside the ROIs. The container runs the following:

• ANTs (2.5.0) Registration (deformable) between a T1w template and a T1w scan
• FSL's (6.0.6) epi_reg (rigid) between a T1w scan and a dMRI scan from the same scanning session
• c3d (1.0.0) tools to convert between the FSL and ITK transform matrix formats
• ANTs (2.5.0) Apply Transforms to apply the calculated image transformations to move a structural atlas into the dMRI space
• Custom python code to extract dMRI volumes in a specific b-value range
• MRtrix3 (3.0.3) commands to calculate dMRI tensors at every voxel and extract tensor maps of FA, MD, AD, RD
• Custom python code to calculate the mean, median, and stdev of the tensor maps inside each region of interest (ROI) of the atlas

Build and Testing Environment

The container was built and tested using a machine running on Ubuntu 20.04, with 64GB of memory. The CPU is a Intel(R) Xeon(R) W-2255 CPU running at 3.70GHz. Moreover, the container runs successfully on computation nodes with AMD processors using the CENTOS 9 OS. 

Expected Runtime and Memory Usage

When run single-threaded 1500 different times:

• The memory usage was around 4 GB, with some runs as low as 3.7 GB and as high as 4.08 GB.
• The average run time was around 3 hours, with the maximum run time at around 5h 38m.

How to Run

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

Command(s) to Run

Below are the usage instructions for how to run the Singularity Container:

singularity run -e --contain -B </path/to/input/directory>:/INPUTS -B </path/to/output/directory>:/OUTPUTS \
-B </path/to/temp/directory>:/tmp <singularity_container> {--MNI | --EVE3 | --custom}

Where the --EVE3 flag will register the JHU EVE 3 Atlas labels (obtained here: https://github.com/muschellij2/Eve_Atlas), the --MNI flag will calculate the transforms to move data from the dMRI space to the MNI 152 space (nonlinear, 1mm iso), and the --custom flag allows the user to input a different template and atlas.

Please continue reading in order to learn how to structure the input directory.

Expected Inputs

To run the container, all MRI volumes are expected to be in the NIFTI format. The required inputs for running the container should be named as follows:

• t1.nii.gz : a T1w image
• dwmri.nii.gz : a 4D dMRI that has been preprocessed with FSL's TOPUP and EDDY using the PreQual preprocessing pipeline (which can be found here: 10.5281/zenodo.14058395 and here: https://github.com/MASILab/PreQual). Is assumed to have at least one b0 volume.
• dwmri.bval : a metadata text file for dMRI (units of s/mm², in the FSL format) for the bvalues of each dMRI volume. Should be properly formatted if coming from PreQual.
• dwmri.bvec : a metadata text file for dMRI (normalized unit vectors in the FSL format) for the bvectors of each dMRI volume. Should be properly formatted if coming from PreQual.
• mask.nii.gz : the PreQual mask provided as output

Optionally (recommended), you can also provide a T1w segmentation image:

• T1_seg.nii.gz : a segmentation map of the provided T1w image coming from SLANT-TICV (which can be found here: https://github.com/MASILab/SLANTbrainSeg_TICV)

If using the --custom flag, you must also provide the following:

• Atlas_<atlas_name>.nii.gz : a 3D atlas with ROIs, where <atlas_name> is a name for the custom atlas
• Label_<atlas_name>.txt : a lookup table (LUT) text file with an entry for each ROI in the provided atlas. The format of the file should be:

	#INTENSITY/Integer_label Region_Of_Interest_Name

	0 Background			
	1 Superior_Parietal_Lobule_left
	2 Cingulate_Gyrus_left
	3 Middle_Frontal_Gyrus_left
	...

• • In other words, each line should have an intensity value of the labelmap and the corresponding name of the label delimited by a space
  • The first line of the text file should be the background with intensity of zero
  • The names of the ROIs in the labelmap should not contain any spaces: the only spaces should be between the intensity and corresponding ROI name
• template.nii.gz : a structural T1w template that the atlas ROIs are defined on. Should be in the same space as the provided atlas.

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:

singularity run -e --contain -B </path/to/temp/directory>:/tmp \
 -B </path/to/PreQual/or/Preprocessed/DWI/NIFTI>:/INPUTS/dwmri.nii.gz \
 -B </path/to/PreQual/or/Preprocessed/DWI/BVAL>:/INPUTS/dwmri.bval \
 -B </path/to/PreQual/or/Preprocessed/DWI/BVEC>:/INPUTS/dwmri.bvec \
 -B </path/to/DWI/Mask>:/INPUTS/mask.nii.gz \
-B </path/to/T1w/NIFTI>:/INPUTS/t1.nii.gz \
-B </path/to/T1/SLANT/Segmentation>:/INPUTS/T1_seg.nii.gz \
-B </path/to/session/derivatives/directory>:/OUTPUTS \
<singularity_container> {--MNI | --EVE3 | --custom}

  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:

singularity run -e --contain -B /tmp:/tmp \
 -B /BIDS_dataset/derivatives/PreQual/sub-XXX/ses-YYY/PREPROCESSED:/INPUTS \
-B /BIDS_dataset/sub-XXX/ses-YYY/anat/sub-XXX_ses-YYY_T1w.nii.gz:/INPUTS/t1.nii.gz \
-B /BIDS_dataset/derivatives/SLANT-TICV/sub-XXX/ses-YYY/sub-XXX_ses-YYY_seg.nii.gz:/INPUTS/T1_seg.nii.gz \
-B /BIDS_dataset/derivatives/WMAtlasEVE3/sub-XXX/ses-YYY:/OUTPUTS \
<singularity_container> --EVE3

singularity run -e --contain -B /tmp:/tmp \
 -B /BIDS_dataset/derivatives/sub-XXX/ses-YYY/PreQual/PREPROCESSED:/INPUTS \
-B /BIDS_dataset/sub-XXX/ses-YYY/anat/sub-XXX_ses-YYY_T1w.nii.gz:/INPUTS/t1.nii.gz \
-B /BIDS_dataset/derivatives/sub-XXX/ses-YYY/SLANT-TICV/post/FinalResult/sub-XXX_ses-YYY_seg.nii.gz:/INPUTS/T1_seg.nii.gz \
-B /BIDS_dataset/derivatives/sub-XXX/ses-YYY/WMAtlasEVE3:/OUTPUTS \
<singularity_container> --EVE3

Expected Outputs

There are several outputs to be expected from the pipeline:

• dwmri%Atlas_<atlas_name>.nii.gz : the 3D atlas labels moved into the dMRI space
  • note this only appears if you have provided an atlas. If you only provide the template or run with the --MNI flag, this will not be present in the outputs
• dwmri%{fa,md,ad,rd}.nii.gz : 3D tensor maps
• dwmri%ANTS_t1tob0.txt : the linear transform file for moving from the T1w image space to the dMRI space
• dwmri%0GenericAffine.mat : the linear transform file for moving from the T1w image space to the T1w template
• dwmri%1InverseWarp.nii.gz : the inverse warp file for the T1w scan to the T1w template
• dwmri%diffusionmetrics.csv : CSV file that contains the mean, median, stdev values of FA, MD, AD, RD for the ROIs in the atlas
  
  • If the SLANT-TICV segmentation was provided, values will be provided within those ROIs as well 
  • The format of the CSV is:

• Atlas_<atlas_name>.png : A QC png of the atlas ROIs overlayed on the FA map post-transformation
  • note this only appears if you have provided an atlas. If you only provide the template or run with the --MNI flag, this will not be present in the outputs
• dwmri%firstshell.{bval,bvec,nii.gz} : the NIFTI, bval, and bvec files for the extracted volumes prior to calculating the diffusion tensor
• dwmri%b0.nii.gz : extracted average b0 shell from the dMRI scan
• If the SLANT-TICV segmentation was provided, then the following files will also be present:
  • dwmri%T1_seg_to_dwi.nii.gz : SLANT-TICV labels moved into the dMRI space
  • T1_seg.png : A QC png of the SLANT-TICV ROIs overlayed on the FA map post-transformation

How to Apply Transform Files

If you would like to apply the transformations yourself, this is the following ANTs command to do so:

antsApplyTransforms -d 3 -i <file_in_atlas_space> -r <3D_file_in_dMRI_space> -n NearestNeighbor -t dwmri%ANTS_t1_to_b0.txt -t [dwmri%0GenericAffine.mat,1] -t dwmri%1InverseWarp.nii.gz -o <output_file_name>

where the <3D_file_in_dMRI_space> can be any 3D file in dMRI space (such as the b0, fa map, etc.)

Compare to Test Data

NOTE: the image registration is non-deterministic process, so the results may not be exactly the same when running the testing data yourself

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) where the dMRI scan has been preprocessed with version 1.0.8 of the PreQual preprocessing pipeline and the T1w image has been run through SLANT-TICV.

• 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 dMRI data provided as test input is the concatenation of runs 1, 2, and 3 in the dwi subfolder (all three were run through the PreQual together)
  • 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, run the following commands:

## create an input and output directory (and temp)
mkdir inputs outputs temp

## move the input testing files to the inputs directory
mv dwmri.nii.gz dwmri.bval dwmri.bvec mask.nii.gz t1.nii.gz T1_seg.nii.gz inputs/

## run the command
singularity run -e --contain -B inputs:/INPUTS -B outputs:/OUTPUTS -B temp:/tmp <singularity_container> --EVE3

When done, the outputs folder you created should contain all the outputs specified above, along with several temporary files. Please compare the dwmri%diffusionmetrics.csv, dwmri%Atlas_JHU_MNI_SS_WMPM_Type-III.nii.gz, Atlas_JHU_MNI_SS_WMPM_Type-III.png, T1_seg.png, and the transform files to assess the similarity in the outputs to those provided in this repository. Again, registration is a non-deterministic process, so the outputs may not match exactly.