From 535a9da1a41d76099b9a8bd3494acbe3c82f7e2f Mon Sep 17 00:00:00 2001
From: Matt Cieslak <mattcieslak@gmail.com>
Date: Sun, 20 Oct 2019 10:51:14 -0400
Subject: [PATCH 01/12] add dwi tsv file

---
 .../01-magnetic-resonance-imaging-data.md     | 20 ++++++++++++++++++-
 src/schema/datatypes/dwi.yaml                 |  1 +
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 3eb1f3eb75..0646fbb9bd 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -568,6 +568,22 @@ Example of `[*_]dwi.bval` file, corresponding to the previous `[*_]dwi.bvec` exa
 0 0 2000 2000 1000 1000
 ```
 
+Optionally, a `sub-01_acq-multiband_gradient.tsv` file
+can be provided that specifies gradient directions in RAS+ scanner coordinates.
+
+Optional `dwi.tsv` example:
+
+```Text
+R	A	S	B
+0	0	0	0
+1.0	0	0	1000
+-0.0509541      0.0617551       -0.99679        1000
+```
+
+`[*_]dwi.tsv` files can be saved on any level of the directory structure
+and thus define those values for all sessions and/or subjects in one place (see
+Inheritance principle).
+
 ### Multipart (split) DWI schemes
 
 Some MR schemes cannot be acquired directly by some scanner devices,
@@ -656,7 +672,9 @@ JSON example:
 ```JSON
 {
   "PhaseEncodingDirection": "j-",
-  "TotalReadoutTime": 0.095
+  "TotalReadoutTime": 0.095,
+  "BigDelta": 0.005,
+  "SmallDelta": 0.0005
 }
 ```
 
diff --git a/src/schema/datatypes/dwi.yaml b/src/schema/datatypes/dwi.yaml
index 561ca1a5a2..21294a54f8 100644
--- a/src/schema/datatypes/dwi.yaml
+++ b/src/schema/datatypes/dwi.yaml
@@ -6,6 +6,7 @@
     - .nii.gz
     - .nii
     - .json
+    - .tsv
     - .bvec
     - .bval
   entities:

From 364b2528e92edcf55c1a399262cc17e88afe1845 Mon Sep 17 00:00:00 2001
From: Matt Cieslak <mattcieslak@gmail.com>
Date: Sun, 20 Oct 2019 21:16:46 -0400
Subject: [PATCH 02/12] Add BigDelta, SmallDelta descriptions

---
 .remarkrc                                                | 2 +-
 .../01-magnetic-resonance-imaging-data.md                | 9 +++++++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/.remarkrc b/.remarkrc
index f0938a7bca..1cc5dbe8b5 100644
--- a/.remarkrc
+++ b/.remarkrc
@@ -1,6 +1,6 @@
 {
   "plugins": [
-    "preset-lint-markdown-style-guide",
+    "remark-preset-lint-markdown-style-guide",
     ["lint-no-duplicate-headings", false],
     ["lint-list-item-indent", "tab-size"],
     ["lint-emphasis-marker", "consistent"],
diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 0646fbb9bd..ad034dc31d 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -661,12 +661,21 @@ 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
+
+| 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.     |
+| BiglDelta      | 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

From 0fd7340972374d1c098637098c09710ee0373a78 Mon Sep 17 00:00:00 2001
From: Matt Cieslak <mattcieslak@gmail.com>
Date: Tue, 22 Oct 2019 17:34:49 -0400
Subject: [PATCH 03/12] Update
 src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Co-Authored-By: Oscar Esteban <code@oscaresteban.es>
---
 .../01-magnetic-resonance-imaging-data.md                       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index ad034dc31d..9cd7c440ea 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -674,7 +674,7 @@ additional terms that can be included 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.     |
-| BiglDelta      | 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. |
+| 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:
 

From 24278e8237547112f355bea5ca8bb36765918487 Mon Sep 17 00:00:00 2001
From: Matt Cieslak <mattcieslak@gmail.com>
Date: Wed, 23 Oct 2019 14:21:01 -0400
Subject: [PATCH 04/12] Revert to previous linter

---
 .remarkrc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.remarkrc b/.remarkrc
index 1cc5dbe8b5..f0938a7bca 100644
--- a/.remarkrc
+++ b/.remarkrc
@@ -1,6 +1,6 @@
 {
   "plugins": [
-    "remark-preset-lint-markdown-style-guide",
+    "preset-lint-markdown-style-guide",
     ["lint-no-duplicate-headings", false],
     ["lint-list-item-indent", "tab-size"],
     ["lint-emphasis-marker", "consistent"],

From 524e7765d717c7bfb29ab363954ff416d07c86eb Mon Sep 17 00:00:00 2001
From: Matt Cieslak <mattcieslak@gmail.com>
Date: Tue, 29 Oct 2019 14:49:49 -0400
Subject: [PATCH 05/12] Describe RASB and deprecation plans

---
 .../01-magnetic-resonance-imaging-data.md     | 34 +++++++++++++------
 1 file changed, 23 insertions(+), 11 deletions(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 9cd7c440ea..e4a4d9ad71 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -522,19 +522,26 @@ 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
+### REQUIRED gradient strength and orientation information
 
-The REQUIRED gradient orientation information corresponding to a DWI acquisition
+The REQUIRED gradient strength and 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
+In addition, it is RECOMMENDED to store the gradient orientation in a `[*_]dwi.tsv` file,
+in the *RASB+* format described below.
+The `[*_]dwi.[bval|bvec]` files are DEPRECATED and will be
+phased out in a future release.
+The *RASB+* 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 orientation file formats**.
+**BVEC/BVAL specification**.
 The `[*_]dwi.bval` and `[*_]dwi.bvec` files MUST follow the
 [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
@@ -568,8 +575,17 @@ Example of `[*_]dwi.bval` file, corresponding to the previous `[*_]dwi.bvec` exa
 0 0 2000 2000 1000 1000
 ```
 
-Optionally, a `sub-01_acq-multiband_gradient.tsv` file
-can be provided that specifies gradient directions in RAS+ scanner coordinates.
+**RASB+ format for gradient strength and orientation**.
+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 the columns `R A S B`, where `R`, `A` and `S` contain a unit vector
+describing the gradient direction in scanner coordinates.
+The `B` column contains the *b*-value in (in s/mm<sup>2</sup>).
+Although the *b*-value is a common way to convey gradient
+strength, it does not unambiguously depict the sampled coordinate in *q*-space.
+The relationship between each row of this TSV file and its corresponding *q*-space coordinate
+can be calculated with the `BigDelta` and `SmallDelta` metadata fields in the corresponding
+JSON file.
 
 Optional `dwi.tsv` example:
 
@@ -580,10 +596,6 @@ R	A	S	B
 -0.0509541      0.0617551       -0.99679        1000
 ```
 
-`[*_]dwi.tsv` files can be saved on any level of the directory structure
-and thus define those values for all sessions and/or subjects in one place (see
-Inheritance principle).
-
 ### Multipart (split) DWI schemes
 
 Some MR schemes cannot be acquired directly by some scanner devices,

From 3e6964cdb04b356317035759abb3955b9d6b8ea4 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Wed, 21 Apr 2021 09:51:44 +0200
Subject: [PATCH 06/12] enh: more liberal specification of TSV files

---
 .../01-magnetic-resonance-imaging-data.md     | 88 ++++++++++++-------
 1 file changed, 58 insertions(+), 30 deletions(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index e4a4d9ad71..38c1d79cbc 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -524,13 +524,16 @@ The user is free to choose any other label than `singleband` and
 
 ### REQUIRED gradient strength and orientation information
 
-The REQUIRED gradient strength and orientation information corresponding to a DWI acquisition
-MUST be stored using `[*_]dwi.bval` and `[*_]dwi.bvec` pairs of files.
-In addition, it is RECOMMENDED to store the gradient orientation in a `[*_]dwi.tsv` file,
-in the *RASB+* format described below.
-The `[*_]dwi.[bval|bvec]` files are DEPRECATED and will be
+The gradient strength and orientation information corresponding to a DWI acquisition
+is REQUIRED, and therefore, MUST be stored in the structure.
+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 *RASB+* file format is OPTIONAL and will replace `[*_]dwi.[bval|bvec]` as the
+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
@@ -541,7 +544,47 @@ As an exception to the [common principles](../02-common-principles.md#definition
 that parameters are constant across runs, the gradient table information (stored
 within `[*_]dwi.[bval|bvec|tsv]` files) MAY change across DWI runs.
 
-**BVEC/BVAL specification**.
+**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 corresponding to 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
+```
+
+**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):
 The `[*_]dwi.bvec` file contains 3 rows with *N* space-delimited floating-point numbers
@@ -555,8 +598,8 @@ Following the FSL format for the `[*_]dwi.bvec` specification, the coordinate sy
 the *b* vectors MUST be defined with respect to the coordinate system defined by
 the header of the corresponding `_dwi` NIfTI file and not the scanner's device
 coordinate system (see [Coordinate systems](../99-appendices/08-coordinate-systems.md)).
-The most relevant implication for this choice is that any rotations applied to the DWI data
-also need to be applied to the *b* vectors in the `[*_]dwi.bvec` file.
+The most relevant limitation imposed by this choice is that the gradient information cannot
+be directly stored in this format if the scanner generates *b*-vectors in *scanner coordinates*.
 
 Example of `[*_]dwi.bvec` file, with *N*=6, with two *b*=0 volumes in the beginning:
 
@@ -575,27 +618,6 @@ Example of `[*_]dwi.bval` file, corresponding to the previous `[*_]dwi.bvec` exa
 0 0 2000 2000 1000 1000
 ```
 
-**RASB+ format for gradient strength and orientation**.
-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 the columns `R A S B`, where `R`, `A` and `S` contain a unit vector
-describing the gradient direction in scanner coordinates.
-The `B` column contains the *b*-value in (in s/mm<sup>2</sup>).
-Although the *b*-value is a common way to convey gradient
-strength, it does not unambiguously depict the sampled coordinate in *q*-space.
-The relationship between each row of this TSV file and its corresponding *q*-space coordinate
-can be calculated with the `BigDelta` and `SmallDelta` metadata fields in the corresponding
-JSON file.
-
-Optional `dwi.tsv` example:
-
-```Text
-R	A	S	B
-0	0	0	0
-1.0	0	0	1000
--0.0509541      0.0617551       -0.99679        1000
-```
-
 ### Multipart (split) DWI schemes
 
 Some MR schemes cannot be acquired directly by some scanner devices,
@@ -683,6 +705,12 @@ 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.     |

From 3fa1740b139ea59bcb54ec20834bf8f4f4539075 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Wed, 21 Apr 2021 14:23:55 +0200
Subject: [PATCH 07/12] fix: roll comment on bvecs back to original

---
 .../01-magnetic-resonance-imaging-data.md                     | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 38c1d79cbc..3cc6142cd3 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -598,8 +598,8 @@ Following the FSL format for the `[*_]dwi.bvec` specification, the coordinate sy
 the *b* vectors MUST be defined with respect to the coordinate system defined by
 the header of the corresponding `_dwi` NIfTI file and not the scanner's device
 coordinate system (see [Coordinate systems](../99-appendices/08-coordinate-systems.md)).
-The most relevant limitation imposed by this choice is that the gradient information cannot
-be directly stored in this format if the scanner generates *b*-vectors in *scanner coordinates*.
+The most relevant implication for this choice is that any rotations applied to the DWI data
+also need to be applied to the *b* vectors in the `[*_]dwi.bvec` file.
 
 Example of `[*_]dwi.bvec` file, with *N*=6, with two *b*=0 volumes in the beginning:
 

From fa194f951fe15c43148e38d084095cf64eba8bf5 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Fri, 23 Apr 2021 08:44:11 +0200
Subject: [PATCH 08/12] fix: bad link, update outdated bval/bvec info

---
 .../01-magnetic-resonance-imaging-data.md                      | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 3d15bd4cce..5da35c0186 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -511,9 +511,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.

From 9ee13ffad57a7e48f59c59165373162034cdd509 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Fri, 23 Apr 2021 09:07:41 +0200
Subject: [PATCH 09/12] fix: minimal wording and punctuation changes

---
 .../01-magnetic-resonance-imaging-data.md                 | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 5da35c0186..d17dc3cbd1 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -555,7 +555,7 @@ In other words, the number of rows in the TSV file and the size of the last dime
 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 corresponding to a nonzero gradient strength
+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
@@ -571,6 +571,7 @@ 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`).
 
@@ -583,9 +584,10 @@ R	A	S	b
 -0.0509541	0.0617551	-0.99679	1000
 ```
 
-**Legacy `.bvec` \& `.bval` specification of gradient information**.
+**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

From 487032cb6e54c7821001e64e166ac80667a079c9 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Fri, 23 Apr 2021 09:39:05 +0200
Subject: [PATCH 10/12] enh: add comment regarding 'effective' vs. 'requested'
 gradients

---
 .../01-magnetic-resonance-imaging-data.md                    | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index d17dc3cbd1..925c8f25a8 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -525,6 +525,11 @@ The user is free to choose any other label than `singleband` and
 
 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.

From 6c73743815b596dbe8d5c129829b83ac1463d4f6 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Wed, 28 Apr 2021 18:13:43 +0200
Subject: [PATCH 11/12] enh: refine text and provisions for deprecation
 addressing @satra's concerns

---
 .../01-magnetic-resonance-imaging-data.md     | 49 +++++++++++++------
 1 file changed, 34 insertions(+), 15 deletions(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 6f6df4a548..6ebc159841 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -544,21 +544,24 @@ The user is free to choose any other label than `singleband` and
 ### 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
+is REQUIRED, and therefore, MUST be stored in the structure using the formats introduced
+below.
+The gradient strength and orientation information 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
+The gradient information MAY be stored using the OPTIONAL `.bval` and `.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 format of the `.tsv` file and the `.bvec`/`.bval` files, as well as the conversion from
+`.bvec`/`.bval` to `.tsv`, are described below.
+
+The RECOMMENDED `.tsv` file and the OPTIONAL `.bval`/`.bvec` MAY coexist in the structure.
+In such a case, the `.tsv` file and the `.bval`/`.bvec` pair MUST be consistent as described
+below.
+However, the `.bval`/`.bvec` files are DEPRECATED and will be phased out in a future release.
 
 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
@@ -600,7 +603,7 @@ 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:
+Example of TSV file, following the *RAS+b* convention:
 
 ```Text
 R	A	S	b
@@ -610,24 +613,24 @@ R	A	S	b
 ```
 
 **Legacy `.bvec` & `.bval` specification of gradient information**.
-The `[*_]dwi.bval` and `[*_]dwi.bvec` files MUST follow the
+The `.bvec`/`.bval` files MUST follow the
 [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
+The `.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
 the third row contains the *z* elements of a unit vector in the direction of the applied
 diffusion gradient, where the *i*-th elements in each row correspond together to
 the *i*-th volume, with `[0,0,0]` for *non-diffusion-weighted* (also called *b*=0 or *low-b*)
 volumes.
-Following the FSL format for the `[*_]dwi.bvec` specification, the coordinate system of
+Following the FSL format for the `.bvec` specification, the coordinate system of
 the *b* vectors MUST be defined with respect to the coordinate system defined by
 the header of the corresponding `_dwi` NIfTI file and not the scanner's device
 coordinate system (see [Coordinate systems](../99-appendices/08-coordinate-systems.md)).
 The most relevant implication for this choice is that any rotations applied to the DWI data
 also need to be applied to the *b* vectors in the `[*_]dwi.bvec` file.
 
-Example of `[*_]dwi.bvec` file, with *N*=6, with two *b*=0 volumes in the beginning:
+Example of `.bvec` file, with *N*=6, with two *b*=0 volumes in the beginning:
 
 ```Text
 0 0 0.021828 -0.015425 -0.70918 -0.2465
@@ -635,15 +638,31 @@ Example of `[*_]dwi.bvec` file, with *N*=6, with two *b*=0 volumes in the beginn
 0 0 -0.59636 0.97516 -0.70503 -0.96351
 ```
 
-The `[*_]dwi.bval` file contains the *b*-values (in s/mm<sup>2</sup>) corresponding to the
+The `.bval` file contains the *b*-values (in s/mm<sup>2</sup>) corresponding to the
 volumes in the relevant NIfTI file), with 0 designating *b*=0 volumes, space-delimited.
 
-Example of `[*_]dwi.bval` file, corresponding to the previous `[*_]dwi.bvec` example:
+Example of `.bval` file, corresponding to the previous `.bvec` example:
 
 ```Text
 0 0 2000 2000 1000 1000
 ```
 
+**Conversion from the legacy `.bvec` & `.bval` format into gradient table (`.tsv`)**.
+To convert from the legacy format into table format, the values of the `.bvec` file
+are transposed, the values of the `.bval` file are contatenated as the fourth column
+and the `I J K b` header is inserted.
+The conversion corresponding to the `.bvec`/`.bval` example above is:
+
+```Text
+I	J	K	b
+0	0	0	0
+0	0	0	0
+0.021828	0.80242	-0.59636	2000
+-0.015425	0.22098	0.97516	2000
+-0.70918	-0.00063106	-0.70503	1000
+-0.2465	0.1043	-0.96351	1000
+```
+
 ### Multipart (split) DWI schemes
 
 Some MR schemes cannot be acquired directly by some scanner devices,

From dea99be8a42623402bf930f736f23df9b472a545 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 29 Apr 2021 17:13:31 +0200
Subject: [PATCH 12/12] fix: update FSL specification of the bvecs/bvals with
 @satra's link

---
 .../01-magnetic-resonance-imaging-data.md                       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 6ebc159841..f4de5aba89 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -614,7 +614,7 @@ R	A	S	b
 
 **Legacy `.bvec` & `.bval` specification of gradient information**.
 The `.bvec`/`.bval` 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/FAQ#What_conventions_do_the_bvecs_use.3F).
 
 The `.bvec` file contains 3 rows with *N* space-delimited floating-point numbers
 (corresponding to the *N* volumes in the corresponding NIfTI file.)