[ENH] Use TSV for DWI gradients, and allow both voxel- and world- coordinates conventions

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

@@ -531,9 +531,8 @@ distinguish different sets of phase-encoding directions.
 **Combining multi- and single-band acquisitions**.
 The single-band reference image MAY be stored with suffix `sbref` (for example,
 `dwi/sub-control01_sbref.nii[.gz]`) as long as the image has no corresponding
-[gradient information (`[*_]dwi.bval` and `[*_]dwi.bvec` sidecar files)](#required-gradient-orientation-information)
+[gradient information](#required-gradient-strength-and-orientation-information)
 to be stored.
-
 Otherwise, if some gradient information is associated to the single-band diffusion
 image and a multi-band diffusion image also exists, the `acq-<label>` key/value pair
 MUST be used to distinguish both images.
@@ -542,21 +541,78 @@ In such a case, two files could have the following names:
 The user is free to choose any other label than `singleband` and
 `multiband`, as long as they are consistent across subjects and sessions.
 
-### REQUIRED gradient orientation information
-
-The REQUIRED gradient orientation information corresponding to a DWI acquisition
-MUST be stored using `[*_]dwi.bval` and `[*_]dwi.bvec` pairs of files.
-The `[*_]dwi.bval` and `[*_]dwi.bvec` files MAY be saved on any level of the directory structure
+### REQUIRED gradient strength and orientation information
+
+The gradient strength and orientation information corresponding to a DWI acquisition
+is REQUIRED, and therefore, MUST be stored in the structure.
+The gradient strength and orientation information stored in the structure MUST correspond
+to "*effective*" values (as in, the actual orientations and strengths applied by the scanner),
+rather than the "*requested*" values (as in, the original gradient table design that is
+configured into the scanner's MR protocol settings).
+
+The RECOMMENDED way to store gradient information is a `[*_]dwi.tsv` file corresponding
+to one or more DWI files.
+The format of this TSV file, and associated metadata, are described below.
+The gradient information MAY be stored using the `[*_]dwi.bval` and `[*_]dwi.bvec` pair
+of files.
+However, the `[*_]dwi.[bval|bvec]` files are DEPRECATED and will be
+phased out in a future release.
+The TSV file format is OPTIONAL, and will replace `[*_]dwi.[bval|bvec]` as the
+default method for representing gradients.
+
+The `[*_]dwi.[bval|bvec|tsv]` files MAY be saved 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](../02-common-principles.md#the-inheritance-principle)).
 
 As an exception to the [common principles](../02-common-principles.md#definitions)
 that parameters are constant across runs, the gradient table information (stored
-within the `[*_]dwi.bval` and `[*_]dwi.bvec` files) MAY change across DWI runs.
+within `[*_]dwi.[bval|bvec|tsv]` files) MAY change across DWI runs.
+
+**Gradient table specification (`_dwi.tsv` file)**.
+Gradient strength and orientation can be provided in a TSV file named, for example,
+`sub-01_acq-singleband_dwi.tsv` or `sub-01_acq-multiband_dwi.tsv`.
+This TSV file must contain four columns, where the first three columns correspond to the
+three components of a unit-norm vector determining one gradient orientation (also called "*b*-vector")
+and the last column contains the gradient strength ("*b*-value") in s/mm<sup>2</sup>.
+Each row of the TSV file corresponds to one sampled DWI, and therefore, the number of rows
+MUST match the number of volumes in the corresponding DWI file(s).
+In other words, the number of rows in the TSV file and the size of the last dimension of the
+data array in the corresponding DWI file(s) MUST be the same.
+
+Rows corresponding to *b = 0* s/mm<sup>2</sup> strengths MUST contain four zeros.
+Correspondingly, the components of the *b*-vector associated with a nonzero gradient strength
+(*b* &#62; 0) MUST represent a unit-norm vector.
+
+Scanner devices may store the *b*-vectors with reference to the acquired voxel or the
+scanner coordinate system (see [Coordinate systems](../99-appendices/08-coordinate-systems.md)).
+The coordinate system specification is REQUIRED, and MUST be encoded by the column headers
+of the TSV file.
+Therefore, if the *b*-vectors in the gradient table are given in *voxel coordinates*,
+the column headers MUST be `I`, `J`, `K`, `b`.
+We will refer to this format as *IJK+b* in the following.
+Alternatively, if the *b*-vectors in the gradient table are given in *scanner coordinates*,
+the column headers MUST be `R`, `A`, `S`, `b`.
+We will refer to this format as *RAS+b* in the following.
+
+It is RECOMMENDED to store the gradient table information in the original coordinate system
+stored by the scanner (therefore, unchanged).
+
+It is RECOMMENDED to maintain the column ordering as described above (thus, either `I J K b`
+or `R A S b`).
+
+Example of `_dwi.tsv` file, following the *RAS+b* convention:
+
+```Text
+R	A	S	b
+0	0	0	0
+1.0	0	0	1000
+-0.0509541	0.0617551	-0.99679	1000
+```
 
-**Gradient orientation file formats**.
+**Legacy `.bvec` & `.bval` specification of gradient information**.
 The `[*_]dwi.bval` and `[*_]dwi.bvec` files MUST follow the
-[FSL format](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT/UserGuide#DTIFIT):
+[FSL format](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT/UserGuide#DTIFIT).
+
 The `[*_]dwi.bvec` file contains 3 rows with *N* space-delimited floating-point numbers
 (corresponding to the *N* volumes in the corresponding NIfTI file.)
 The first row contains the *x* elements, the second row contains the *y* elements and
@@ -665,19 +721,36 @@ sub-<label>/[ses-<label>/]             # MultipartID
 
 ### Other RECOMMENDED metadata
 
+#### Phase-encoding information (common metadata fields)
+
 The `PhaseEncodingDirection` and `TotalReadoutTime` metadata
 fields are RECOMMENDED to enable the correction of geometrical distortions
 with [fieldmap information](#fieldmap-data).
 See [Common metadata fields](#common-metadata-fields) for a list of
 additional terms that can be included in the corresponding JSON file.
 
+#### Pulse gradient timing information
+
+Although the *b*-value is the most common way to convey gradient strength, it does not
+unambiguously depict the sampled coordinate in *q*-space.
+The relationship between each *b*-vector and its corresponding *q*-space coordinate
+can be calculated with the `BigDelta` and `SmallDelta` metadata fields in the corresponding
+JSON file.
+
+| Field name     | Definition                                                                                                                                                                                                                                                                |
+| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| SmallDelta     | RECOMMENDED. Acquisition pulse separation time (in seconds). For Siemens, this is in the shadow header (0029,1120) under `sSpecPara.dSpecLipidSupprBandwidth` in milliseconds. This value is necessary for estimating ensemble average propagators in physical units.     |
+| BigDelta       | RECOMMENDED. Acquisition pulse separation time (in seconds). For Siemens, this is in the shadow header (0029,1120) under `sSpecPara.dSpecLipidSupprDeltaPos` in milliseconds. This value is also necessary for estimating ensemble average propagators in physical units. |
+
 JSON example:
 
 ```JSON
 {
   "PhaseEncodingDirection": "j-",
   "TotalReadoutTime": 0.095,
-  "B0FieldSource": ["phasediff_fmap0", "pepolar_fmap0"]
+  "B0FieldSource": ["phasediff_fmap0", "pepolar_fmap0"],
+  "BigDelta": 0.005,
+  "SmallDelta": 0.0005
 }
 ```
 

src/schema/datatypes/dwi.yaml

@@ -6,6 +6,7 @@
     - .nii.gz
     - .nii
     - .json
+    - .tsv
     - .bvec
     - .bval
   entities: