Change handling of field mapping information

Relates to #39 here, bids-standard/bids-specification#622 in BIDS 1.0, maybe others also. Had hoped to discuss at OHBM22 but didn't get the chance.

I really dislike having information regarding how an inhomogeneity field should be estimated ("B0FieldSource") and the images to which that estimate should be applied ("IntendedFor") encoded alongside image data sidecar information. The contents of those sidecars provide information about the image data themselves, how they were acquired, acquisition parameters, etc., whereas these fields relate specifically to how those data should be processed. We are currently bastardising the sidecar information that is specific to one image data file with content that relates to other image data files and the desired utilisation of such.

I would vastly prefer a solution where information relating to how a dataset should be processed is independent of the raw data themselves. The image sidecar JSONs that come out of eg. dcm2niix should remain untouched. Instead there should be a separate JSON file that is specifically intended to provide information about the intended utilisation of specific images.

In the specific context of B0 inhomogeneity field map estimates, one may theoretically have any number of field map estimates, which may come from different sources. Eg. If acquiring reversed phase encoding spin-echoes, and a subject moves a lot during the session, you may want to derive multiple field maps throughout the session, and for each fMRI run use only the most temporally proximal estimate. So that might look like (focusing more on concept than field names):

$ cat processing.json
{
    "B0FieldMaps": [
        "early": {
            "Sources": [
                "fmap/sub-###_dir-ap_run-1_epi.nii.gz",
                "fmap/sub-###_dir-pa_run-1_epi.nii.gz"
            ],
            "Sinks": [
                "func/sub-###_task-nback_bold.nii.gz"
                "func/sub-###_task-olr_bold.nii.gz"
            ]
        },
        "late": {
            "Sources": [
                "fmap/sub-###_dir-ap_run-2_epi.nii.gz",
                "fmap/sub-###_dir-ap_run-3_epi.nii.gz",
                "fmap/sub-###_dir-pa_run-2_epi.nii.gz"
                "fmap/sub-###_dir-pa_run-3_epi.nii.gz"
            ],
            "Sinks": [
                "func/sub-###_task-rest_bold.nii.gz"
            ]
        }
    ]
}

Theoretically, this concept of defining a text file that prescribes the intended image processing and inter-dependencies between data may not necessarily be constrained to just B0 inhomogeneity field mapping; hence the "B0FieldMaps" list at the root level. Curious to know if anyone with a wider breadth of experience can come up with more examples of such.

TL;DR: Separate processing instructions from raw data.

I will add to this thread a thought relating to https://github.com/bids-standard/bids-specification/issues/1655.

Unlike the OP, which focuses on metadata, this comment relates to the data files themselves.

Consider storage of image data from a dual-echo gradient echo experiment for field map estimation. The issue linked above relates specifically to case 1, which is a phase difference & magnitude image, but here I will talk in reference to "Case 2: Two phase maps and two magnitude images", just because it is the more extreme case.

Here's what the current specification shows:

sub-<label>/
    [ses-<label>/]
        fmap/
            sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude1.json
            sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude1.nii[.gz]
            sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude2.json
            sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude2.nii[.gz]
            sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase1.json
            sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase1.nii[.gz]
            sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase2.json
            sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase2.nii[.gz]

Now allow me to demonstrate an equivalent alternative (simplified for readability):

sub-<label>/
    [ses-<label>/]
        fmap/
            sub-<label>[_ses-<label>]_echo-1_part-mag_T2starw.json
            sub-<label>[_ses-<label>]_echo-1_part-mag_T2starw.nii[.gz]
            sub-<label>[_ses-<label>]_echo-1_part-phase_T2starw.json
            sub-<label>[_ses-<label>]_echo-1_part-phase_T2starw.nii[.gz]
            sub-<label>[_ses-<label>]_echo-2_part-mag_T2starw.json
            sub-<label>[_ses-<label>]_echo-2_part-mag_T2starw.nii[.gz]
            sub-<label>[_ses-<label>]_echo-2_part-phase_T2starw.json
            sub-<label>[_ses-<label>]_echo-2_part-phase_T2starw.nii[.gz]

Here I'm showing the data as still residing in the fmap/ modality directory, though this could hypothetically be up for debate also.

This example shows how information that everywhere else in the specification is encoded as entities---echo number and complex component---have instead been forced into suffices in this case. As stated in the TLDR in the OP, I believe this has happened because the intent of how the data should be used has been jammed into locations that otherwise describe what the data are, leading to incongruency in the specification. IMO, a BIDS App should be able to read from a file that indicates the intentions for processing, see that a field map source involves the use of complex data from a dual-echo gradient echo acquisition, and know whether it's capable of satisfying that intent.

It's a little trickier for field map case 1, where the scanner may have withheld the individual echo phases and instead emitted a phase difference map. And indeed as discussed in https://github.com/bids-standard/bids-specification/issues/1655 the nature of "the" magnitude image may be more convoluted. Whether that would be encoded by retaining the _phasediff suffix, as _part-phasediff, or as _part-phase with requisite sidecar metadata to indicate that it's a pre-calculated phase difference rather than absolute phase, would be an open discussion.

Not necessarily wed to the idea. And it may be me once again driving too far down purist avenue. But food for thought regardless.

bids-standard / bids-2-devel

Change handling of field mapping information #53