Issue with Fmap Usage in qsiprep (Topup Disregards AP Fmap and Uses DWI Image)

Summary of what happened:

Hi everyone,

I’m encountering an issue with field maps in my diffusion dataset. I have field maps for both the AP and PA directions (with the phase encoding direction for my DWI NIfTI files set to j-). I’ve ensured that both field maps are recognized by qsiprep by using the ‘Intended for’ field in the corresponding JSON files for the field maps. Despite this, qsiprep (across both versions I’ve tried) repeatedly disregards the field map for the AP direction during the topup step. Instead, it appears to use an image from the DWI run itself—one that isn’t even a B0 image—as the reference for distortion correction in the AP direction.

When I used qsiprep version 0.24.0, the preprocessing was completed without any errors, but the output DWI still displayed field distortions. After upgrading to version 1.0.1, the issue with the topup persists, but I am now also receiving a fatal error during the distortion merger step (see the crash log below). My input raw DWI images are in 4D.

Additionally, after upgrading to version 1.0.1, I encountered a new error in the SynthSeg node, which is searching for a specific file that doesn’t exist. I’m not sure what is causing this error—it may be related to memory issues—but I’m puzzled because I used the same dataset and the same computer for both versions, and only version 1.0.1 produced this error.

Any help or insight would be much appreciated!

Thank you in advance!
Kristina

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

docker run -ti --rm \
   -v /path/to/your/data:/data:ro \
   -v /path/to/your/data/derivatives/qsiprep:/out \
   -v /path/to/your/data/derivatives:/work \
   pennlinc/qsiprep:latest /data /out participant \
   --participant-label sub-XXX \
   --output-resolution 1.3 \
   --fs-license-file /path/to/your/license.txt \
   -w /work

I also tried adding --prefer_dedicated_fmaps and --distortion-group-merge concat, it didn’t make a difference.

Version:

QSIPrep version v1.0.1
QSIPrep version v0.24.0

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

Docker (version 27.3.1)

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

Yes, using dcm2bids

[WARN] The recommended file /README is missing. See Section 03 (Modality agnostic files) of the BIDS specification. (code: 101 - README_FILE_MISSING)

The part of the crash log from the QSIPrep v1.0.1

Node: qsiprep_1_0_wf.sub_DD02_wf.sub_DD02_final_merge_wf.distortion_merger
Working directory: /work/qsiprep_1_0_wf/sub_DD02_wf/sub_DD02_final_merge_wf/distortion_merger

Node inputs:

b0_refs = <undefined>
b0_threshold = 100
bids_dwi_files = <undefined>
bval_files = <undefined>
bvec_files = <undefined>
carpetplot_data = <undefined>
denoising_confounds = <undefined>
dwi_files = <undefined>
harmonize_b0_intensities = True
raw_concatenated_files = <undefined>
scan_metadata = <undefined>
...
.DimensionError: Input data has incompatible dimensionality: Expected dimension is 4D and you provided a 3D image. See https://nilearn.github.io/stable/manipulating_images/input_output.html.

Screenshots / relevant information:

Here is the message of the topupsummary_dwi report: “A total of 2 distortion groups were included in the data data. Distortion group ‘0 -1 0 0.061685’ was represented by image 3 from sub-DD02_run-02_dwi.nii.gz. Distortion group ‘0 1 0 0.061685’ was represented by image 0 from sub-DD02_dir-PA_epi.nii.gz.”


Hi @Kristina_Rainich and welcome to neurostars!!

This makes sense. Your DWI are AP, so the b0 from the DWI is used in correction, obviating the need for the dedicated AP field map. How can you tell it is not a b0 from the DWI being used?

For your synthseg error, what kind of resources are you giving your job?

Is this error for all subjects or just isolated ones?

Any chance you can share a failing subject’s raw data?

Best,
Steven

Thank you for your quick response!

You’re absolutely right — I misunderstood the message from the topup summary. I initially thought that “image 3” referred to a certain volume from the run, but after reviewing the output, I found that the qsiprep_1_0_wf/sub_[number]_wf/dwi_preproc_wf/hmc_sdc_wf/gather_inputs/b0_selection_info.tsv file actually documents the best b=0 selection process, and “image 3” is the specific b=0 image chosen from this run.

Regarding the SynthSeg error, after encountering this error, I attempted to allocate resources using the --memory=16g --memory-swap=20g flag, but this led to a crash during denoising. My system has the following resources available:
Memory: 31Gi total, with approximately 5.2Gi used and 24Gi available before running QSIPrep.
Swap: 2.0Gi total, with 1.1Gi available.
As for other subjects, this error does not seem to be replicated — they seem to complete QSIPrep successfully.

I’ve shared the raw data for this failing subject through a cloud link sent to your email (as we cannot make it publicly available). Please let me know if you need further details or logs. I plan to adjust the resource allocation settings further, including experimenting with different memory flags. If the problem persists, I will consider running the pipeline on a more powerful machine with higher memory and CPU resources.

Best regards,
Kristina

Hi @Kristina_Rainich,

What was that crash error log? Synthseg is very resource intensive. Any chance you have compute cluster access? Or try processing runs individually (e.g. with a BIDS filter file)? I think moving to a more powerful system should be your first troubleshooting step.

Best,
Steven