Documentation Table of Contents

• Version Notes
•  Introduction
  • Build and Testing Environment
  • Expected Runtime and Memory Usage
• How to Run
• Expected Outputs
• Compare to Test Data

Version Notes

2025-01-13: Edited documentation and provided test data in repository.

Introduction

PreQual is a single integrated pipeline that combines established diffusion preprocessing tools from major MRI-focused software packages with intuitive QA.

This upload contains the singularity container for v1.1.0 of  https://github.com/MASILab/PreQual. For instructions on how to run the container as well as the definition file used to build the singularity, please see the documentation present on the Github repository.

For more information, visit the github repo and the published paper: Leon Y. Cai, Qi Yang, Colin B. Hansen, Vishwesh Nath, Karthik Ramadass, Graham W. Johnson, Benjamin N. Conrad, Brian D. Boyd, John P. Begnoche, Lori L. Beason-Held, Andrea T. Shafer, Susan M. Resnick, Warren D. Taylor, Gavin R. Price, Victoria L. Morgan, Baxter P. Rogers, Kurt G. Schilling, Bennett A. Landman. PreQual: An automated pipeline for integrated preprocessing and quality assurance of diffusion weighted MRI images. Magnetic Resonance in Medicine, 2021.

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 on diffusion MRI with a 128 x 128 x 57 voxel grid, 70 volumes, and a voxel size of 2 x 2 x 4 mm^3:

• The memory usage was around 21 GB, with some runs as low as 18 GB and as high as 22 GB.
• The average run time was around 8 hours, with the maximum run time at around 13h 22m.

How to Run

Please see the GitHub repository here: https://github.com/MASILab/PreQual.

Expected Outputs

Please see the GitHub repository here: https://github.com/MASILab/PreQual.

Compare to Test Data

NOTE: EDDY 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).

• 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
  • We use all 3 runs of dMRI data provided as test input, which come from the dwi subfolder
  • The T1w scan comes from the anat subfolder and is called sub-0001_run-1_T1w.nii.gz in the AOMIC dataset

To run the test data, run the following commands:

#make directories
mkdir inputs outputs

#copy input files into inputs directory
cp <test_input_files> inputs/

#run PreQual Command
singularity run -e --contain -B inputs:/INPUTS -B outputs:/OUTPUTS \
-B </path/to/freesurfer/license>:/APPS/freesurfer/license.txt -B /tmp:/tmp \
</path/to/simg/file> j --topup_first_b0s_only

When done, the outputs folder you created should contain all the outputs specified above, along with several intermediate and quality assurance files. Please compare the files in the PREPROCESSED and PDF directories to assess the similarity in the outputs to those provided in this repository. Again, EDDY is a non-deterministic process, so the outputs may not match exactly.