Improve documentation on debugging bad IntendedFor/B0Field specs

[JunhongYu]

What happened?

fMRIprep 25.0.0 was able to complete preprocessing this dataset https://openneuro.org/datasets/ds004630/versions/1.1.3 without any errors being reported. However the fmaps were not applied.

I've checked that the *_phasediff.json files had the correct IntendedFor arguments, but they were missing for *_magnitude1.json and *_magnitude2.json . I've added the IntendedFor arguments to these 2 jsons and did a fresh fMRIprep run on sub-06, but the fmaps were not applied as well.

It appears that the authors of this dataset had no problems with the fmaps when they ran fMRIPrep 20.2.6 previous; the output of this fMRIprep 20.2.6 run is contained in derivatives/fmriprep directory of their openneuro repository

What command did you use?

fmriprep $subdir $output_dir participant -w $work_dir \
    --output-spaces MNI152NLin6Asym --cifti-output 91k \
    --participant-label sub-06 --nthreads 16 --omp-nthreads 16

What version of fMRIPrep are you running?

25.0.0

How are you running fMRIPrep?

Local installation ("bare-metal")

Is your data BIDS valid?

Yes

Are you reusing any previously computed results?

FreeSurfer

Please copy and paste any relevant log output.

Additional information / screenshots

No response

[smeisler]

I have replicated this error on this dataset, and have confirmed they still persist when (1) gzipping all .nii-->.nii.gz. (2) using B0FieldSource/Identifier method (3) changing the fmap phase encoding direction to be opposite the bold.

[smeisler]

This issue would probably be better migrated to SDCFlows.

[effigies]

Done. @smeisler I haven't had a chance to look into this at all, but maybe we can sync up later today/tomorrow?

[effigies]

Alright. I've had a look at this. @GerardYu Thanks for your patience!

There are some issues with the B0Field* specifications:

$ git grep B0Field
sub-03/fmap/sub-03_magnitude1.json:    "B0FieldIdentifier": "magnitude1_fmap",
sub-03/fmap/sub-03_magnitude1.json:    "B0FieldIdentifier": "magnitude1_fmap",
sub-03/fmap/sub-03_magnitude2.json:    "B0FieldIdentifier": "magnitude2_fmap",
sub-03/fmap/sub-03_magnitude2.json:    "B0FieldIdentifier": "magnitude2_fmap",
sub-03/fmap/sub-03_phasediff.json:  "B0FieldIdentifier": "phasediff_fmap",
sub-05/fmap/sub-05_magnitude1.json:    "B0FieldIdentifier": "magnitude1_fmap",
sub-05/fmap/sub-05_magnitude2.json:    "B0FieldIdentifier": "magnitude2_fmap",
sub-05/fmap/sub-05_phasediff.json:  "B0FieldIdentifier": "phasediff_fmap",

1. This declares 3 B0FieldIdentifiers for the entire dataset: magnitude1_fmap, magnitude2_fmap, and phasediff_fmap. Each of these fieldmaps will have one type of file across all subjects. Instead you need all three types of file to have the same value, and this should be distinct, per-subject. e.g.:

sub-03/fmap/sub-03_magnitude1.json:    "B0FieldIdentifier": "sub3_phasediff",
sub-03/fmap/sub-03_magnitude2.json:    "B0FieldIdentifier": "sub3_phasediff",
sub-03/fmap/sub-03_phasediff.json:  "B0FieldIdentifier": "sub3_phasediff",
sub-05/fmap/sub-05_magnitude1.json:    "B0FieldIdentifier": "sub5_phasediff",
sub-05/fmap/sub-05_magnitude2.json:    "B0FieldIdentifier": "sub5_phasediff",
sub-05/fmap/sub-05_phasediff.json:  "B0FieldIdentifier": "sub5_phasediff",

2. The B0FieldIdentifier is duplicated in sub-03. Whatever comes last will take precedence, so you need to be careful while fixing this. I would deduplicate and then fix.

3. There is no B0FieldSource in BOLD files. Even though you can estimate the fieldmaps, it won't be applied. You need something like:

sub-03/func/sub-03_task-passiveview_run-1_bold.nii:  "B0FieldSource": "sub3_phasediff",