How to Run DWI Analysis

Here's a rundown on how to use our DWI preprocessing pipeline

This wiki page provides instructions for running the DWI pipeline, including environment setup, file naming conventions, and quality control.

1. File Requirements

To run the pipeline, you need the following three files for each subject:

1. DWI Volume
2. T1w Volume
3. Pelican Non-linear Transform (xfm) with Warp

Naming Convention

The ID and Session are parsed directly from the DWI filename. Files must adhere to the following naming convention to ensure proper data aggregation:

ID_sessiondate_DWI.extension

Important: Strict adherence to this format is required to correctly identify subjects and timepoints during aggregation. I ain't no wizard to write code that understand every id+date format in existence.

---

2. Environment Setup

Before running the scripts, load the required modules.

# Load module path
module use /cvmfs/neurodesk.ardc.edu.au/neurodesk-modules/*

# Load specific tool versions
module load fsl/6.0.3 mrtrix3/3.0.4 StdEnv apptainer minc ants

Important: You must use FSL 6.0.3 and MRtrix3 3.0.4. Newer versions of these tools currently contain bugs that affect this pipeline.

---

3. Input Data Preparation

The script accepts either MRtrix3 (.mif) files or NIfTI (.nii / .nii.gz) files.

• Option A: DICOM to .mif (Recommended)

If you have raw DICOM files, it is best to convert them directly to .mif format, as this preserves the gradient table in the header.

mrconvert $dicom_dir $subject_session.mif

• Option B: Using NIfTI Files

If you are starting with NIfTI files, you have two choices:

• Convert NIfTI to .mif manually: You must attach the bvecs and bvals using MRtrix.

mrconvert $nii_input $mif_output -fslgrad $bvecs $bvals

• Provide NIfTI files directly: You can provide the NIfTI file directly to the script, provided that matching bvecs and bvals exist in the same directory.

1. DWI: ID_sessiondate_DWI.nii.gz
2. Bvec: ID_sessiondate_DWI.bvec
3. Bval: ID_sessiondate_DWI.bval

---

4. Running the Pipeline

The main execution script is runDWI.sh.

./runDWI.sh <dwi_file> <t1w_file> <nlin_warp> [pe_dir] [readout_time]

Parameter	Description
<dwi_file>	Path to the input DWI file (mif or nifti).
<t1w_file>	Path to the T1-weighted structural file.
<nlin_warp>	Path to the Pelican non-linear warp file.
[pe_dir]	Phase Encoding Direction. Extract this from the JSON sidecar or dataset documentation. Usually consistent across a dataset.
[readout_time]	Total Readout Time. Extract from JSON sidecar or documentation. Usually consistent across a dataset.

Important: <> means mandatory to provide, [] means optional

---

5. Quality Control (QC)

After processing, a QC report is generated. Location: //Diffusion/Preprocseed/eddy_qc/quad/qc.pdf

What to check:

• Page 6: Ensure there are no lines visible in the images.

• Page 7: Check the outlier plot.

  • There should be no outliers in the first 6 volumes.

  • Outliers appearing after the first 6 volumes are expected and acceptable.