Heudiconv heuristics for field maps

1

I am trying to set up a heuristics file for a study with field maps, but I’m still confused after looking through the heudiconv example files and relevant parts of the BIDS 1.0.1 specification paper. The study acquires a field map before each functional/dwi scan type (i.e., one for each of four tasks and one for the dwi). The field maps correspond to case 4 in the BIDS specification, with two maps with different phase encoding directions.

First, should I use the “acq” field to denote the scan type the field map corresponds to? E.g., sub-01_ses-01_acq-rest_dir-PA_run-01_epi.nii.gz instead of
sub-01_ses-01_dir-PA_run-01_epi.nii.gz

Second, the different directions are showing up as separate runs. Is that expected? E.g.,
sub-01_ses-01_acq-rest_dir-PA_run-01_epi.nii.gz and
sub-01_ses-01_acq-rest_dir-AP_run-02_epi.nii.gz

Finally, and most importantly, how exactly do I add the “IntendedFor” field to the json? Can I do it in the heuristics file?

2

  1. Personally I say yes, the acq field is useful to identify which scan each fieldmap correspond to - but it’s not necessary as the IntendedFor in the json is the ultimate identifier.

  2. This may be happening because of double substitution in your heuristic file. In this heuristic, item is incremented for every fieldmap, regardless if the run is PA/AP. In another example, these keys are separated in order to generate sequential runs for each direction. AFAIK, both ways are fine.

  3. This hasn’t been implemented in heudiconv yet, we’re working on finding the best way to add this. Within the heuristics file is a great idea though! For my datasets, I’ve been adding it to the JSON after conversion.

Hope this helps!

3

Thank you. Your answers are very helpful.

1 and 2 are pretty clear now, but I’m still stuck on 3. When you figure out “IntendedFor” post-conversion, how do you know which functional files correspond to each field map from the converted files? Do you compare the “AcquisitionDateTime” values from the jsons?

4

I’ve only worked with two acquisitions of field maps, but took advantage of the acq-label from 1) to differentiate the two.

5

I have cobbled together something that should assign the appropriate scans for each field map based on the acquisition times, but I have a list of the absolute paths to the selected scan files. Do you know of a way to convert the absolute path to the necessary relative path with grabbids?

6

@tsalo I’m not sure there is a grabbids function for that - what I have been doing is splitting the path I defined as the root of my project.

import os

base = '/path/to/root'

rel_fmap = [x.split(base)[-1] for x in fieldmaps] # where fieldmaps is list of abspaths
7

Thanks. That works.

I’ve created a gist that adds the “IntendedFor” field to the fmap jsons based on acquisition time. I’ve tested it out on a couple of subjects, but I don’t know how well it will work on others. I’ll try to convert it to a real function at some point.