[ENH] Add "multipart DWI" acquisitions and refactor DWI specifications #624
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -57,7 +57,7 @@ that a given scan was collected with the intended coil elements selected | |
| | **Key name** | **Requirement level** | **Data type** | **Description** | | ||
| |--------------------------------|-----------------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | NumberShots | RECOMMENDED | [number][] | The number of RF excitations need to reconstruct a slice or volume. Please mind that this is not the same as Echo Train Length which denotes the number of lines of k-space collected after an excitation. | | ||
| | ParallelReductionFactorInPlane | RECOMMENDED | [number][] | The parallel imaging (for instance, GRAPPA) factor. Use the denominator of the fraction of k-space encoded for each slice. For example, 2 means half of k-space is encoded. Corresponds to DICOM Tag 0018, 9069 `Parallel Reduction Factor In-plane`. | | ||
| | ParallelAcquisitionTechnique | RECOMMENDED | [string][] | The type of parallel imaging used (for example GRAPPA, SENSE). Corresponds to DICOM Tag 0018, 9078 `Parallel Acquisition Technique`. | | ||
| | PartialFourier | RECOMMENDED | [number][] | The fraction of partial Fourier information collected. Corresponds to DICOM Tag 0018, 9081 `Partial Fourier`. | | ||
| | PartialFourierDirection | RECOMMENDED | [string][] | The direction where only partial Fourier information was collected. Corresponds to DICOM Tag 0018, 9036 `Partial Fourier Direction`. | | ||
|
|
@@ -376,6 +376,14 @@ participant, task and run takes precedence. | |
|
|
||
| ## Diffusion imaging data | ||
|
|
||
| Diffusion-weighted imaging data acquired for a participant. | ||
| Currently supported image types include: | ||
|
|
||
| | **Name** | `suffix` | **Description** | | ||
| |---------------------- | -------- | ----------------------------------------------------------------- | | ||
| | DWI | dwi | Diffusion-weighted imaging contrast (specialized T2\* weighting). | | ||
| | Single-Band Reference | sbref | Single-band reference for one or more multi-band `dwi` images. | | ||
|
|
||
| Template: | ||
|
|
||
| ```Text | ||
|
|
@@ -389,52 +397,162 @@ sub-<label>/[ses-<label>/] | |
| sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>]_sbref.json | ||
| ``` | ||
|
|
||
| If more than one run of the same acquisition and direction has been acquired, the | ||
| [`run-<index>`](../99-appendices/09-entities.md#run) key/value pair MUST be used: | ||
| `_run-1`, `_run-2`, `_run-3` (and so forth.) | ||
| When there is only one scan of a given acquisition and direction, the run key MAY be | ||
| omitted. | ||
| The [`run-<index>`](../99-appendices/09-entities.md#run) key/value pair is RECOMMENDED | ||
| to encode the splits of multipart DWI scans (see [below](#multipart-split-dwi-schemes).) | ||
|
|
||
| The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq) | ||
| key/value pair corresponds to a custom label the user may use to | ||
| distinguish different sets of parameters. | ||
|
|
||
| The OPTIONAL [`dir-<label>`](../99-appendices/09-entities.md#dir) | ||
| key/value pair corresponds to a custom label the user may use to | ||
| 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) | ||
| 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. | ||
| In such a case, two files could have the following names: | ||
| `sub-01_acq-singleband_dwi.nii.gz` and `sub-01_acq-multiband_dwi.nii.gz`. | ||
| The user is free to choose any other label than `singleband` and | ||
| `multiband`, as long as they are consistent across subjects and sessions. | ||
|
There was a problem hiding this comment. How will the pipelines know that the sbref is intended to be used as the anatomical reference for the multiband sequence? Does this go in the sidecar? There was a problem hiding this comment. This particular is out of the scope of the refactor - let's take this one to the finish line and then see if extending the |
||
|
|
||
| ### 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 | ||
| 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. | ||
|
|
||
| **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 | ||
| (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 | ||
oesteban marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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: | ||
|
|
||
| ```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 | ||
| volumes in the relevant NIfTI file), with 0 designating *b*=0 volumes, space-delimited. | ||
|
There was a problem hiding this comment. depending on the scanner and sequence some of the BVALs might have very small values in locations where 0 is expected (Siemens sometimes adds 5, 10, 15 as an example). Similarly, values for non-zero BVALs can be not-rounded off say 990 or 995 instead of 1,000 or 2020, 2010 or 1995 instead of 2000. I think this is fine for 80% of the situations but it might require changes in the future. There was a problem hiding this comment. I think @mattcieslak initiated the right place for this conversation with #352. For a cleaner diff that assumes this PR has been already merged, please use oesteban/bids-specification@enh/dwi-combinations...mattcieslak:dwi_tsv |
||
|
|
||
| Example of `[*_]dwi.bval` file, corresponding to the previous `[*_]dwi.bvec` example: | ||
|
|
||
| ```Text | ||
| 0 0 2000 2000 1000 1000 | ||
| ``` | ||
|
|
||
| ### Multipart (split) DWI schemes | ||
|
|
||
| Some MR schemes cannot be acquired directly by some scanner devices, | ||
| requiring to generate several DWI runs that were originally meant to belong | ||
| in a single one. | ||
oesteban marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| For instance, some GE scanners cannot collect more than ≈160 volumes | ||
| in a single run under fast-changing gradients, so acquiring *HCP-style* | ||
| diffusion images will require splitting the DWI scheme in several runs. | ||
| Because researchers will generally optimize the data splits, these will likely | ||
| not be able to be directly concatenated. | ||
| BIDS permits defining arbitrary groupings of these multipart scans with the | ||
| following metadata: | ||
|
|
||
| | **Key name** | **Requirement level** | **Data type** | **Description** | | ||
| | --------------- | --------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | MultipartID | REQUIRED | [string][] | A unique (per participant) label tagging DWI runs that are part of a multipart scan. | | ||
|
|
||
| JSON example: | ||
|
|
||
| ```JSON | ||
| { | ||
| "MultipartID": "dwi_1" | ||
| } | ||
| ``` | ||
|
|
||
| For instance, if there are two phase-encoding directions (`AP`, `PA`), and | ||
| two runs each, and the intent of the researcher is that all of them are | ||
| part of a unique multipart scan, then they will tag all four runs with the | ||
| same `MultipartID` (shown at the right-hand side of the file listing): | ||
|
|
||
| ```Text | ||
| sub-<label>/[ses-<label>/] # MultipartID | ||
| dwi/ | ||
| sub-1_dir-AP_run-1_dwi.nii.gz # dwi_1 | ||
| sub-1_dir-AP_run-2_dwi.nii.gz # dwi_1 | ||
| sub-1_dir-PA_run-1_dwi.nii.gz # dwi_1 | ||
| sub-1_dir-PA_run-2_dwi.nii.gz # dwi_1 | ||
| ``` | ||
|
|
||
| If, conversely, the researcher wanted to store two multipart scans, one possibility | ||
| is to combine matching phase-encoding directions: | ||
|
|
||
| ```Text | ||
| sub-<label>/[ses-<label>/] # MultipartID | ||
| dwi/ | ||
| sub-1_dir-AP_run-1_dwi.nii.gz # dwi_1 | ||
| sub-1_dir-AP_run-2_dwi.nii.gz # dwi_1 | ||
| sub-1_dir-PA_run-1_dwi.nii.gz # dwi_2 | ||
| sub-1_dir-PA_run-2_dwi.nii.gz # dwi_2 | ||
| ``` | ||
|
|
||
| Alternatively, the researcher's intent could be combining opposed phase-encoding | ||
| runs instead: | ||
|
|
||
| ```Text | ||
| sub-<label>/[ses-<label>/] # MultipartID | ||
| dwi/ | ||
| sub-1_dir-AP_run-1_dwi.nii.gz # dwi_1 | ||
| sub-1_dir-AP_run-2_dwi.nii.gz # dwi_2 | ||
| sub-1_dir-PA_run-1_dwi.nii.gz # dwi_1 | ||
| sub-1_dir-PA_run-2_dwi.nii.gz # dwi_2 | ||
| ``` | ||
|
|
||
| The `MultipartID` metadata MAY be used with the | ||
| [`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair, for example: | ||
|
|
||
| ```Text | ||
| sub-<label>/[ses-<label>/] # MultipartID | ||
| dwi/ | ||
| sub-1_acq-shell1_run-1_dwi.nii.gz # dwi_1 | ||
| sub-1_acq-shell1_run-2_dwi.nii.gz # dwi_2 | ||
| sub-1_acq-shell2_run-1_dwi.nii.gz # dwi_1 | ||
| sub-1_acq-shell2_run-2_dwi.nii.gz # dwi_2 | ||
| ``` | ||
|
|
||
| ### Other RECOMMENDED metadata | ||
|
|
||
| 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. | ||
|
|
||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm assuming so, but just to confirm, does this match current practice? This seems to be a new explicit requirement, although I see that there's never been
_sbref.bval.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If you see a
_sbref.bvalfile then it should be filled with zeros. There could be a use case for nonzero (but very low b-vals << 1000) but why don't use_dwiwhich is more appropriate?This does match current practice, and as you were pointing, it was implicit in the spec. I just made it explicit, if that makes sense.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There's one large case, which is siemens scanners can't make a b=0 only series without b > 0 scan included. So the sbref will include a few b=0 images followed by a random b=1000. +1 for optional gradient files for sbrefs
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the BIDS curator has two options in that case:
_dwifile, although there are not enough orientations to fit a diffusion model this is indeed a diffusion-weighted MRI._sbreffile.Allowing
_sbref.bvaladds quite a bit of complexity to PyBIDS and software and irregularity (w.r.t. sbrefs underfunc/), while IMHO misrepresenting the nature of the file.Would you reconsider your +1 to having optional gradient files for sbrefs?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Dropping the b > 0 images would be a processing step, so the sbrefs would no longer be "raw" like the other images. This is actually the same issue that the reverse phase encoding direction images have - the
fmaps/*_epiimages require .bval and .bvec files to be interpreted correctly for distortion correction.These are major BIDS limitations that are prevent dmri workflows from using real BIDS and require users put the extra gradient information files into .bidsignore. I think there is another PR open for this, though. I'd be happy if there was even a sidecar field that has the bvals in it, since the gradient directions are irrelevant fir sbrefs and epi fieldmaps.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Dropping the b > 0 would be the same as people are actually doing with nonsteady states in functional MRI (at some places), for instance. Or if you intendedly leave out of conversion a whole bunch of acquisitions that are otherwise already in the DICOM structure. I'm not saying anyone should do this, but it is an option - this is outside of BIDS purview.
I don't think this is the same issue. If you have diffusion weights (i.e., nonzero b-values) then you are indeed acquiring DWI - and these files should not be under
fmap/regardless of whether you can fit a diffusion model or not. I think BIDS has sufficient specifications to write these files underdwi/as_dwi.niifiles with corresponding gradient info.The problem of estimating a fieldmap using these DWIs is a completely different issue, which is actually addressed in #622.
Finally, accepting
sbref.bvalfiles would probably not be backward compatible (and a big change I would leave for another PR to keep this one with a focused scope).Can you point at some publicly shared dataset?