Skip to content

Module 10 Diffusion Imaging

Jump to bottom
Jared Tanner edited this page Apr 4, 2026 · 16 revisions

Watch these videos for an introduction to diffusion MRI. This will also be covered in class.

Intro: https://youtu.be/l5XtngIbehg

Another resource for those interested: https://youtu.be/1shFshj5Tgc

For this assignment, you will use an automated and containerized pipeline to preprocess diffusion data. [QSIPrep]https://qsiprep.readthedocs.io/en/latest/index.html) is a pipeline developed at the University of Pennsylvania, which has a rich history with MRI development and analyses.

"Diffusion-weighted magnetic resonance imaging (dMRI) is the primary method for noninvasively studying the organization of white matter in the human brain. Here we introduce QSIPrep, an integrative software platform for the processing of diffusion images that is compatible with nearly all dMRI sampling schemes. Drawing on a diverse set of software suites to capitalize on their complementary strengths, QSIPrep facilitates the implementation of best practices for processing of diffusion images." (https://www.nature.com/articles/s41592-021-01185-5)

I do not have a walk-through video for this. Please use previously developed skills to finish this assignment.

Steps to accomplish

  1. Copy (do not move!) the Module10 directory to your own subdirectory.
    Please do this first before touching any files in that directory. Your subdirectory should be located at:

    /blue/psy4930/share/students/YOUR_GATORLINK/

    or wherever you have been storing your data this semester.

    If you accidentally do anything to the original Module10 directory, immediately contact me so I can help fix any issues.

  2. Within your copy of the Module10 directory, you will see four directories.
    This is a BIDS-style (but not fully complete) dataset. It will work with QSIPrep as the command is currently written.

    • code
    • derivatives
    • sub-004
    • sub-005

  3. Within the code directory is a sample script.
    Because this script uses the $USER variable, it will automatically pull your Gatorlink username. This means if you copied the Module10 folder exactly to:

    /blue/psy4930/share/students/YOUR_GATORLINK/Module10

    you do not need to edit the paths or the email line.

    Here is the script for sub-005, but it is also in the code directory. This will use the GPU and CUDA to accelerate processing. It uses the hpg-turin partition, so it will grab an available GPU. It might take a little while for your job to start depending on cluster traffic, but once running, it should only take about 1 hour to finish.

    #!/bin/bash
#SBATCH --time=3:00:00
#### EDIT the job-name and output when you run the other participant
#SBATCH --job-name=Module10-005_qsiprep 
#SBATCH --output=Module10-005_qsiprep_%j.log 
#SBATCH --mem=64GB
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=10
#SBATCH --account=psy4930
#SBATCH --qos=psy4930
#SBATCH --mail-type=END,FAIL
######### EDIT THIS to your email
#SBATCH --mail-user=$USER@ufl.edu 
#SBATCH --partition=hpg-turin
#SBATCH --gpus=1

pwd; hostname; date

module load cuda gcc/5.2.0

############# Make sure your paths match where your data are ##############################

# 1. Add tmp directory -- UPDATE THIS TO MATCH YOUR PATH if not using default
mkdir -p /blue/psy4930/share/students/${USER}/Module10/derivatives/tmp_scratch 

# 2. Update your apptainer command
apptainer run --cleanenv --containall --nv \
    -B /blue/psy4930/share/students/${USER}/Module10:/in \
    -B /blue/psy4930/share/students/${USER}/Module10/derivatives:/out \
    -B /blue/psy4930/share/students/${USER}/Module10/derivatives/tmp_scratch:/tmp \
    -B /blue/psy4930/share/students/${USER}/Module10/derivatives/tmp_scratch:/var/tmp \
    -B /apps/freesurfer/license/license.txt:/opt/freesurfer/license.txt \
    /blue/psy4930/share/data/neurotools/qsiprep-1.1.1.sif /in /out/qsiprep participant \
    --participant-label sub-005 \
    --skip-bids-validation \
    --nprocs 10 \
    --omp-nthreads 5 \
    --mem 60000 \
    --fs-license-file /opt/freesurfer/license.txt \
    --output-resolution 2 \
    --unringing-method mrdegibbs \
    --eddy-config /out/eddy_params.json \
    --stop-on-first-crash \
    -w /out/tmp_scratch/ -v -v

date

    Note: You only need to change the paths in the script above if you put your Module10 folder somewhere other than:

    /blue/psy4930/share/students/YOUR_GATORLINK/

    If this does not start successfully, you likely have a typo somewhere.

  4. Save the file.
    Then, make a copy of that script in the same code directory and name it:

    sub-004_ses-04_qsiprep.sh

  5. Edit the new sub-004_ses-04_qsiprep.sh file so it runs the other participant.
    You will only need to change anywhere in the script it says 005 to 004 (a total of 3 instances):

    • two in the #SBATCH section at the top
    • one in the apptainer command for the --participant-label flag

  6. Submit the two scripts from within the code directory using the following command:

    sbatch sub-004_ses-04_qsiprep.sh ; sbatch sub-005_ses-04_qsiprep.sh

    Each script will require about 1 hour to run. It could be longer depending on queue wait times.

What to turn in

Submit the image files called:

  • sub-004_ses-04_dir-AP_desc-biascorrpost_dwi.svg
  • sub-005_ses-04_dir-AP_desc-biascorrpost_dwi.svg

Because of the $USER variable, you can find these in your processed directories here:

/blue/psy4930/share/students/$USER/Module10/derivatives/qsiprep/sub-004/ses-04/figures
/blue/psy4930/share/students/$USER/Module10/derivatives/qsiprep/sub-005/ses-04/figures

Troubleshooting

If your job started but the required .svg figures do not exist in your output directory, there was likely a processing error. Here are the most common culprits and how to fix them:

Typos

Double-check your scripts for any typos in the file paths, participant IDs, or missing spaces.

Incomplete Data

Ensure you copied the entire Module10 directory correctly. If the transfer was interrupted, you might be missing essential files.

Out of Memory (OOM) Errors

Occasionally, the script can fail because the GPU ran out of memory during processing. You can check for this by opening the .log file created in your code directory.

Look for an error message like:

parallel_for failed: cudaErrorMemoryAllocation: out of memory

How to fix it

If you see this, delete the partially created files. Specifically, delete the entire sub-004 and/or sub-005 directory inside your derivatives/qsiprep folder, then resubmit your script.

If it keeps happening

Edit these two lines to increase your memory allocation, for example to 96 GB:

  • Change #SBATCH --mem=64GB to #SBATCH --mem=96GB
  • Change --mem 60000 \ to --mem 90000 \

If it still fails after increasing the memory, send me both of your scripts, and I will give you credit for the assignment.

Clone this wiki locally