[ENH] Recommend reporting of BigDelta and SmallDelta for DWI images

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

@@ -900,7 +900,36 @@ A guide for using macros can be found at
    }
 ) }}
 
-### Other RECOMMENDED metadata
+### Combined DWI schemes
+
+Some DWI schemes are acquired by varying parameters including the
+[`EchoTime (TE)`](../glossary.md#objects.metadata.EchoTime),
+[`SmallDelta (δ)`](../glossary.md#smalldelta-metadata),
+[`BigDelta (Δ)`](../glossary.md#bigdelta-metadata);
+in addition to varying the diffusion-encoding weightings (b-values) and
+gradients (b-vectors).
+
+For instance, in a single run the
+[Connectome 2.0 scanner](https://doi.org/10.1016/j.neuroimage.2021.118530)
+collects DWI volumes where the `EchoTime`, `SmallDelta`, and `BigDelta` parameters can be varied. The DWI
+volumes are concatenated in a single file and processed together with the `EchoTime`, `SmallDelta`,
+and `BigDelta` values.
+
+BIDS permits saving the `EchoTime`, `SmallDelta`, and `BigDelta` values corresponding to the *N*
+volumes in the NIfTI file. The `EchoTime`, `SmallDelta`, and `BigDelta` values MAY be stored as an array in the sidecar JSON file.
+If a single `EchoTime`, `SmallDelta`, or `BigDelta` value is used for the entire acquisition, the value
+MAY be stored as a single number in the sidecar JSON file.
+The `EchoTime`, `SmallDelta`, and `BigDelta` values MUST be specified in seconds.
+
+The `EchoTime`, `SmallDelta`, and `BigDelta` fields MAY be
+saved in the sidecar JSON file on any level of the directory structure and thus define those values for
+all sessions and/or subjects in one place (see
+[the inheritance principle](../common-principles.md#the-inheritance-principle)).
+
+As an exception to the [common principles](../common-principles.md#definitions)
+that parameters are constant across runs, the `EchoTime`, `SmallDelta`, and `BigDelta` values MAY change across the DWI run.
+
+### Other metadata fields
 
 <!-- This block generates a metadata table.
 These tables are defined in
@@ -922,6 +951,8 @@ JSON example:
 
 ```JSON
 {
+  "BigDelta": 0.040,
+  "SmallDelta": 0.015,
   "PhaseEncodingDirection": "j-",
   "TotalReadoutTime": 0.095,
   "B0FieldSource": ["phasediff_fmap0", "pepolar_fmap0"]

src/schema/objects/metadata.yaml

@@ -351,6 +351,24 @@ BasedOn:
       items:
         type: string
         format: participant_relative
+BigDelta:
+  name: BigDelta
+  display_name: Diffusion Big Delta (Δ)
+  description: |
+    In the context of a diffusion-weighted pulsed gradient spin echo sequence,
+    corresponds to the time between the leading edges of two successive
+    diffusion-encoding gradient pulses (Δ), specified in seconds.
+    The value may be an array, if Δ varies by volume, in which case the number
+    of values MUST correspond to the number of volumes in the data file.
+  anyOf:
+    - type: number
+      unit: s
+      exclusiveMinimum: 0
+    - type: array
+      items:
+        type: number
+        unit: s
+        exclusiveMinimum: 0
 BloodDensity:
   name: BloodDensity
   display_name: Blood Density
@@ -939,6 +957,38 @@ DewarPosition:
     `"upright"`, `"supine"` or `"degrees"` of angle from vertical:
     for example on CTF systems, `"upright=15°, supine=90°"`.
   type: string
+DiffGradientDuration:
+  name: DiffGradientDuration
+  display_name: Diffusion Gradient Duration
+  description: |
+    In the context of a diffusion-weighted pulsed gradient spin echo sequence,
+    corresponds to the duration of a diffusion-encoding gradient pulse (δ),
+    specified in milliseconds.
+  anyOf:
+    - type: number
+      unit: ms
+      exclusiveMinimum: 0
+    - type: array
+      items:
+        type: number
+        unit: ms
+        exclusiveMinimum: 0
+DiffGradientSeparation:
+  name: DiffGradientSeparation
+  display_name: Diffusion Gradient Separation
+  description: |
+    In the context of a diffusion-weighted pulsed gradient spin echo sequence,
+    corresponds to the time between the leading edges of two successive
+    diffusion-encoding gradient pulses (Δ), specified in milliseconds.
+  anyOf:
+    - type: number
+      unit: ms
+      exclusiveMinimum: 0
+    - type: array
+      items:
+        type: number
+        unit: ms
+        exclusiveMinimum: 0
 DigitizedHeadPoints:
   name: DigitizedHeadPoints
   display_name: Digitized Head Points
@@ -3918,6 +3968,24 @@ SliceTiming:
     type: number
     minimum: 0
     unit: s
+SmallDelta:
+  name: SmallDelta
+  display_name: Diffusion Small Delta (δ)
+  description: |
+    In the context of a diffusion-weighted pulsed gradient spin echo sequence,
+    corresponds to the duration of a diffusion-encoding gradient pulse (δ),
+    specified in seconds.
+    The value may be an array, if δ varies by volume, in which case the number
+    of values MUST correspond to the number of volumes in the data file.
+  anyOf:
+    - type: number
+      unit: s
+      exclusiveMinimum: 0
+    - type: array
+      items:
+        type: number
+        unit: s
+        exclusiveMinimum: 0
 SoftwareFilters:
   name: SoftwareFilters
   display_name: Software Filters

src/schema/rules/checks/mri.yaml

@@ -145,3 +145,31 @@ RepetitionTimePreparationNotConsistent:
     - type(nifti_header) != "null"
   checks:
     - length(sidecar.RepetitionTimePreparation) == nifti_header.dim[4]
+
+BigDeltaNotConsistent:
+  issue:
+    code: BIGDELTA_NOT_CONSISTENT
+    message: |
+      The number of values for 'BigDelta' for this file does
+      not match the 4th dimension of the NIfTI header.
+    level: error
+  selectors:
+    - suffix == "dwi"
+    - type(sidecar.BigDelta) == "array"
+    - type(nifti_header) != "null"
+  checks:
+    - length(sidecar.BigDelta) == nifti_header.dim[4]
+
+SmallDeltaNotConsistent:
+  issue:
+    code: SMALLDELTA_NOT_CONSISTENT
+    message: |
+      The number of values for 'SmallDelta' for this file does
+      not match the 4th dimension of the NIfTI header.
+    level: error
+  selectors:
+    - suffix == "dwi"
+    - type(sidecar.SmallDelta) == "array"
+    - type(nifti_header) != "null"
+  checks:
+    - length(sidecar.SmallDelta) == nifti_header.dim[4]

src/schema/rules/sidecars/dwi.yaml

@@ -16,5 +16,7 @@ MRIDiffusionOtherMetadata:
     - suffix == "dwi"
     - match(extension, "^\.nii(\.gz)?$")
   fields:
+    BigDelta: optional
+    SmallDelta: optional
     PhaseEncodingDirection: recommended
     TotalReadoutTime: recommended