Documentation Table of Contents

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

Important Notes

• The container has inherently nondeterministic steps, resulting in different outputs given subsequent reruns using the exact same inputs. Thus, checksum comparisons are not viable for comparing test data outputs to provided sample data in the "Compare to Test Data" section. However, for a measurement of variability due to nondeterminism, we provide an empirical mean and standard deviation of the output PREPROCESSED/dwmri.nii.gz file across 50 different reruns of the container with the provided input test data. Please see the "Compare to Test Data" section for further details.

Versioning

• (2026-02-12) Version 1.1.0a: Edited documentation to clarify nondeterminism in outputs. Provided empirical mean/stdev of test data. Uploaded new test data and software bill of materials.
• (2025-01-13) Version 1.1.0: Edited documentation and provided test data in repository.
• Version v1: Initial Zenodo Release

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.

The following softwares, packages, and versions are included in the container:

• MRtrix3 (3.0.3)
• FSL (6.0.4)
• c3d (1.0.0)
• ANTs (2.4.1)
• FreeSurfer (6.0.0; requires license)
• MATLAB (2017a)

We also include a software bill of materials generated using syft: PreQual_syft_SBOM.txt

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 run-1 of dMRI data provided as test input, which comes 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 --synb0 stripped

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.

NOTE: We use the --synb0 stripped flag in this tutorial because the provided input T1w image has been skull-stipped. Although we recommend this process, end users are free to use original, non-skull-stripped T1w images for synb0 when using their own data.

NOTE: Again, EDDY is a non-deterministic process, so the outputs will likely not match exactly. However, we provide empirical mean and standard deviaition images across 50 reruns of the test data to quantify the variabiltiy due to nondeterminism.