From 7a10ce1b10489488fe2f3a40244514d1f4ac3119 Mon Sep 17 00:00:00 2001 From: Agah Date: Wed, 13 Jan 2021 14:08:45 -0500 Subject: [PATCH] [ENH] BEP001 - qMRI maps and some additional metadata (#690) * Edit non-param table, add legacy list * Add table for parametric maps * Add description for parametric maps. * Add templates for file collections * Typo, wording for NumberShots * Add spoiling metadata * Update entity schema src * split * Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md Co-authored-by: Taylor Salo * Wording * a.u. --> arbitrary * legacy --> deprecated * mod --> label * ADD explanations about fundamental contrasts * Drop part from qMaps * update entity table * STY: Use .md links, fix table formatting * Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md Co-authored-by: Chris Markiewicz * [ADD] qMRI Appendix * ADD SA2RAGE and qMRI appendix links * Entity and entity tables - Avoid conflict with #692 - Add applicable TB1map file collections * ADD MixingTime & Improve NumberShots * Consistency * Address comment * map units * Super minot textual edits * Some small textual fixes in 10-file-collections * re-render entity table after rebase using python tools/bids_schema.py entities src/schema/ src/99-appendices/04-entity-table.md * fix call to use entitytable, not entities * fix 09-entities using correct schema call * Drop latin phrases * Fix double quotes * Codeblock type fix * Fix article hyperlinks --> DOI * Punctuation fixes * Add section links iof italics * Drop etc. * Rm Latin phrase * add missing newline at end of file * major syntax+linebreak overhaul qmri appendix * remaining qmri appendix syntax issues, except one to be discussed * fix table pipes in 10-file-collections.md * fix ill-formatted links * some more link fixes * one more link * Fix typo * Fix parantheses * Make spoiling-relevant requirements more explicit * Wording suggestion * Add unit for MixingTime * Fix typo * Define R1,R2,R2star and re-arrange rows * Fix double quotes * Fix typo * Wording suggestion * Rm verbosity * Wording fix * Number of shots array/number explanation * Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md Co-authored-by: Chris Markiewicz * Update src/99-appendices/11-qmri.md Co-authored-by: Chris Markiewicz * Update src/99-appendices/11-qmri.md Co-authored-by: Chris Markiewicz * Update src/99-appendices/11-qmri.md Co-authored-by: Chris Markiewicz * Update src/99-appendices/11-qmri.md Co-authored-by: Chris Markiewicz * Update src/99-appendices/11-qmri.md Co-authored-by: Chris Markiewicz * Update src/99-appendices/11-qmri.md Co-authored-by: Chris Markiewicz * Update src/99-appendices/11-qmri.md Co-authored-by: Chris Markiewicz * Update src/99-appendices/11-qmri.md Co-authored-by: Chris Markiewicz * Update src/99-appendices/11-qmri.md Co-authored-by: Chris Markiewicz * Update src/99-appendices/11-qmri.md Co-authored-by: Chris Markiewicz * Update src/99-appendices/11-qmri.md Co-authored-by: Chris Markiewicz * Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md Co-authored-by: Chris Markiewicz * fix links by converting to lowercase * STY: Align table fences * STY: Fix link syntax, one more table fence * Fix typo * Fix paranthesis * STY: Align table fences * Move UNIT1 to non-parametric table * Fix typo * Fix typo * Drop the term grayscale * Align table fence * STY: Align table fences Co-authored-by: Taylor Salo Co-authored-by: Chris Markiewicz Co-authored-by: Chris Markiewicz Co-authored-by: Gilles de Hollander Co-authored-by: Stefan Appelhoff --- mkdocs.yml | 1 + .../01-magnetic-resonance-imaging-data.md | 140 +++-- src/99-appendices/04-entity-table.md | 31 +- src/99-appendices/10-file-collections.md | 57 +- src/99-appendices/11-qmri.md | 558 ++++++++++++++++++ src/schema/datatypes/anat.yaml | 145 ++++- src/schema/datatypes/fmap.yaml | 33 ++ 7 files changed, 880 insertions(+), 85 deletions(-) create mode 100644 src/99-appendices/11-qmri.md diff --git a/mkdocs.yml b/mkdocs.yml index 4fce5fb957..5219216eeb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,6 +50,7 @@ nav: - Coordinate systems: 99-appendices/08-coordinate-systems.md - Entities: 99-appendices/09-entities.md - File collections: 99-appendices/10-file-collections.md + - Quantitative MRI: 99-appendices/11-qmri.md - Changelog: CHANGES.md - The BIDS Starter Kit: - GitHub repository: https://github.com/bids-standard/bids-starter-kit 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 7574f34bad..f876857dd4 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 @@ -43,33 +43,39 @@ that a given scan was collected with the intended coil elements selected ### Sequence Specifics -| **Key name** | **Requirement level** | **Data type** | **Description** | -|-----------------------------|-----------------------|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| PulseSequenceType | RECOMMENDED | [string][] | A general description of the pulse sequence used for the scan (for example, MPRAGE, Gradient Echo EPI, Spin Echo EPI, Multiband gradient echo EPI). | -| ScanningSequence | RECOMMENDED | [string][] or [array][] of [strings][] | Description of the type of data acquired. Corresponds to DICOM Tag 0018, 0020 `Scanning Sequence`. | -| SequenceVariant | RECOMMENDED | [string][] or [array][] of [strings][] | Variant of the ScanningSequence. Corresponds to DICOM Tag 0018, 0021 `Sequence Variant`. | -| ScanOptions | RECOMMENDED | [string][] or [array][] of [strings][] | Parameters of ScanningSequence. Corresponds to DICOM Tag 0018, 0022 `Scan Options`. | -| SequenceName | RECOMMENDED | [string][] | Manufacturer's designation of the sequence name. Corresponds to DICOM Tag 0018, 0024 `Sequence Name`. | -| PulseSequenceDetails | RECOMMENDED | [string][] | Information beyond pulse sequence type that identifies the specific pulse sequence used (for example, "Standard Siemens Sequence distributed with the VB17 software," "Siemens WIP ### version #.##," or "Sequence written by X using a version compiled on MM/DD/YYYY"). | -| NonlinearGradientCorrection | RECOMMENDED | [boolean][] | Boolean stating if the image saved has been corrected for gradient nonlinearities by the scanner sequence. | -| MTState | RECOMMENDED | [boolean][] | Boolean stating whether the magnetization transfer pulse is applied. Corresponds to DICOM tag (0018, 9020) `Magnetization Transfer`. | -| MTOffsetFrequency | RECOMMENDED if the MTstate is `True`. | [number][] | The frequency offset of the magnetization transfer pulse with respect to the central H1 Larmor frequency in Hertz (Hz). | -| MTPulseBandwidth | RECOMMENDED if the MTstate is `True`. | [number][] | The excitation bandwidth of the magnetization transfer pulse in Hertz (Hz). | -| MTNumberOfPulses | RECOMMENDED if the MTstate is `True`. | [number][] | The number of magnetization transfer RF pulses applied before the readout. | -| MTPulseShape | RECOMMENDED if the MTstate is `True`. | [string][] | Shape of the magnetization transfer RF pulse waveform. Accepted values: `HARD`, `GAUSSIAN`, `GAUSSHANN` (gaussian pulse with Hanning window), `SINC`, `SINCHANN` (sinc pulse with Hanning window), `SINCGAUSS` (sinc pulse with Gaussian window), `FERMI`. | -| MTPulseDuration | RECOMMENDED if the MTstate is `True`. | [number][] | Duration of the magnetization transfer RF pulse in seconds. | +| **Key name** | **Requirement level** | **Data type** | **Description** | +|-----------------------------|--------------------------------------------------------------|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| PulseSequenceType | RECOMMENDED | [string][] | A general description of the pulse sequence used for the scan (for example, MPRAGE, Gradient Echo EPI, Spin Echo EPI, Multiband gradient echo EPI). | +| ScanningSequence | RECOMMENDED | [string][] or [array][] of [strings][] | Description of the type of data acquired. Corresponds to DICOM Tag 0018, 0020 `Scanning Sequence`. | +| SequenceVariant | RECOMMENDED | [string][] or [array][] of [strings][] | Variant of the ScanningSequence. Corresponds to DICOM Tag 0018, 0021 `Sequence Variant`. | +| ScanOptions | RECOMMENDED | [string][] or [array][] of [strings][] | Parameters of ScanningSequence. Corresponds to DICOM Tag 0018, 0022 `Scan Options`. | +| SequenceName | RECOMMENDED | [string][] | Manufacturer's designation of the sequence name. Corresponds to DICOM Tag 0018, 0024 `Sequence Name`. | +| PulseSequenceDetails | RECOMMENDED | [string][] | Information beyond pulse sequence type that identifies the specific pulse sequence used (for example, "Standard Siemens Sequence distributed with the VB17 software," "Siemens WIP ### version #.##," or "Sequence written by X using a version compiled on MM/DD/YYYY"). | +| NonlinearGradientCorrection | RECOMMENDED | [boolean][] | Boolean stating if the image saved has been corrected for gradient nonlinearities by the scanner sequence. | +| MTState | RECOMMENDED | [boolean][] | Boolean stating whether the magnetization transfer pulse is applied. Corresponds to DICOM tag (0018, 9020) `Magnetization Transfer`. | +| MTOffsetFrequency | RECOMMENDED if the MTstate is `True`. | [number][] | The frequency offset of the magnetization transfer pulse with respect to the central H1 Larmor frequency in Hertz (Hz). | +| MTPulseBandwidth | RECOMMENDED if the MTstate is `True`. | [number][] | The excitation bandwidth of the magnetization transfer pulse in Hertz (Hz). | +| MTNumberOfPulses | RECOMMENDED if the MTstate is `True`. | [number][] | The number of magnetization transfer RF pulses applied before the readout. | +| MTPulseShape | RECOMMENDED if the MTstate is `True`. | [string][] | Shape of the magnetization transfer RF pulse waveform. Accepted values: `HARD`, `GAUSSIAN`, `GAUSSHANN` (gaussian pulse with Hanning window), `SINC`, `SINCHANN` (sinc pulse with Hanning window), `SINCGAUSS` (sinc pulse with Gaussian window), `FERMI`. | +| MTPulseDuration | RECOMMENDED if the MTstate is `True`. | [number][] | Duration of the magnetization transfer RF pulse in seconds. | +| SpoilingState | RECOMMENDED | [boolean][] | Boolean stating whether the pulse sequence uses any type of spoiling strategy to suppress residual transverse magnetization. | +| SpoilingType | RECOMMENDED if the SpoilingState is `True`. | [string][] | Specifies which spoiling method(s) are used by a spoiled sequence. Accepted values: `RF`, `GRADIENT` or `COMBINED`. | +| SpoilingRFPhaseIncrement | RECOMMENDED if the SpoilingType is `RF` or `COMBINED`. | [number][] | The amount of incrementation described in degrees, which is applied to the phase of the excitation pulse at each TR period for achieving RF spoiling. | +| SpoilingGradientMoment | RECOMMENDED if the SpoilingType is `GRADIENT` or `COMBINED`. | [number][] | Zeroth moment of the spoiler gradient lobe in millitesla times second per meter (mT.s/m). | +| SpoilingGradientDuration | RECOMMENDED if the SpoilingType is `GRADIENT` or `COMBINED`. | [number][] | The duration of the spoiler gradient lobe in seconds. The duration of a trapezoidal lobe is defined as the summation of ramp-up and plateau times. | ### In-Plane Spatial Encoding -| **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`. | -| PhaseEncodingDirection | RECOMMENDED | [string][] | Possible values: `i`, `j`, `k`, `i-`, `j-`, `k-`. The letters `i`, `j`, `k` correspond to the first, second and third axis of the data in the NIFTI file. The polarity of the phase encoding is assumed to go from zero index to maximum index unless `-` sign is present (then the order is reversed - starting from the highest index instead of zero). `PhaseEncodingDirection` is defined as the direction along which phase is was modulated which may result in visible distortions. Note that this is not the same as the DICOM term `InPlanePhaseEncodingDirection` which can have `ROW` or `COL` values. This parameter is REQUIRED if corresponding fieldmap data is present or when using multiple runs with different phase encoding directions (which can be later used for field inhomogeneity correction). | -| EffectiveEchoSpacing | RECOMMENDED | [number][] | The "effective" sampling interval, specified in seconds, between lines in the phase-encoding direction, defined based on the size of the reconstructed image in the phase direction. It is frequently, but incorrectly, referred to as "dwell time" (see `DwellTime` parameter below for actual dwell time). It is required for unwarping distortions using field maps. Note that beyond just in-plane acceleration, a variety of other manipulations to the phase encoding need to be accounted for properly, including partial fourier, phase oversampling, phase resolution, phase field-of-view and interpolation.2 This parameter is REQUIRED if corresponding fieldmap data is present. | -| TotalReadoutTime | RECOMMENDED | [number][] | This is actually the "effective" total readout time , defined as the readout duration, specified in seconds, that would have generated data with the given level of distortion. It is NOT the actual, physical duration of the readout train. If `EffectiveEchoSpacing` has been properly computed, it is just `EffectiveEchoSpacing * (ReconMatrixPE - 1)`.3 . This parameter is REQUIRED if corresponding "field/distortion" maps acquired with opposing phase encoding directions are present (see 8.9.4). | +| **Key name** | **Requirement level** | **Data type** | **Description** | +|--------------------------------|-----------------------|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| NumberShots | RECOMMENDED | [number][] or [array][] of [numbers][] | The number of RF excitations needed to reconstruct a slice or volume (may be referred to as partition). Please mind that this is not the same as Echo Train Length which denotes the number of k-space lines collected after excitation in a multi-echo readout. The data type array is applicable for specifying this parameter before and after the k-space center is sampled. Plase see [`NumberShots` metadata field](../99-appendices/11-qmri.md#numbershots-metadata-field) in the qMRI appendix for corresponding calculations. | +| 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`. | +| PhaseEncodingDirection | RECOMMENDED | [string][] | Possible values: `i`, `j`, `k`, `i-`, `j-`, `k-`. The letters `i`, `j`, `k` correspond to the first, second and third axis of the data in the NIFTI file. The polarity of the phase encoding is assumed to go from zero index to maximum index unless `-` sign is present (then the order is reversed - starting from the highest index instead of zero). `PhaseEncodingDirection` is defined as the direction along which phase is was modulated which may result in visible distortions. Note that this is not the same as the DICOM term `InPlanePhaseEncodingDirection` which can have `ROW` or `COL` values. This parameter is REQUIRED if corresponding fieldmap data is present or when using multiple runs with different phase encoding directions (which can be later used for field inhomogeneity correction). | +| EffectiveEchoSpacing | RECOMMENDED | [number][] | The "effective" sampling interval, specified in seconds, between lines in the phase-encoding direction, defined based on the size of the reconstructed image in the phase direction. It is frequently, but incorrectly, referred to as "dwell time" (see `DwellTime` parameter below for actual dwell time). It is required for unwarping distortions using field maps. Note that beyond just in-plane acceleration, a variety of other manipulations to the phase encoding need to be accounted for properly, including partial fourier, phase oversampling, phase resolution, phase field-of-view and interpolation.2 This parameter is REQUIRED if corresponding fieldmap data is present. | +| TotalReadoutTime | RECOMMENDED | [number][] | This is actually the "effective" total readout time , defined as the readout duration, specified in seconds, that would have generated data with the given level of distortion. It is NOT the actual, physical duration of the readout train. If `EffectiveEchoSpacing` has been properly computed, it is just `EffectiveEchoSpacing * (ReconMatrixPE - 1)`.3 . This parameter is REQUIRED if corresponding "field/distortion" maps acquired with opposing phase encoding directions are present (see 8.9.4). | +| MixingTime | RECOMMENDED | [number][] | In the context of a stimulated- and spin-echo 3D EPI sequence for B1+ mapping, corresponds to the interval between spin- and stimulated-echo pulses. In the context of a diffusion-weighted double spin-echo sequence, corresponds to the interval between two successive diffusion sensitizing gradients, specified in seconds. | 2Conveniently, for Siemens data, this value is easily obtained as `1 / (BWPPPE * ReconMatrixPE)`, where BWPPPE is the @@ -133,29 +139,24 @@ Template: ```Text sub-