Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 15 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 109 additions & 17 deletions src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -542,52 +541,128 @@ 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 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 gradient information MAY be stored using the OPTIONAL `.bval` and `.bvec` pair
of files.
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
[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 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 `.bvec`/`.bval` files MUST follow the
[FSL format](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT/FAQ#What_conventions_do_the_bvecs_use.3F).

**Gradient orientation file formats**.
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
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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The directions in the bvec aren't always using the image axis coordinate system. @frankyeh recently updated DSI Studio to handle the case where the image axes aren't in the FSL "RPI" orientation but the bvecs are. FSL interprets bvecs differently depending on the orientation of the image axis.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, I didn't know that. I think this just reinforces the argument that this PR is necessary. How the (recently added) conversion example would change with this? Should we mention the image axis coordinate system so that what is said is fully accurate?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The conversion example will only work if the image is in LAS+ orientation. This will be true by default if dcm2niix was used, but is not guaranteed.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

here is the actualFSL spec: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT/FAQ#What_conventions_do_the_bvecs_use.3F (it should be included in that section)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
0 0 0.80242 0.22098 -0.00063106 0.1043
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,
Expand Down Expand Up @@ -665,19 +740,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
oesteban marked this conversation as resolved.
Show resolved Hide resolved
Comment on lines +771 to +772
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Given that these appear in a general sidecar metadata space rather than a DWI-specific context, the names "BigDelta" and "SmallDelta" may not be specific enough.

  • If revisiting, it would be worth considering whether it is worthwhile adding these, or instead deferring more advanced diffusion encoding information entirely to the aDWI extension.

}
```

Expand Down
1 change: 1 addition & 0 deletions src/schema/datatypes/dwi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
- .nii.gz
- .nii
- .json
- .tsv
- .bvec
- .bval
entities:
Expand Down