Organization of fieldmaps in BIDS for both diffusion and multi-echo fMRI data


We are trying to organize the fieldmaps for both diffusion and multi-echo fMRI in our BIDS dataset for fMRIPrep and QSIPrep use.

We have separate fieldmaps for our diffusion data and multi-echo fMRI data. How do we organize it? Should we place both types of fieldmaps in the ‘fmap’ folder or should we place them in their respective folders ‘dwi’ and ‘func’?

We have tried:

  • When we placed the both types of fieldmaps under the ‘fmap’ folder: QSIPrep works, fMRIPrep does not read in the correct fieldmap
  • When we placed both types of fieldmaps in their respective folders (‘dwi’ and ‘func’): fMRIPrep works, QSIPrep does not work

We have ‘IntendedFor’ and ‘B0FieldIdentifier’ in all of the fieldmap json files.

It would be really helpful if someone has experience with organizing fieldmaps of different modalities in the same database.

Thank you so much!!!

1 Like

Hi @janhavi-pillai and welcome to neurostars!

It should all go in the fmap folder.

It would help to see the file organization for a subject and some JSONs for us to debug.


Thank you for the quick response!

This is how we have it organized now… not sure if any of the naming conventions are wrong.

Do you mean the fieldmap json from a single subject? Or the error output from fMRIPrep or QSIPrep?

Have you run the BIDS validator on this dataset? From what I can tell it mostly looks good, but there might be metadata that is not right. However, the dir-<> label in the DWI files should be AP or PA (corresponding to the phase encoding direction), not the number of directions. The number of directions can be added to the acq-<> label, e.g., acq-b500dir30.

Yes ^, e.g., a sub-XXX_ses_xxx_axq-xxx_dir-XX_epi.json file.


  • fieldmaps go in the fmap folders
  • IntendedFor should be sufficient for softwares to know to which files those fieldmaps should be applied to

As mentioned make sure your dataset passes the bids validation (in general just make sure you do not skip validation when running fmriprep).

If we could we see the content of one of the json for the fieldmap this may also help figure out if there is an issue (like a typo in the IntededFor?)

Also which version of fMRIPrep and QSIPrep are you using?

And giving us the part of the fMRIPrep and QSIPrep log that makes you say 'it does not work" may help us help you.

Fieldmaps go in the fmap folder, but sometimes you have pepolar fieldmap scans that serve both as dwi data as well as fieldmap data (e.g. when you have 100 dir-PA + 100 dir-AP scans). The only working solution for me is that I put all the data in the dwi folder and then copy a few volumes of each direction in the fmap folder, otherwise SDC flows cannot find them (even if I properly label them with both B0FieldIdentifier/Source). I haven’t seen documentation on this and I’m always wondering if what I do is the best I can do according to the BIDS specifications :slight_smile:

@Marcel_Zwiers the fieldmap handling for DWIs isn’t well-described in the BIDS spec. There are a couple things that make this tough. bval/bvec are not allowed in the fmap directory. This is a big issue for Siemens, which won’t let you do b=0 only scans in many dwi sequences.

The way qsiprep handles this is, for each distortion group,

  1. Grab all the b=0 images in that distortion group from _dwi.nii files in the dwi directory
  2. If you have a secret (hidden by a line in .bidsignore) bval/bvec file in fmap, use it to extract the b=0’s from the epi fieldmaps in the fmap directory from that distortion group. If no bval/bvec grab all of the images from the epi fieldmap. The bval/bvec don’t matter under normal circumstances because of what happens next
  3. Calculate the pairwise correlation between all b=0 images in this distortion group. The images are ranked by their mean correlation to all other images and the best N are picked to use for distortion correction. b>0 images don’t score well here and aren’t picked.

The gathering method is implemented here and the actual images chosen per each distortion group will be described in your html report.