BIDS Curation Tutorial Part 5: Fieldmaps and IntendedFor
Introduction
As described in the BIDS Specification, fieldmaps are typically acquired with the purpose of correcting one or more EPI scans under func/ordwi/for distortions derived from B0 nonuniformity. The IntendedFor field (set in the .json sidecar of a fieldmap NIfTI file) is a list of relative paths to the files the fieldmap is intended to correct.
Using Fieldmaps on Functional and Diffusion Acquisitions
The BIDS Curation Gear uses “resolvers” as the final step of processing to set IntendedFor paths. The default reproin project curation template specifies only the folders where the files to be corrected are found. Resolvers are used to list all of the possible files in those folders that the fieldmap might be used to correct. To filter this list so that it contains only some of the files in the folders, regular expression (regex) pairs are used in the BIDS Curation gear configuration. By default, the resolvers populate the IntendedFors list for each fieldmap with all of the files in the anat, dwi, and func folders.
For those studies using custom project curation templates, more details can be added to the template to directly filter the IntendedFor lists without the need to add regexes when running the BIDS Curation Gear. See our article on the template file for more details.
Default curation of IntendedFor lists
For this example of using fieldmaps on functional acquisitions, we'll use a new dataset which has three fieldmaps.
Acquisitions view: 
BIDS view: 
If this dataset is processed using the default reproin template, without specifying regular expressions, below are what the IntendedFor lists would look like for:
fmap-SE-APsub-01/ses-01/anat/sub-01_ses-01_T1w.nii.gz sub-01/ses-01/anat/sub-01_ses-01_T2w.nii.gz sub-01/ses-01/anat/sub-01_ses-01_FLAIR.nii.gz sub-01/ses-01/dwi/sub-01_ses-01_dir-AP_dwi.nii.gz sub-01/ses-01/dwi/sub-01_ses-01_dir-PA_dwi.nii.gz sub-01/ses-01/func/sub-01_ses-01_task-bart_run-1_bold.nii.gz sub-01/ses-01/func/sub-01_ses-01_task-bart_run-2_bold.nii.gz sub-01/ses-01/func/sub-01_ses-01_task-rest_run-1_bold.nii.gz sub-01/ses-01/func/sub-01_ses-01_task-rest_run-2_bold.nii.gzfmap-SE-PAsub-01/ses-01/anat/sub-01_ses-01_T1w.nii.gz sub-01/ses-01/anat/sub-01_ses-01_T2w.nii.gz sub-01/ses-01/anat/sub-01_ses-01_FLAIR.nii.gz sub-01/ses-01/dwi/sub-01_ses-01_dir-AP_dwi.nii.gz sub-01/ses-01/dwi/sub-01_ses-01_dir-PA_dwi.nii.gz sub-01/ses-01/func/sub-01_ses-01_task-bart_run-1_bold.nii.gz sub-01/ses-01/func/sub-01_ses-01_task-bart_run-2_bold.nii.gz sub-01/ses-01/func/sub-01_ses-01_task-rest_run-1_bold.nii.gz sub-01/ses-01/func/sub-01_ses-01_task-rest_run-2_bold.nii.gzgre-field-mappingsub-01/ses-01/anat/sub-01_ses-01_T1w.nii.gz sub-01/ses-01/anat/sub-01_ses-01_T2w.nii.gz sub-01/ses-01/anat/sub-01_ses-01_FLAIR.nii.gz sub-01/ses-01/dwi/sub-01_ses-01_dir-AP_dwi.nii.gz sub-01/ses-01/dwi/sub-01_ses-01_dir-PA_dwi.nii.gz sub-01/ses-01/func/sub-01_ses-01_task-bart_run-1_bold.nii.gz sub-01/ses-01/func/sub-01_ses-01_task-bart_run-2_bold.nii.gz sub-01/ses-01/func/sub-01_ses-01_task-rest_run-1_bold.nii.gz sub-01/ses-01/func/sub-01_ses-01_task-rest_run-2_bold.nii.gz
Contents of intendedfors.csv file
In the above examples, we have abbreviated the IntendedFors lists to just highlight the NIfTI files. When examining the _intendedfors.csv file contents, you will see all of the files in the anat, func, and dwi folders (e.g., .nii.gz, .json, .bval, .bvec, etc.).
Guidelines for setting up the regular expressions
Regular expressions can seem daunting to draft. This section aims to give some general tips and guidelines to help you understand how the BIDS Curation Gear interprets these regexes and hopefully demystify setting these up for your study.
The first half of each regex pair uses the acquisition label to find the desired fieldmap file. So, for our current example dataset, .*fmap(_|-)SE(_|-).* could be used to map to both fmap-SE-AP and fmap-SE-PA acquisition labels. While, .*gre-.* could be used to map to the gre-field-mapping acquisition label.
Since by default, the BIDS Curation Gear populates the initial IntendedFor list for each fieldmap file with all possible BIDS filepaths that the fieldmap could be applied to, the second half of each regex pair uses the Curated BIDS path to find the desired functional or diffusion NIfTI files. So, .*_bold.nii.gz would map to all of the functional NIfTI files, and .*_dwi.nii.gz would map to all of the diffusion NIfTI files.
Regex pairs for matching fieldmaps with function/diffusion scans
Use the acquisition label to map to a desired fieldmap and the Curated BIDS path to map to the image files to add to the IntendedFor list for the desired fieldmap.
How to include regular expressions during BIDS Curation
When running the BIDS Curation Gear, a list of one or more regex pairs is included as part of the gear configuration.
Example 1: Applying fieldmaps to different functional acquisitions
For this example, let's say we want to apply the SE fieldmaps to the first run of both the bart and rest tasks and the gre fieldmap to the second run of both tasks.
In this example, we need two regex pairs to correctly filter the correct functional acquisitions to the desired fieldmaps:
So, in the above example, the first regex of the first pair, .*fmap(_|-)SE(_|-).*, matches the acquisition labels fmap-SE-AP and fmap-SE-PA , and the second regex of the first pair, _run-1_bold.nii.gz, matches the Curated BIDS paths for the first runs of both functional tasks.
Similarly, the first regex of the second pair, .*gre-.* matches the gre-field-mapping acquisition label, and the second regex of the second pair, _run-2_bold.nii.gz matches the Curated BIDS paths of the second runs of both functional tasks.
Note that including _bold in the regexes filters out the single-band reference (SBRef) acquisitions, and specifying .nii.gz filters out any files that are not NIfTI image files.
Including the above list of regex pairs in the config of the BIDS Curation Gear results in the below IntendedFor lists for both the fmap-SE-AP and fmap-SE-PA files:
sub-01/ses-01/func/sub-01_ses-01_task-bart_run-1_bold.nii.gz
sub-01/ses-01/func/sub-01_ses-01_task-rest_run-1_bold.nii.gz
Similarly, for gre-field-mapping the IntendedFor list after using including the list of regexes in the BIDS Curation Gear configuration looks like:
sub-01/ses-01/func/sub-01_ses-01_task-bart_run-2_bold.nii.gz
sub-01/ses-01/func/sub-01_ses-01_task-rest_run-2_bold.nii.gz
Example 2: Apply fieldmaps to both diffusion and functional acquisitions
Unlike Datasets 1 and 2 used for the first four parts of this tutorial series, the current dataset has both functional and diffusion scans. It is quite common to acquire different fieldmaps to correct diffusion scans and functional scans individually.
Let's work up a set of regexes that will apply the fmap-SE-AP fieldmap to the *_dir-PA_dwi.nii.gz Curated BIDS path, the fmap-SE-PA fieldmap to the *_dir-AP_dwi.nii.gz Curated BIDS path, and the gre-field-mapping fieldmap to all of the *_bold.nii.gz Curated BIDS paths.
In this case, we need three pairs of regexes, one for each fieldmap.
.*fmap(_|-)SE(_|-)AP.* _dir-PA_dwi.nii.gz .*fmap(_|-)SE(_|-)PA.* _dir-AP_dwi.nii.gz .*gre-.* _bold.nii.gz
The first pair matches the fmap-SE-AP acquisition label with the dwi/*_dir-PA_dwi.nii.gz Curated BIDS path.
fmap-SE-AP IntendedFor list:
The second pair matches the fmap-SE-PA acquisition label with the dwi/*_dir-AP_dwi.nii.gz Curated BIDS path.
fmap-SE-PA IntendedFor list:
Finally, the third pair matches the gre-field-mapping acquisition label with the func/*_bold.nii.gz Curated BIDS path.
gre-field-mapping IntendedFor list:
sub-01/ses-01/func/sub-01_ses-01_task-bart_run-1_bold.nii.gz
sub-01/ses-01/func/sub-01_ses-01_task-bart_run-2_bold.nii.gz
sub-01/ses-01/func/sub-01_ses-01_task-rest_run-1_bold.nii.gz
sub-01/ses-01/func/sub-01_ses-01_task-rest_run-2_bold.nii.gz
Finishing up with Part 5
If you are using relabeling to ReproIn-compliant acquisition labels and the default reproin template for BIDS curation, then you should now have an understanding of the steps needed to successfully prepare, relabel, and curate your own dataset into BIDS format using Flywheel's tools.
If you are using an existing custom study curation template or creating your own custom study curation template, the next part will cover how extend curation templates and set up local debugging of a custom curation template. Continue to Part 6: Troubleshooting and Debugging to learn more about handling custom study curation templates.