Getting fieldmaps (or other multi-echo data) into BIDS format

Hi, all,

I’m trying to convert a dataset with field maps into BIDS format, and I’m having trouble using heudiconv to do it.

I have a sequence (fm2d2r) that generates two series_id lines in the dicominfo.tsv. The first series_id has 118 TRs, representing 2 3-d magnitude images (with different echo times). The second series_id has 59 TRs and represents the phase map.

In BIDS, this should look like:

<+3 json files>

But, because there is only 1 series listed in the dicominfo.tsv, heudiconv doesn’t know to create files for both magnitude images. (This issue is addressed here, as well: )

Is there a recommended way to work around this?


Hi Todd,

I have come across a similar issue you are describing. I found that while using heudiconv there were some files I knew had multiple scans, but only showed up as a single line in the dicominfo.tsv file.
I found that it was really dependent on dcm2niix to find that there are two different files and name them properly (as you identified what the output should be). I found dcm2niix did indeed do that for my set.
Have you tried going through to create your heuristic file and run heudiconv to see if dcm2niix will find it?
If you are unsure, we have a tutorial ( walking through how you may be able to run heudiconv.

Thank you,

There’s actually another open issue on heudiconv for proper handling of multi-echo data:

My understanding at this point is that dcm2niix properly handles the files, but heudiconv does not. There were two suggestions in the github issue you linked, Todd, that seem viable (either editing the save_converted_files function in or co-opting custom_callable() in the heuristics file), though I’m not sure of a current preference between them !

Longer term, getting multi-echo support integrated into heudiconv would be great ! There was a PR started on this:



I’m wondering if there has been progress made with getting spin-echo field maps and BIDS compliance since the posts in this discussion are from 2018:

We have collected 2 spin-echo field maps (A-P and P-A) and phase-diff maps - is fMRIPrep able to handle these non-traditional fieldmaps? (We’re not able to get them BIDS compliant)

If fMRIPrep is not able to handle spin-echo fieldmaps yet (I did see there is a BIDS Extension Proposal - BEP001 - that may be working on this?) - is there a recommendation in regards to no fieldmaps vs. fieldmap-less option? (The documentation highlights that the -less option is experimental, which makes us a little leery)

Hi @NRob

It appears the PRs referenced have been worked on since and support for multi-echo images.

Regarding the BIDS compliance - what may be the errors? BIDS supports spin-echo filed maps with multiple directions along with phase-diff maps.

Perhaps @oesteban or @effigies may have suggestions on the fMRIPrep implementation regarding field maps.

Thank you,

Hi Franklin,
Thank you so much for your response. When we try to run the BIDS validater at the start of fMRIPrep, we get the following error:
Evidence: sub-3054_ses-1_run-1_ap.json
Evidence: sub-3054_ses-1_run-1_ap.nii.gz
Evidence: sub-3054_ses-1_run-2_pa.json
Evidence: sub-3054_ses-1_run-2_pa.nii.gz

(I also edited my previous question for clarity - said multi echo a few times, I meant spin-echo. We collected spin-echo field maps with multiple directions, want to use in conjunction with multi echo functional data)


Hi @NRob

Regarding the BIDS Validation - the file names are close to being BIDS validated! For example:
sub-3054_ses-1_run-1_ap.json can be fixed to sub-3054_ses-1_dir-ap_run-1_epi.json. This will filename scheme can be applied to your field maps (both nii.gz and json) that are multiple phase-encoded directions. Another method to check the validation can be using our web client.

Thank you,

1 Like

Thank you, Franklin, that was very helpful. However, I have my fieldmaps passing through BIDS validation, but fMRIPrep is ignoring them?

My fieldmaps are as follows:

When I run the participant through fMRIPrep, it runs, but I get the following note at the start:
191120-19:25:30,313 nipype.workflow WARNING:
SDC: no fieldmaps found or they were ignored (/projects/MNA/data/Nifti/sub-3054/ses-1/func/sub-3054_ses-1_task-cert1_run-001_echo-1_bold.nii.gz).

In the link that you provided, I saw that you can edit the .json files with an “IntendedFor” statement, but it’s optional if you want you want to specify particular runs. We don’t want to specify particular runs, but I could add this to both .json files and specify all of the runs? I’m not sure what else the problem could be? Thanks for any clarification!


Hi @NRob

Great to hear the dataset is BIDS validated!

This sounds like it can be a result of the missing IntendedFor field. I think that approach you described can work! It will be interesting to see what fMRIPrep thinks after making this edit.

Thank you,

@emdupre is it possible that, even having correctly set the IntendedFor entry on the metadata, fMRIPrep discards fieldmaps for multi-echo data? (i.e., could this be a bug?)

We set the IntendedFor entry on the metadata, and fMRIPrep ran, this time recognizing the fieldmaps. In the boiler plate at the end of the .html doc, it states:

“A deformation field to correct for susceptibility distortions was estimated based on two echo-planar imaging (EPI) references with opposing phase-encoding directions, using 3dQwarp. Based on the estimated susceptibility distortion, an unwarped BOLD reference was calculated for a more accurate co-registration with the anatomical reference. The Bold reference was then co-registered to the T1w reference using bbregister which implements boundary-based registration. Co-registration was configured with six degrees of freedom.”

However, in the images/movies above, it shows significant distortion. The ‘after’ images for the ‘Susceptibiltiy distortion correction’ look like they were (extremely) overcorrected. We’re wondering if having the spin echos labeled as _EPI files (per @franklin suggestion above) causes fMRIPrep to make assumptions about the files? Our spin echos are not EPIs. Could this be causing a problem? (The boiler plate is also incorrect for our preprocessing as it refers to our spin echos as “two echo-planar imaging (EPI) references with opposing phase-encoding directions”.)