QSIPrep phase and magnitude images combined

Software Support
1

Summary of what happened:

We have magnitude and phase images for each participant. After running QSIprep and receiving the output, we noticed that the phase and magnitude data was combined, though we heard that shouldn’t have been an issue since v0.21.1?

Command used (and if a helper script was used, a link to the helper script or the command generated):

#!/bin/bash

# Ensure correct number of arguments
if [ "$#" -ne 3 ]; then
    echo "Usage: $0 <DATA_DIR> <OUTPUT_DIR> <WORK_DIR>"
    exit 1
fi

# Assign arguments to variables
DATA_DIR="$1"
OUTPUT_DIR="$2"
WORK_DIR="$3"
FS_LICENSE="license.txt"

# Loop through all subjects in the DATA_DIR (assumes sub-<ID> structure)
for subject_path in "${DATA_DIR}"/sub-*; do
    # Extract subject ID
    SUBJECT=$(basename "$subject_path")

    # Run qsiprep for the current subject
    docker run --rm -ti \
        -v "${DATA_DIR}:/data:ro" \
        -v "${OUTPUT_DIR}:/out" \
        -v "${WORK_DIR}:/work" \
        pennbbl/qsiprep \
        /data /out participant \
        --output-resolution 1.5 \
        --participant-label "${SUBJECT#sub-}" \
        --fs-license-file /data/license.txt
done

Version:

0.24.1.dev0+gc6ac851.d20241114

Environment (Docker, Singularity / Apptainer, custom installation):

Docker on Ubuntu

Data formatted according to a validatable standard? Please provide the output of the validator:

Input directory structure:

└── subjects_processed_2/
    ├── dataset_description.json
    └── sub-name/
        ├── anat/
        │   ├── sub-name_T1w.json
        │   └── sub-name_T1w.nii.gz
        ├── dwi/
        │   ├── sub-name_dwi.json
        │   ├── sub-name_dwi.bvec
        │   ├── sub-name_dwi.nii.gz
        │   └── sub-name_dwi.bval
        └── fmap/
            ├── sub-name_dir-PA_epi.nii.gz
            └── sub-name_dir-PA_epi.json

Relevant log outputs (up to 20 lines):

Screenshots / relevant information:

2

The magnitude and phase images are only combined during the dwidenoise step. They should be split up afterwards. When you say that you noticed that the phase and magnitude data was combined, do you mean you loaded the preprocessed files and they were complex valued?

EDIT: And just to clarify, when you say that your input directory looks like that, you mean it looks like the following, right? I.e., the magnitude and phase components are split into separate files, per BIDS.

└── subjects_processed_2/
    ├── dataset_description.json
    └── sub-name/
        ├── anat/
        │   ├── sub-name_T1w.json
        │   └── sub-name_T1w.nii.gz
        ├── dwi/
        │   ├── sub-name_part-mag_dwi.json
        │   ├── sub-name_part-mag_dwi.bvec
        │   ├── sub-name_part-mag_dwi.nii.gz
        │   ├── sub-name_part-mag_dwi.bval
        │   ├── sub-name_part-phase_dwi.json
        │   ├── sub-name_part-phase_dwi.bvec
        │   ├── sub-name_part-phase_dwi.nii.gz
        │   └── sub-name_part-phase_dwi.bval
        └── fmap/
            ├── sub-name_dir-PA_epi.nii.gz
            └── sub-name_dir-PA_epi.json
3

Thanks, @tsalo! I’m helping @cathzchen to analyze this data, so I’ll post here too.

Yes, that’s what we meant, sorry for the confusion.
As a follow-up question, what exactly should we leave in the fmap folder? For the opposite phase encoding direction we have the following files:

  • An SBRef file (magnitude, single volume)
  • A magnitude file (9 volumes, 8 are b=0 and one is b=1000)
  • A phase file (9 volumes, 8 are b=0 and one is b=1000)

Does it make sense to only have the SBRef file in the fmap folder, to be used as input for TOPUP? Will QSIprep then use both SBREfs (the fmap and the main one) as input for TOPUP?

Or can QSIPrep use the full information in the 8 b=0 volumes of the magnitude data, and this is what we should leave in the fmap?

Thanks again for your help!
Roey

4

Hi @roeysc,

Just to further clarify, you are saying that you have both magnitude and phase for both DWI and fmaps?

As described in the BIDS specification (Magnetic Resonance Imaging - Brain Imaging Data Structure 1.10.0) you need at least two phase files or a single phasediff image. Also, if your fmaps have multiple volumes you should have an accompanying bval/bvec file.

QSIPrep does not use SBREFs. QSIPrep uses b0s from the DWI itself.

I recommend updating.

Best,
Steven

1 Like
5

Thanks for these insights, @Steven!

Yes, that is right. Our protocol consists of 70 volumes in AP phase encoding (including several b=0 volumes) and 9 volumes in PA phase encoding (8 are b=0 volumes). Both the 70 volumes and 9 volumes have magnitude+phase data.

I’m sorry if these are very basic questions, but:

  1. Should we only include the magnitude data in the fmap folder?
  2. Should we make a copy of the main 70 volumes data and paste it into the fmap folder, so that both PA and AP scans are inside the fmap folder?

Does this mean we can leave non-b0 volumes in the fmap files, and QSIPrep will know to only extract the relevant b=0 volumes based on the bvec file?

Many thanks, @Steven!
Roey

6

Hi @roeysc,

Okay so this is PEPOLAR style fieldmapping, but you collect the real and imaginary parts.

Please refer to the BIDS specification (Magnetic Resonance Imaging - Brain Imaging Data Structure 1.10.0). You can see that you can include both mag and phase (indicated by the part-<> label).

No, the DWI data should stay in dwi.

Yes.

Best,
Steven

7

Thank you so much, @Steven, this is very helpful.