fMRIPrep: problem with metadata field 'B0FieldIdentifier'

Summary of what happened:

I used fMRIPrep to preprocess a multi-session fMRI-experiment. Each session has two fMRI-task runs, an anatomical and a fieldmap scan. The fieldmap includes two magnitudes and a phase-difference map. Following BIDS (version 1.10.1) recommendations, I added a metadata field B0FieldIdentifier to the json-sidecar file of the phase-difference map (“B0FieldIdentifier”: “gre_fmap0”). Additionally, the field B0FieldSource was added to the json-sidecar files of the fMRI-task runs ("B0FieldSource": "gre_fmap0"). From my understanding, the complementary fields should explain to preprocessing software, what fieldmap-source is to be used for distortion correction during preprocessing of the functional images. However, fMRIPrep stopped with an error (posting here the three last lines of the error message from the html report):

File "/opt/conda/envs/fmriprep/lib/python3.12/site-packages/sdcflows/interfaces/fmap.py", line 329, in _run_interface
	    raise ValueError('Magnitude 1/2 orientation mismatch too big to ignore.')
	ValueError: Magnitude 1/2 orientation mismatch too big to ignore.

Scrolling up in the error message I found the reason for the mismatch:

mag_files: `['/data/651977/dataset/sub-MA102/ses-V2/fmap/sub-MA102_ses-V2_magnitude1.nii.gz', '/data/651977/dataset/sub-MA102/ses-V3/fmap/sub-MA102_ses-V3_magnitude2.nii.gz']`

As can be seen, the software was using the magnitude1 and magnitude2 images from different sessions (ses-V2 and ses-V3, respectively), instead of using the magnitudes from the same session.

Note, that each subject actually has 4 sessions, and when running the software on a full subject-dataset, fMRIPrep stopped at [Node] "_msmsulc1" found cached. and idled until I cancelled the job. Only when submitting 2 sessions, fMRIPrep ended with the error above that helped me to track down the problem. When I submitted a subject with a single session, the program worked fine, i.e. preprocessing was completed successfully including distortion correction.

Additionally, I added fields ‘IntendedFor’ to the phase-difference maps and indicated the BIDS-path to the functional scans meant for distortion correction. fMRIPrep worked fine when only ‘IntendedFor’ field was present. However, with both fields present (i.e., IntendedFor and B0FieldIdentifier), I ran into the problem described above.

Now, I am not sure whether my definition of B0FieldIdentifier/B0FieldSource is somehow mistaken, or whether there is an issue with this fMRIPrep version?

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

I used slurm:

module load fmriprep/25.1.3
fmriprep /data/${SLURM_JOB_ID}/dataset /data/${SLURM_JOB_ID}/derivatives participant \
  --fs-license-file ${FREESURFER_LICENSE} \
  --work-dir /data/${SLURM_JOB_ID}/workdir \
  --participant_label ${PARTICIPANT}

(I do not believe that the script will be helpful for solution, but can provide if needed).

Version:

25.1.3

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

Singularity

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

Bids-validator@1.14.10
(node:2388904) Warning: Closing directory handle on garbage collection
(Use `node --trace-warnings ...` to show where the warning was created)
	e[33m1: [WARN] The Authors field of dataset_description.json should contain an array of fields - with one author per field. This was triggered based on the presence of only one author field. Please ignore if all contributors are already properly listed. (code: 102 - TOO_FEW_AUTHORS)e[39m

e[36m	Please visit https://neurostars.org/search?q=TOO_FEW_AUTHORS for existing conversations about this issue.e[39m

	e[33m2: [WARN] The recommended file /README is very small. Please consider expanding it with additional information about the dataset. (code: 213 - README_FILE_SMALL)e[39m
		./README

e[36m	Please visit https://neurostars.org/search?q=README_FILE_SMALL for existing conversations about this issue.e[39m

        e[34me[4mSummary:e[24me[39m                  e[34me[4mAvailable Tasks:e[24me[39m          e[34me[4mAvailable Modalities:e[39me[24m 
        67 Files, 558.41MB        task-neurofeedback        MRI                   
        1 - Subject                                                               
        2 - Sessions 

Relevant log outputs (up to 20 lines):

250930-18:50:50,106 nipype.workflow CRITICAL:
	 fMRIPrep failed: Traceback (most recent call last):
  File "/opt/conda/envs/fmriprep/lib/python3.12/site-packages/nipype/pipeline/plugins/multiproc.py", line 67, in run_node
    result["result"] = node.run(updatehash=updatehash)
                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/conda/envs/fmriprep/lib/python3.12/site-packages/nipype/pipeline/engine/nodes.py", line 525, in run
    result = self._run_interface(execute=True)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/conda/envs/fmriprep/lib/python3.12/site-packages/nipype/pipeline/engine/nodes.py", line 643, in _run_interface
    return self._run_command(execute)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/conda/envs/fmriprep/lib/python3.12/site-packages/nipype/pipeline/engine/nodes.py", line 769, in _run_command
    raise NodeExecutionError(msg)
nipype.pipeline.engine.nodes.NodeExecutionError: Exception raised while executing Node check_register.

Traceback:
	Traceback (most recent call last):
	  File "/opt/conda/envs/fmriprep/lib/python3.12/site-packages/nipype/interfaces/base/core.py", line 401, in run
	    runtime = self._run_interface(runtime)
	              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	  File "/opt/conda/envs/fmriprep/lib/python3.12/site-packages/sdcflows/interfaces/fmap.py", line 329, in _run_interface
	    raise ValueError('Magnitude 1/2 orientation mismatch too big to ignore.')
	ValueError: Magnitude 1/2 orientation mismatch too big to ignore.

Screenshots / relevant information:

not included


Hi @christianparet,

In the future, please format your code and terminal outputs for readability using tickmarks / the </> button in the text editor. You can see I edited your post for you this time.

You can just change your B0Field* metadata to be session specific (e.g., gre_fmap0_ses_V1).

Yes, when B0Field* metadata are specified, they override IntendedFor.

Best,
Steven

Thank you, Steven. Obviously, changing the B0Field* metadata is a solution. Still, this finding could be considered for fixing in the future, because the issue becomes very hard to debug with datasets of 3+ sessions (in this case the program idles and no error message is received).