Check IntendedFor field of the fmap’s JSON

Description of how to check and potentially update the fmap’s JSON file

The “IntendedFor” field of the fmap’s JSON file tells fmriPrep for which (functional) data the distortion correction should be applied to.

Depending on the conversion method you used to convert your DICOM to nifti files, the contents will look differently.

Additionally, depending on the version of fmriPrep you plan to use for preprocessing, you need different naming conventions of the entries.

In general, there are two naming conventions that might be used in the IntendedFor field:

BIDS uri spec necessary for fmriprep 24.0.0 or newer:

``` json
"IntendedFor": [
    "bids::sub-1181001/ses-1/func/sub-1181001_ses-1_task-movie_run-1_bold.nii.gz",
    "bids::sub-1181001/ses-1/func/sub-1181001_ses-1_task-movie_run-2_bold.nii.gz", 
    etc
    ]
```

Older fmap spec necessary for fmriprep older than 24.0.0:

``` json
"IntendedFor": [
    "ses-1/func/sub-1181001_ses-1_task-movie_run-1_bold.nii.gz",
    "ses-1/func/sub-1181001_ses-1_task-movie_run-2_bold.nii.gz",
    etc
    ]
```

With changing Versions of BIDS and BIDS-Apps, slight changes occur in how and where you have to include specific information. One example for this is the IntendedFor information in the fmap’s .json file.

Due to these differences and potential resulting problems (e.g. no distortion correction is applied), you should always check the content of the fmap’s “IntendedFor” field before running fmriPrep.

1 Check the content of the JSON file

Navigate to the fmap directory of a/each subject (*/bids/sub-999/ses-1/fmap/) and open the .json file

Scroll down to the very end of it. There should be a section that starts with IntendedFor and looks like this:

In General, all entries should follow the same naming convention (either the new or the old one, see above). If the naming convention corresponds to the fmriPrep version you want to use, you don´t have to change anything. If it does not correspond to the naming convention necessary for your version, you can follow the steps below to update the file.

Additionally, it may occur, that additional files are included in this field (e.g. files named “*part-phase*”) where no distortion correction should be applied to. Even if the naming convention is correct for your planned version of fmriprep, your should remove the entries of these files (see below)

2 Update “IntendedFor” field of the fmap’s JSON file

There is a dedicated script to update the contents of the fmap’s .json file. It can be found at /shared/update_json.py. To start and use the script:

1. Open a terminal

2. Type /shared/update_json.py

3. Indicate if you want to change the naming convention (independent of the current version, the old naming convention is changed to the new one and vice versa if you select 1 (=Yes) here)

4. Indicate if you want to remove entries from the field

5. If you want to remove entries, indicate the keywords that identify an entry to be removed

6. Provide the path to your bids directory

After providing all the inputs, the indicated changes will be performed and saved in the file automatically. Additionally, the original .json file will be saved as filename_orig.json (if the original entries are needed later again)