enh: allow encoding the fieldmapping intent of the protocol

This PR addresses the problem @mattcieslak spotted at in bids-standard#239.

This enhancement (WIP) basically allows for researchers to encode
the protocol's intent regarding fieldmaps.

As @satra introduced in bids-standard#239 (comment),
BIDS "*could encode intent and automation. Whether it should is a community decision."

This PR proposes a solution to encoding the intent. It doesn't modify
anything to allow also encoding automation.

The PR attempts to be backwards compatible.

I'm submitting this draft PR to open discussions and looking forward to
feedback.

Resolves: bids-standard#239.
References: #263, nipreps/dmriprep#43, bids-standard/bids-2-devel#39

src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

@@ -104,6 +104,24 @@ Useful for multimodal co-registration with MEG, (S)EEG, TMS, etc.
 | ----------------------------- | --------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | AnatomicalLandmarkCoordinates | RECOMMENDED           | [object][] of [arrays][] | Key:value pairs of any number of additional anatomical landmarks and their coordinates in voxel units (where first voxel has index 0,0,0) relative to the associated anatomical MRI, (e.g. `{"AC": [127,119,149], "PC": [128,93,141], "IH": [131,114,206]}, or {"NAS": [127,213,139], "LPA": [52,113,96], "RPA": [202,113,91]}`). |
 
+### Echo-Planar Imaging & B0 field-mapping
+
+Echo-Planar Imaging (EPI) schemes typically used in the acquisition of
+diffusion and functional MRI may also be *intended for* estimating the
+*B=0* field inside the scanner (in other words, *estimating the fieldmap*,)
+without the acquisition of additional MRI schemes such as gradient-recalled
+echo (GRE) sequences that are stored under the `fmap/` folder of the
+BIDS structure.
+
+The modality labels `dwi` (under `dwi/`), `bold`, and `sbref` (under `func/`)
+and any modality under `fmap/` are allowed to encode the MR protocol intent for
+fieldmap estimation using the following metadata:
+
+| **Key name**                | **Requirement level** | **Data type** | **Description**                                                                                                                                                          |
+| --------------------------- | --------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| B0FieldIdentifier           | OPTIONAL              | [string][]    | The presence of this key states that this particular 3D or 4D image may be used for fieldmap estimation purposes. The `B0FieldIdentifier` MUST be a unique string within one participant's tree, shared only by the images meant to be used as inputs for the estimation of a particular instance of the *B0 field* estimation.                                                                                                                                               |
+| B0FieldSource               | OPTIONAL              | [string][] or [list][] of [string][]    | At least one existing `B0FieldIdentifier` defined by other images in the participant's tree. This field states the *B0 field* estimation designated by the `B0FieldIdentifier` that may be used to correct the dataset for distortions caused by B0 inhomogeneities. `B0FieldSource` and `B0FieldIdentifier` are mutually exclusive. When a list of identifiers is given, the estimated fieldmap may be averaged across the different sources.      |
+
 ### Institution information
 
 | **Key name**                | **Requirement level** | **Data type** | **Description**                                                                                                                                                          |
@@ -359,7 +377,8 @@ sub-control01/
    "PhaseEncodingDirection": "j",
    "InstitutionName": "Stanford University",
    "InstitutionAddress": "450 Serra Mall, Stanford, CA 94305-2004, USA",
-   "DeviceSerialNumber": "11035"
+   "DeviceSerialNumber": "11035",
+   "B0FieldSource": ["phasediff_fmap0", "pepolar_fmap0"]
 }
 ```
 
@@ -440,16 +459,28 @@ JSON example:
 ```JSON
 {
   "PhaseEncodingDirection": "j-",
-  "TotalReadoutTime": 0.095
+  "TotalReadoutTime": 0.095,
+  "B0FieldSource": ["phasediff_fmap0", "pepolar_fmap0"]
 }
 ```
 
 ## Fieldmap data
 
+### Using `B0FieldIdentifier` metadata
+
+The general purpose `B0FieldIdentifier` MRI metadata is RECOMMENDED for the
+prescription of the B0 field estimation intent of the original acquisition
+protocol.
+This encoding fully overrides the `IntendedFor` approach (see below).
+However, the `IntendedFor` encoding is permitted and RECOMMENDED in combination
+with the `B0FieldIdentifier` to maintain compatibility with outdated software.
+
+### Using `IntendedFor` metadata
+
 Data acquired to correct for B0 inhomogeneities can come in different forms. The
 current version of this standard considers four different scenarios. Please note
 that in all cases fieldmap data can be linked to a specific scan(s) it was
-acquired for by filling the IntendedFor field in the corresponding JSON file.
+acquired for by filling the `IntendedFor` field in the corresponding JSON file.
 For example:
 
 ```JSON
@@ -469,7 +500,7 @@ slashes. Here's an example with multiple target scans:
 }
 ```
 
-The IntendedFor field is OPTIONAL and in case the fieldmaps do not correspond to
+The `IntendedFor` field is OPTIONAL and in case the fieldmaps do not correspond to
 any particular scans it does not have to be filled.
 
 Multiple fieldmaps can be stored.