[ENH] Allow images in dwi and func to have an IntendedFor field in their json sidecar

[mattcieslak]

Currently EPI fieldmaps are stored in the fmap directory. The user specifies which scans in func or dwi the fieldmaps are supposed to correct via the IntendedFor field in the corresponding json sidecars.

Sometimes a whole DWI series is acquired with the reverse phase encoding direction of another DWI series and the low b images in each series are meant to correct the opposite PE direction series.

For this use case, would it be best to

1. Manually extract some low b images from each series into a new nifti file in fmaps with IntendedFor specified in its sidecar or
2. Add an IntendedFor field to the sidecars of the images in dwi and func?

Option 1 would go against keeping the images as raw as possible and would make automatic BIDS conversion very tricky. Option 2 might be confusing because images in dwi and func are not really "intended for" distortion correction.

I'd be very interested to hear opinions on this and happy to do a PR

[effigies]

Ah, I hadn't understood that you were proposing an IntendedFor field for the actual func/dwi images. I had interpreted you as saying that IntendedFor only linked fmap to func, not fmap to dwi.

Option 2 might be confusing because images in dwi and func are not really "intended for" distortion correction.

I think this is correct. If it will take modification to get them into a state where they can be used as fieldmaps, then it's misleading; if they're ready-to-use, then they're just fieldmaps. I think we need to consider the modified version derivatives (e.g., <bids>/derivatives/dwi2fmap/sub-01/fmap/sub-01_acq-PA_epi.nii.gz with an IntendedFor metadata field pointing to the correct DWI image), and work to make sure preprocessing pipelines can access derivatives.

In fMRIPrep, this is already something we need to do with regard to lesion masks and custom brain masks.

[mattcieslak]

How would the IntendedFor fields in <bids>/derivatives/dwi2fmap/sub-01/fmap/sub-01_acq-PA_epi.nii.gz get specified? A different field in the original image's sidecar? Or maybe rely on the ShimSettings and PhaseEncodingDirection to determine if images can be used to correct each other?

[francopestilli]

@mattcieslak @effigies are we expecting this to affect also how we save data related to the DWI modality?

[effigies]

@mattcieslak To make it concrete, suppose we start with:

bids/
    sub-01/
        dwi/
            sub-01_acq-AP_dwi.nii.gz
            sub-01_acq-PA_dwi.nii.gz
    ...

Neither of them should be directly used as a fieldmap, so we need to do some preprocessing on each to make it suitable for the other.

bids/derivatives/dwi2fmap/
    sub-01/
        fmap/
            sub-01_acq-AP_desc-preproc_epi.nii.gz
            sub-01_acq-AP_desc-preproc_epi.json
            sub-01_acq-PA_desc-preproc_epi.nii.gz
            sub-01_acq-PA_desc-preproc_epi.json

Following the BIDS derivatives dictum if any filename in a derivative dataset has a name permissible for a raw BIDS data, then that file must be an identical copy of that raw file I've added a desc-preproc entity to make it clear these are derivatives. And then we have the contents:

sub-01_acq-AP_desc-preproc_epi.json:

{
  "IntendedFor": ["sub-01/dwi/sub-01_acq-PA_dwi.nii.gz"]
}

sub-01_acq-PA_desc-preproc_epi.json:

{
  "IntendedFor": ["sub-01/dwi/sub-01_acq-AP_dwi.nii.gz"]
}

I do see one difference with the current language: The example IntendedFor metadata starts with func//dwi/, not sub-<label>/. While that works for files that are within the same subject directory, it seems to produce issues with derivatives. There's nothing specifically prohibiting more components, so this should be a clarification and making sure the tooling (i.e., pybids) will resolve cross-dataset IntendedFor links.

Does that make sense, or even address your question?

@francopestilli I'm trying to work within the existing specs as much as possible. If there ends up being a specific proposal to modify the spec, it should still be backwards compatible, so it shouldn't affect existing, valid datasets.

[mattcieslak]

I'm thinking about the common case where the sampling scheme is split up across multiple runs with different phase encoding directions. I've seen protocols with something like

bids/
    sub-01/
        dwi/
            sub-01_acq-AP_run-01_dwi.nii.gz
            sub-01_acq-PA_run-02_dwi.nii.gz
            sub-01_acq-AP_run-03_dwi.nii.gz
            sub-01_acq-PA_run-04_dwi.nii.gz

where it's not immediately clear which series should be paired together for correction. If there's not a best-practices heuristic it would be nice to let the person curating the data specify their intended pairing in the sidecars.

[oesteban]

@satra this conversation is highly related to some of the points you raised in poldracklab/fmriprep#1246

[effigies]

@mattcieslak Is it the case that these can be used directly, or they need to be preprocessed before they can be used? If the former, then I think there's a strong case for allowing IntendedFor for BOLD/DWI images. If the latter, then I think the approach I described above would apply:

bids/derivatives/dwi2fmap/
    sub-01/
        fmap/
            sub-01_acq-AP_run-01_desc-preproc_epi.nii.gz
            sub-01_acq-AP_run-01_desc-preproc_epi.json
            sub-01_acq-PA_run-02_desc-preproc_epi.nii.gz
            sub-01_acq-PA_run-02_desc-preproc_epi.json
            sub-01_acq-AP_run-03_desc-preproc_epi.nii.gz
            sub-01_acq-AP_run-03_desc-preproc_epi.json
            sub-01_acq-PA_run-04_desc-preproc_epi.nii.gz
            sub-01_acq-PA_run-04_desc-preproc_epi.json

sub-01_acq-AP_run-01_desc-preproc_epi.json:

{
  "IntendedFor": ["sub-01/dwi/sub-01_acq-PA_run-02_dwi.nii.gz"]
}

sub-01_acq-PA_run-02_desc-preproc_epi.json:

{
  "IntendedFor": ["sub-01/dwi/sub-01_acq-AP_run-01_dwi.nii.gz"]
}

And so on.

I think you may also be able to do something like the following:

bids/
    sub-01/
        dwi/
            sub-01_acq-AP_run-01_dwi.nii.gz
            sub-01_acq-PA_run-01_dwi.nii.gz
            sub-01_acq-AP_run-02_dwi.nii.gz
            sub-01_acq-PA_run-02_dwi.nii.gz

This would make it clearer that these pairs are associated, although that would simply be the curator's convention. The spec does not indicate that these should be interpreted as each others' fieldmaps.

[satra]

@effigies - almost no system generates ready to use fieldmaps. most of them requires some processing to generate a fieldmap that is then used for distortion correction. (and there are typically upto 4 types of distortion that need to be corrected for: gradient nonlinearity, B0, B1, eddy).

as noted earlier, in some cases some acquisitions of dwi are only collected for distortion correction (we have done this ourselves with 4B0 images), for some scans it's implicit like non-similar phase encoding for diffusion scans, and sometimes you may be able to use other scans to correct a given scan.

therefore there is a difference between intent (of the protocol) and possibilities for an automated routine like fmri/dmri/qsiprep (e.g., i could undistort epi bold images using information from diffusion images, if some acquisition settings were aligned - in this case it may not have been intended, but an analysis of the bids data may allow such a thing).

i think bids could encode intent and automation. whether it should is a community decision.

there is perhaps a broader conversation around IntendedFor when it comes to distortion correction.

[mattcieslak]

Although potentially confusing, I actually like the idea of allowing an optional IntendedFor in the dwi or func image metadata. It is familiar for anyone who has used this field for fieldmaps and could be directly copied into the metadata for the fmap-derivatives images suggested by @effigies.

[oesteban]

Hi @edickie, as per our dmriprep meeting, I've assigned you to this issue with the hopes we resurrect this and take it to the finish line.