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. |
2 Conveniently, for Siemens data, this value is easily obtained as
`1 / (BWPPPE * ReconMatrixPE)`, where BWPPPE is the
@@ -133,29 +139,24 @@ Template:
```Text
sub-/[ses-/]
anat/
- sub-[_ses-][_acq-][_ce-][_rec-][_run-][_part-]_.nii[.gz]
+ sub-[_ses-][_acq-][_ce-][_rec-][_run-][_part-]_.nii[.gz]
sub-[_ses-][_acq-][_ce-][_rec-][_run-][_mod-]_defacemask.nii[.gz]
```
Anatomical (structural) data acquired for that participant. Currently supported
-modalities include:
-
-| **Name** | `modality_label` | **Description** |
-| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| T1 weighted | T1w | |
-| T2 weighted | T2w | |
-| T1 Rho map | T1rho | Quantitative T1rho brain imaging `](../99-appendices/09-entities.md#rec)
key/value can be used to distinguish
different reconstruction algorithms (for example ones using motion correction).
+Structural MR images whose intensity is represented in a non-arbitrary scale
+constitute parametric maps. Currently supported parametric maps include:
+
+| **Name** | `suffix` | **Description** |
+|----------------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Longitudinal relaxation time map | T1map | In seconds (s). T1 maps are REQUIRED to use this suffix regardless of the method used to generate them. See [this interactive book on T1 mapping](https://qmrlab.org/t1_book/intro) for further reading on T1-mapping. |
+| Longitudinal relaxation rate map | R1map | In seconds-1 (1/s). R1 maps (R1 = 1/T1) are REQUIRED to use this suffix regardless of the method used to generate them. |
+| True transverse relaxation time map | T2map | In seconds (s). T2 maps are REQUIRED to use this suffix regardless of the method used to generate them. |
+| True transverse relaxation rate map | R2map | In seconds-1 (1/s). R2 maps (R2 = 1/T2) are REQUIRED to use this suffix regardless of the method used to generate them. |
+| Observed transverse relaxation time map | T2starmap | In seconds (s). T2-star maps are REQUIRED to use this suffix regardless of the method used to generate them. |
+| Observed transverse relaxation rate map | R2starmap | In seconds-1 (1/s). R2-star maps (R2star = 1/T2star) are REQUIRED to use this suffix regardless of the method used to generate them. |
+| Proton density map | PDmap | In arbitrary units (arbitrary). PD maps are REQUIRED to use this suffix regardless of the method used to generate them. |
+| Magnetization transfer ratio map | MTRmap | In arbitrary units (arbitrary). MTR maps are REQUIRED to use this suffix regardless of the method used to generate them. MTRmap intensity values are RECOMMENDED to be represented in percentage in the range of 0-100%. |
+| Magnetization transfer saturation map | MTsat | In arbitrary units (arbitrary). MTsat maps are REQUIRED to use this suffix regardless of the method used to generate them. |
+| T1 in rotating frame (T1 rho) map | T1rho | In seconds (s). T1-rho maps are REQUIRED to use this suffix regardless of the method used to generate them. |
+| Myelin water fraction map | MWFmap | In arbitrary units (arbitrary). MWF maps are REQUIRED to use this suffix regardless of the method used to generate them. MWF intensity values are RECOMMENDED to be represented in percentage in the range of 0-100%. |
+| Macromolecular tissue volume (MTV) map | MTVmap | In arbitrary units (arbitrary). MTV maps are REQUIRED to use this suffix regardless of the method used to generate them. |
+| Combined PD/T2 map | PDT2map | In arbitrary units (arbitrary). Combined PD/T2 maps are REQUIRED to use this suffix regardless of the method used to generate them. |
+| Quantitative susceptibility map (QSM) | Chimap | In parts per million (ppm). QSM allows for determining the underlying magnetic susceptibility of tissue (Chi) ([Wang & Liu, 2014](https://onlinelibrary.wiley.com/doi/10.1002/mrm.25358)). Chi maps are REQUIRED to use this suffix regardless of the method used to generate them. |
+| RF transmit field map | TB1map | In arbitrary units (arbitrary). Radio frequency (RF) transmit (B1+) field maps are REQUIRED to use this suffix regardless of the method used to generate them. TB1map intensity values are RECOMMENDED to be represented as percent multiplicative factors such that FlipAngleeffective = B1+intensity \*FlipAnglenominal . |
+| RF receive sensitivity map | RB1map | In arbitrary units (arbitrary). Radio frequency (RF) receive (B1-) sensitivity maps are REQUIRED to use this suffix regardless of the method used to generate them. RB1map intensity values are RECOMMENDED to be represented as percent multiplicative factors such that Amplitudeeffective = B1-intensity \*Amplitudeideal . |
+| Observed signal amplitude (S0) map | S0map | In arbitrary units (arbitrary). For a multi-echo (typically fMRI) sequence, S0 maps index the baseline signal before exponential (T2-star) signal decay. In other words: the exponential of the intercept for a linear decay model across log-transformed echos. For more information, please see, for example, [the tedana documentation](https://tedana.readthedocs.io/en/latest/approach.html#monoexponential-decay-model-fit). S0 maps are RECOMMENDED to use this suffix if derived from an ME-FMRI dataset. |
+| Equilibrium magnetization (M0) map | M0map | In arbitrary units (arbitrary). A common quantitative MRI (qMRI) fitting variable that represents the amount of magnetization at thermal equilibrium. M0 maps are RECOMMENDED to use this suffix if generated by qMRI applications (for example, variable flip angle T1 mapping). |
+
+Parametric images listed in the table above are typically generated by
+processing a [file collection](../02-common-principles.md#entity-linked-file-collections).
+Please visit the [file collections appendix](../99-appendices/10-file-collections.md) to see the
+list of suffixes available for quantitative MRI (qMRI) applications associated
+with these maps.
+For any other details on the organization of parametric maps, their
+recommended metadata fields, and the application specific entity or
+metadata requirement levels of [file collections](../99-appendices/10-file-collections.md) that can generate
+them, visit the [qMRI appendix](../99-appendices/11-qmri.md).
+
+### Deprecated suffixes
+
+Some suffixes that were available in versions of the specification prior to
+1.5.0 have been deprecated.
+These suffixes are ambiguous and have been superseded by more precise conventions.
+Therefore, they are not recommended for use in new datasets.
+They are, however, still valid suffixes, to maintain backwards compatibility.
+
+The following suffixes are valid, but SHOULD NOT be used for new BIDS compatible
+datasets (created after version 1.5.0.):
+
+| **Name** | `suffix` | **Reason to deprecate** |
+| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| T2\* | T2star | Ambiguous, may refer to a parametric image or to a conventional image. **Change:** Replaced by `T2starw` or `T2starmap`. |
+| FLASH | FLASH | FLASH (Fast-Low-Angle-Shot) is a vendor specific implementation for spoiled gradient echo acquisition. It is commonly used for rapid anatomical imaging and also for many different qMRI applications. When used for a single file, it does not convey any information about the image contrast. When used in a file collection, it may result in conflicts across filenames of different applications. **Change:** Removed from suffixes. |
+| Proton density | PD | Ambiguous, may refer to a parametric image or to a conventional image. **Change:** Replaced by `PDw` or `PDmap`. |
+
## Task (including resting state) imaging data
Currently supported image contrasts include:
diff --git a/src/99-appendices/04-entity-table.md b/src/99-appendices/04-entity-table.md
index b7d5dd3c65..da16d20ebc 100644
--- a/src/99-appendices/04-entity-table.md
+++ b/src/99-appendices/04-entity-table.md
@@ -18,17 +18,26 @@ while entity definitions are in [Appendix IX](09-entities.md).
## Magnetic Resonance Imaging
-| Entity | Subject | Session | Task | Acquisition | Contrast Enhancing Agent | Reconstruction | Phase-Encoding Direction | Run | Corresponding Modality | Echo | Part | Recording |
-|------------------------------------------------------------------------------------------------|-------------------------------------|-------------------------------------|---------------------------------------|-------------------------------------|-----------------------------------|-------------------------------------|-------------------------------------|-------------------------------------|-------------------------------------|---------------------------------------|---------------------------------------|-------------------------------------------------|
-| Format | [`sub-`](09-entities.md#sub) | [`ses-`](09-entities.md#ses) | [`task-`](09-entities.md#task) | [`acq-`](09-entities.md#acq) | [`ce-`](09-entities.md#ce) | [`rec-`](09-entities.md#rec) | [`dir-`](09-entities.md#dir) | [`run-`](09-entities.md#run) | [`mod-`](09-entities.md#mod) | [`echo-`](09-entities.md#echo) | [`part-`](09-entities.md#part) | [`recording-`](09-entities.md#recording) |
-| anat`](09-entities.md#sub) | [`ses-`](09-entities.md#ses) | [`task-`](09-entities.md#task) | [`acq-`](09-entities.md#acq) | [`ce-`](09-entities.md#ce) | [`rec-`](09-entities.md#rec) | [`dir-`](09-entities.md#dir) | [`run-`](09-entities.md#run) | [`mod-`](09-entities.md#mod) | [`echo-`](09-entities.md#echo) | [`flip-`](09-entities.md#flip) | [`inv-`](09-entities.md#inv) | [`mt-`](09-entities.md#mt) | [`part-`](09-entities.md#part) | [`recording-`](09-entities.md#recording) |
+| anat/[ses-/]
+ anat/
+ sub-[_ses-][_acq-][_ce-][_rec-][_run-][_echo-][_flip-][_inv-][_mt-][_part-]_.nii[.gz]
+```
+
+| Suffix | Linking entities | Application | Description |
+|---------|-----------------------|--------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| VFA | flip | Variable flip angle | The VFA method involves at least two spoiled gradient echo (SPGR) of steady-state free precession (SSFP) images acquired at different flip angles. Depending on the provided metadata fields and the sequence type, data may be eligible for DESPOT1, DESPOT2 and their variants ([Deoni et al. 2005](https://doi.org/10.1002/mrm.20314)). |
+| IRT1 | inv, part | Inversion recovery T1 mapping | The IRT1 method involves multiple inversion recovery spin-echo images acquired at different inversion times ([Barral et al. 2010](https://doi.org/10.1002/mrm.22497)). |
+| MP2RAGE | flip, inv, echo, part | Magnetization prepared two gradient echoes | The MP2RAGE method is a special protocol that collects several images at different flip angles and inversion times to create a parametric T1map by combining the magnitude and phase images ([Marques et al. 2010](https://doi.org/10.1016/j.neuroimage.2009.10.002)). |
+| MESE | echo | Multi-echo spin-echo | The MESE method involves multiple spin echo images acquired at different echo times and is primarily used for T2 mapping. Please note that this suffix is not intended for the logical grouping of images acquired using an Echo Planar Imaging (EPI) readout. |
+| MEGRE | echo | Multi-echo gradient-echo | Anatomical gradient echo images acquired at different echo times. Please note that this suffix is not intended for the logical grouping of images acquired using an Echo Planar Imaging (EPI) readout. |
+| MTR | mt | Magnetization transfer ratio | This method is to calculate a semi-quantitative magnetization transfer ratio map. |
+| MTS | flip, mt | Magnetization transfer saturation | This method is to calculate a semi-quantitative magnetization transfer saturation index map. The MTS method involves three sets of anatomical images that differ in terms of application of a magnetization transfer RF pulse (MTon or MToff) and flip angle ([Helms et al. 2008](https://doi.org/10.1002/mrm.21732)). |
+| MPM | flip, mt, echo, part | Multi-parametric mapping | The MPM approaches (a.k.a hMRI) involves the acquisition of highly-similar anatomical images that differ in terms of application of a magnetization transfer RF pulse (MTon or MToff), flip angle and (optionally) echo time and magnitue/phase parts ([Weiskopf et al. 2013](https://doi.org/10.3389/fnins.2013.00095)). See [here](https://owncloud.gwdg.de/index.php/s/iv2TOQwGy4FGDDZ) for suggested MPM acquisition protocols. |
### Fieldmap data
-| Suffix | Meta-data relevant entity | Application | Description |
-| ------ | ---------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| TB1DAM | flip | Double-angle B1+ mapping | The double-angle B1+ method ([Insko and Bolinger 1993](https://www.sciencedirect.com/science/article/abs/pii/S1064185883711332)) is based on the calculation of the actual angles from signal ratios, collected by two acquisitions at different nominal excitation flip angles. Common sequence types for this application include spin echo and echo planar imaging. |
-| TB1EPI | flip, echo | B1+ mapping with 3D EPI | This B1+ mapping method ([Jiru and Klose 2006](https://dx.doi.org/10.1002/mrm.21083)) is based on two EPI readouts to acquire spin echo (SE) and stimulated echo (STE) images at multiple flip angles in one sequence, used in the calculation of deviations from the nominal flip angle. |
-| TB1AFI | flip, inv | Actual Flip Angle Imaging (AFI) | This method ([Yarnykh 2007](https://dx.doi.org/10.1002/mrm.21120)) calculates a B1+ map from two images acquired at interleaved (two) TRs with identical RF pulses using a steady-state sequence |
-| TB1TFL | Please see the qMRI appendix | Siemens `tfl_b1_map` | B1+ data acquired using `tfl_b1_map` product sequence by Siemens based on the method by [Chung et al. (2010)](https://onlinelibrary.wiley.com/doi/full/10.1002/mrm.22423). The sequence generates one ~anatomical image and one scaled flip angle map. |
-| TB1RMF | Please see the qMRI appendix | Siemens `rf_map` | B1+ data acquired using `rf_map` product sequence by Siemens |
-| RB1COR | Please see the qMRI appendix | B1- field correction | Low resolution images acquired by the body coil (in the gantry of the scanner) and the head coil using identical acquisition parameters to generate a combined sensitivity map as described in [Papp et al. (2016)](https://onlinelibrary.wiley.com/doi/full/10.1002/mrm.26058) |
+```Text
+sub-/[ses-/]
+ fmap/
+ sub-[_ses-][_acq-][_ce-][_rec-][_run-][_echo-][_flip-][_inv-][_mt-][_part-]_.nii[.gz]
+```
+
+| Suffix | Meta-data relevant entity | Application | Description |
+|---------|--------------------------------------------------------------|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| TB1DAM | flip | Double-angle B1+ mapping | The double-angle B1+ method ([Insko and Bolinger 1993](https://doi.org/10.1006/jmra.1993.1133)) is based on the calculation of the actual angles from signal ratios, collected by two acquisitions at different nominal excitation flip angles. Common sequence types for this application include spin echo and echo planar imaging. |
+| TB1EPI | flip, echo | B1+ mapping with 3D EPI | This B1+ mapping method ([Jiru and Klose 2006](https://doi.org/10.1002/mrm.21083)) is based on two EPI readouts to acquire spin echo (SE) and stimulated echo (STE) images at multiple flip angles in one sequence, used in the calculation of deviations from the nominal flip angle. |
+| TB1AFI | Please see the [qMRI appendix](../99-appendices/11-qmri.md). | Actual Flip Angle Imaging (AFI) | This method ([Yarnykh 2007](https://doi.org/10.1002/mrm.21120)) calculates a B1+ map from two images acquired at interleaved (two) TRs with identical RF pulses using a steady-state sequence. |
+| TB1TFL | Please see the [qMRI appendix](../99-appendices/11-qmri.md). | Siemens `tfl_b1_map` | B1+ data acquired using `tfl_b1_map` product sequence by Siemens based on the method by [Chung et al. (2010)](https://doi.org/10.1002/mrm.22423). The sequence generates one anatomical image and one scaled flip angle map. |
+| TB1RMF | Please see the [qMRI appendix](../99-appendices/11-qmri.md). | Siemens `rf_map` | B1+ data acquired using `rf_map` product sequence by Siemens. |
+| TB1SRGE | `flip`, `inv` | SA2RAGE | Saturation-prepared with 2 rapid gradient echoes (SA2RAGE) uses a ratio of two saturation recovery images with different time delays, and a simulated look-up table to estimate B1+ ([Eggenschwiler et al. 2011](https://doi.org/10.1002/mrm.23145)). This sequence can also be used in conjunction with MP2RAGE T1 mapping to iteratively improve B1+ and T1 map estimation ([Marques & Gruetter 2013](https://doi.org/10.1371/journal.pone.0069294)). |
+| RB1COR | Please see the [qMRI appendix](../99-appendices/11-qmri.md). | B1- field correction | Low resolution images acquired by the body coil (in the gantry of the scanner) and the head coil using identical acquisition parameters to generate a combined sensitivity map as described in [Papp et al. (2016)](https://doi.org/10.1002/mrm.26058). |
diff --git a/src/99-appendices/11-qmri.md b/src/99-appendices/11-qmri.md
new file mode 100644
index 0000000000..c83013b409
--- /dev/null
+++ b/src/99-appendices/11-qmri.md
@@ -0,0 +1,558 @@
+# Appendix XI: Quantitative MRI
+
+Quantitative MRI (qMRI) is a collection of methods aiming at generating parametric maps
+that can characterize underlying tissue properties.
+Unlike those of conventional MR images (for example, `T1w` or `T2w`),
+intensity values of quantitative maps are not represented in an arbitrary range.
+Instead, these maps are represented either in absolute physical units
+(for example, `seconds` for `T1map`),
+or within an application dependent range of arbitrary units
+(for example, myelin water fraction `MWFmap` in brain).
+
+## Organization of qMRI data in BIDS
+
+Unlike conventional MR images, quantitative maps are not immediate products of the image reconstruction step
+(from k-space data to structural images).
+Intensity values of qMRI maps are calculated by fitting a collection of parametrically
+linked images to a biophysical model or to an MRI signal representation.
+This processing is typically carried out in the image domain.
+There are two main ways to obtain a quantitative map:
+
+1. Pre-generated qMRI maps: The qMRI maps are generated right after the reconstruction
+ of required input images and made available to the user at the scanner console.
+ The acquisition scenarios may include (a) vendor pipelines or (b) open-source pipelines
+ deployed at the scanner site.
+
+1. Post-generated qMRI maps: The qMRI maps are generated from a collection of input
+ data after they are exported from the scanner site.
+ This type of processing is commonly carried out using an open-source software such as
+ [hMRI toolbox](https://github.com/hMRI-group/hMRI-toolbox),
+ [mrQ](https://github.com/mezera/mrQ),
+ [PyQMRI](https://github.com/IMTtugraz/PyQMRI),
+ [qmap](https://www.medphysics.wisc.edu/~samsonov/qmap/doc/qmap.html),
+ [qMRLab](https://github.com/qmrlab/qmrlab),
+ and [QUIT](https://github.com/spinicist/QUIT).
+
+### Inputs are file collections
+
+The common concept of [entity-linked file collections](../02-common-principles.md#entity-linked-file-collections) enables the description of a qMRI
+application by creating logical groups of input files through `suffix` and certain entities
+representing acquisition parameters (`echo`, `flip`, `inv`, `mt`) or file parts (`part`).
+
+If a qMRI file collection is intended for creating structural quantitative maps (for example, `T1map`),
+files belonging to that collection are stored in the `anat` subfolder.
+Below is an example file collection for `MP2RAGE`:
+
+```text
+└── sub-01/
+ └── anat/
+ ├── sub-01_inv-1_part-mag_MP2RAGE.nii.gz
+ ├── sub-01_inv-1_part-phase_MP2RAGE.nii.gz
+ ├── sub-01_inv-1_MP2RAGE.json
+ ├── sub-01_inv-2_part-mag_MP2RAGE.nii.gz
+ ├── sub-01_inv-2_part-phase_MP2RAGE.nii.gz
+ └── sub-01_inv-2_MP2RAGE.json
+```
+
+Commonly, RF fieldmaps (`B1+` and `B1-` maps) are used for the correction of structural quantitative maps.
+As these images do not convey substantial structural information,
+respective file collections of RF fieldmaps are stored in the `fmap` subfolder.
+Below is an example file collection for RF transmit field map `TB1EPI`:
+
+```text
+└── sub-01/
+ └── fmap/
+ ├── sub-01_fa-1_echo-1_TB1EPI.nii.gz
+ ├── sub-01_fa-1_echo-1_TB1EPI.json
+ ├── sub-01_fa-1_echo-2_TB1EPI.nii.gz
+ ├── sub-01_fa-1_echo-2_TB1EPI.json
+ ├── sub-01_fa-2_echo-1_TB1EPI.nii.gz
+ ├── sub-01_fa-2_echo-1_TB1EPI.json
+ ├── sub-01_fa-2_echo-2_TB1EPI.nii.gz
+ └── sub-01_fa-2_echo-2_TB1EPI.json
+```
+
+Please visit the [file collections appendix](./10-file-collections.md#magnetic-resonance-imaging) to see the list of currently supported qMRI applications.
+
+### Quantitative maps are derivatives
+
+Regardless of how they are obtained (pre- or post-generated), qMRI maps are stored in the `derivatives` folder.
+For example a `T1map` can be generated from an `MP2RAGE` file collection using either options.
+
+If the map is post-generated:
+
+```text
+ ds-example/
+ └── derivatives/
+ └── qMRI-software-name/
+ └── sub-01/
+ └── anat/
+ ├── sub-01_T1map.nii.gz
+ ├── sub-01_T1map.json
+ ├── sub-01_UNIT1.nii.gz
+ └── sub-01_UNIT1.json
+```
+
+If the map is pre-generated, for example, by a Siemens scanner:
+
+```text
+ ds-example/
+ └── derivatives/
+ └── Siemens/
+ └── sub-01/
+ └── anat/
+ ├── sub-01_T1map.nii.gz
+ ├── sub-01_T1map.json
+ ├── sub-01_UNIT1.nii.gz
+ └── sub-01_UNIT1.json
+```
+
+Note: Even though the process from which pre-generated qMRI maps are obtained (vendor pipelines) is not known,
+vendors generally allow exporting of the corresponding input data.
+It is RECOMMENDED to share them along with the vendor outputs, whenever possible for a qMRI method supported by BIDS.
+
+### Example datasets
+
+You can find example file collections and qMRI maps organized according to BIDS at [https://osf.io/k4bs5/](https://osf.io/k4bs5/).
+
+## Metadata requirements for qMRI data
+
+The table of required entities for qMRI file collections are provided in the [entity table](./04-entity-table.md).
+However, viability of a qMRI file collection is determined not only by the naming and organization of the input files,
+but also by which metadata fields are provided in accompanying json files.
+
+### Method-specific priority levels for qMRI file collections
+
+#### Anatomy imaging data
+
+| **File collection** | **REQUIRED metadata** | **OPTIONAL metadata** |
+|----------------------|------------------------------------------------------------------------------------------------------------------------------|----------------------------|
+| VFA | `FlipAngle`, `PulseSequenceType`, `RepetitionTimeExcitation` | `SpoilingRFPhaseIncrement` |
+| IRT1 | `InversionTime` | |
+| MP2RAGE* | `FlipAngle`, `InversionTime`, `RepetitionTimeExcitation`, `RepetitionTimePreperation`, `NumberShots`,`MagneticFieldStrength` | `EchoTime` |
+| MESE | `EchoTime` | |
+| MEGRE | `EchoTime` | |
+| MTR | `MTState` | |
+| MTS | `FlipAngle`, `MTState`, `RepetitionTimeExcitation` | |
+| MPM | `FlipAngle`, `MTState`, `RepetitionTimeExcitation` | `EchoTime` |
+
+* Please see MP2RAGE-specific notes for the calculation of `NumberShots` and regarding the
+organization of `UNIT1` image.
+
+Explanation of the table:
+
+- The metadata fields listed in the REQUIRED column are needed to perform a minimum viable qMRI processing for the corresponding `file collection`.
+
+- Note that some of the metadata fields may be constant across different files in a file collection,
+ yet still required as an input (for example, `NumberShots` in `MP2RAGE`).
+ Such metadata fields MUST be provided in the accompanying JSON files.
+
+- The metadata fields listed in the OPTIONAL column can be used to form different flavors of an existing file collection suffix,
+ dispensing with the need for introducing a new suffix.
+ See [deriving the intended qMRI application from an ambiguous file collection](#deriving-the-intended-qmri-application-from-an-ambiguous-file-collection)
+ for details.
+
+#### Field maps
+
+| **File collection** | **REQUIRED metadata** |
+|-------------------------|------------------------------------------------------------------------------------------------------|
+| TB1DAM | `FlipAngle` |
+| TB1EPI | `EchoTime`, `FlipAngle`, `TotalReadoutTime`, `MixingTime` |
+| TB1AFI | `RepetitionTime` |
+| TB1TFL | |
+| TB1RMF | |
+| TB1SRGE* | `FlipAngle`, `InversionTime`, `RepetitionTimeExcitation`, `RepetitionTimePreperation`, `NumberShots` |
+| RB1COR | |
+
+* Please see TB1SRGE-specific notes for the calculation of `NumberShots`.
+
+### Metadata requirements for qMRI maps
+
+As qMRI maps are stored as derivatives, they are subjected to the metadata requirements of
+[derived datasets](../03-modality-agnostic-files.md#derived-dataset-and-pipeline-description).
+
+An example `dataset_description.json` for a qMRI map derivatives folder:
+
+```text
+ ds-example/
+ └── derivatives/
+ └── qMRLab/
+ ├── dataset_description.json
+ └── sub-01/
+ └── anat/
+ ├── sub-01_T1map.nii.gz
+ ├── sub-01_T1map.json
+ ├── sub-01_M0map.nii.gz
+ └── sub-01_M0map.json
+```
+
+`dataset_description.json`:
+
+```text
+{
+ "Name": "qMRLab Outputs",
+ "BIDSVersion": "1.5.0",
+ "DatasetType": "derivative",
+ "GeneratedBy": [
+ {
+ "Name": "qMRLab",
+ "Version": "2.4.1",
+ "Container": {
+ "Type": "docker",
+ "Tag": "qmrlab/minimal:2.4.1"
+ }
+ },
+ {
+ "Name": "Manual",
+ "Description": "Generated example T1map outputs"
+ }
+ ],
+ "SourceDatasets": [
+ {
+ "DOI": "DOI 10.17605/OSF.IO/K4BS5",
+ "URL": "https://osf.io/k4bs5/",
+ "Version": "1"
+ }
+ ]
+}
+```
+
+In addition to the metadata fields provided in the `dataset_description.json`,
+qMRI maps are RECOMMENDED to be accompanied by sidecar JSON files that contain further information about the quantified maps.
+Although this may not be the generic case for common derivative outputs,
+a proper interpretation of qMRI maps may critically depend on some metadata fields.
+For example, without the information of `MagneticFieldStrength`, white-matter T1 values in a `T1map` become elusive.
+
+- All the acquisition parameters that are constant across the files in a file collection are RECOMMENDED
+ to be added to the sidecar json of the qMRI maps.
+
+- Relevant acquisition parameters that vary across files in a qMRI file collection are RECOMMENDED
+ to be added to the sidecar json of the qMRI map **in array form**.
+
+- The JSON file accompanying a qMRI map which is obtained by using open-source software is RECOMMENDED
+ to include additional metadata fields listed in the following table:
+
+| **Field name** | **Definition** |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `BasedOn` | List of files in a file collection to generate the map. Fieldmaps are also listed, if involved in the processing. |
+| `EstimationReference` | Reference to the study/studies on which the implementation is based. |
+| `EstimationAlgorithm` | Type of algoritm used to perform fitting (for example, linear, non-linear, LM and such) |
+| `Units` | Units of the maps, in accordance with the BIDS specification. |
+
+Example:
+
+```text
+sub-01_T1map.nii.gz
+sub-01_T1map.json
+```
+
+sub-01_T1map.json:
+
+```text
+{
+
+<>
+
+"BasedOn":["anat/sub-01_fa-1_VFA.nii.gz",
+ "anat/sub-01_fa-2_VFA.nii.gz",
+ "anat/sub-01_fa-3_VFA.nii.gz",
+ "anat/sub-01_fa-4_VFA.nii.gz",
+ "fmap/sub-01_TB1map.nii.gz"],
+"EstimationPaper":"Deoni et. al.MRM, 2015",
+"EstimationAlgorithm":"Linear",
+"Units": "second",
+
+<>
+
+"MagneticFieldStrength": "3",
+"Manufacturer": "Siemens",
+"ManufacturerModelName": "TrioTim",
+"InstitutionName": "xxx",
+"PulseSequenceType": "SPGR",
+"PulseSequenceDetails": "Information beyond the sequence type that identifies
+ specific pulse sequence used (VB version, if not standard, Siemens WIP XXX
+ ersion ### sequence written by xx using a version compiled on mm/dd/yyyy/)",
+"RepetitionTimeExcitation": "35",
+"EchoTime": "2.86",
+"SliceThickness": "5",
+
+<>
+
+"FlipAngle": ["5","10","15","20"]
+
+}
+```
+
+## Deriving the intended qMRI application from an ambiguous file collection
+
+Certain file collection suffixes may refer to a generic data collection regime such as variable flip angle (VFA),
+rather than a more specific acquisition, for example, magnetization prepared two gradient echoes (MP2RAGE).
+Such generic acquisitions can serve as a basis to derive various qMRI applications by changes to the acquisition sequence
+(for example, readout) type or by varying additional scan parameters.
+
+If such an inheritance relationship is applicable between an already existing file collection
+and a new qMRI application to be included in the specification,
+the inheritor qMRI method is listed in the table below instead of introducing a new file collection suffix.
+This approach aims at:
+
+- preventing the list of available suffixes from over-proliferation,
+- providing qMRI-focused BIDS applications with a set of meta-data driven rules to infer possible fitting options,
+- keeping an inheritance track of the qMRI methods described within the specification.
+
+| **File-collection suffix** | **If REQUIRED metadata == Value** | **OPTIONAL metadata (`entity`/`fixed`)** | **Derived application name (NOT a suffix)** |
+|----------------------------|-----------------------------------|--------------------------------------------|---------------------------------------------|
+| VFA | `PulseSequenceType` == `SPGR` | | DESPOT1 |
+| VFA | `PulseSequenceType` == `SSFP` | `SpoilingRFPhaseIncrement` (`fixed`) | DESPOT2 |
+| MP2RAGE | | `EchoTime` (`echo`) | MP2RAGE-ME |
+| MPM | | `EchoTime` (`echo`) | MPM-ME |
+
+In this table, (`entity`/`fixed`) denotes whether the OPTIONAL metadata that forms a new
+flavor of qMRI applicaiton for the respective suffix varies across files of a file collection
+(which calls for using a linking entity) or fixed. If former is the case, the entity is to be
+added to the files in that file collection. Note that this addition MUST be allowed by the
+priority levels given for that suffix in the [`entity table`](./04-entity-table.md). If latter (`fixed`) is the case,
+filenames will remain the same; however, the optional metadata (third column) may
+define the flavor of the application (fourth column) along with the conditional value of a
+required metadata field (second column).
+
+A derived qMRI application becomes avaiable if all the optional metadata fields
+listed for the respective file collection suffix are provided for the data. In addition,
+conditional rules based on the value of a given required metada field can be set
+for the description of a derived qMRI application. Note that the value of this
+required metadata is fixed across constituent images of a file collection and defined
+in [Method-specific priority levels for qMRI file collections](#method-specific-priority-levels-for-qmri-file-collections).
+
+For example, if the optional metadata field of `PulseSequenceType` is SPGR
+for a collection of anatomical images listed by the `VFA` suffix, the data
+qualifies for `DESPOT1` T1 fitting. For the same suffix, if the `PulseSequenceType`
+metadata field has the value of `SSFP`, and the `SpoilingRFPhaseIncrement` is
+provided as a metadata field, then the dataset becomes eligible for `DESPOT2`
+T2 fitting application.
+
+Please note that optional metadata fields listed in the [deriving the intended qMRI
+application from an ambiguous file collection table](#deriving-the-intended-qmri-application-from-an-ambiguous-file-collection) are included in the optional (third)
+column of [the priority levels table](#method-specific-priority-levels-for-qmri-file-collections) for the consistency of this appendix.
+
+## Introducing a new qMRI file collection
+
+If a qMRI application cannot be interpreted as a subtype of an already existing suffix
+of a qMRI-related file collection, we RECOMMEND adhering to the following principles to
+introduce a new suffix:
+
+- All qMRI-relevant file collection suffixes are capitalized.
+
+- Unless the pulse sequence is exclusively associated with a specific qMRI application
+ (for example, `MP2RAGE`), sequence names are not used as suffixes.
+
+- File collection suffixes for qMRI applications attain a clear description of the qMRI method that they relate to in the
+ [file collections appendix](./10-file-collections.md#magnetic-resonance-imaging).
+
+- Hyperlinks to example applications and reference method articles are encouraged whenever possible.
+
+- If it is possible to derive a qMRI application from an already existing file collection suffix
+ by defining a set of logical conditions over the metadata fields, the tables of the
+ [deriving the intended qMRI application from an ambiguous file collection](#deriving-the-intended-qmri-application-from-an-ambiguous-file-collection)
+ and the
+ [anatomy data priority levels](#anatomy-imaging-data)
+ sections are extended instead of introducing a new suffix.
+
+## Application-specific notes for qMRI file collections
+
+### Anatomy imaging data
+
+General notes:
+
+- Some BIDS metadata field values are calculated based on the values of other metadata fields that are not listed as required fields.
+ These fields include: `NumberShots`.
+ The calculation of the values may depend on the type of the acquisition.
+ These acquisitions include: `MP2RAGE` and `TB1SRGE`.
+
+#### `MP2RAGE` specific notes
+
+##### `UNIT1` images
+
+Although the `UNIT1` image is provided as an output by the acquisition sequence, it is used
+as an input to offline calculation of a `T1map` using a dictionary lookup approach. However,
+`complex` data is needed for an accurate calculation of the `UNIT1` image, which is not commonly
+provided by the stock sequence. Instead, the `magnitude` and `phase` images are exported. Please
+see the relevant discussion at [qMRLab issue #255](https://github.com/qMRLab/qMRLab/issues/255).
+
+Therefore, the `UNIT1` image provided by the scanner is RECOMMENDED to be stored under the `anat`
+raw dataset directory along with the `MP2RAGE` file collection and to be used as the primary input
+for quantifying a `T1map`.
+
+If an additional `UNIT1` image is calculated offline, then the output is to be stored in the
+`derivatives` folder with neccesary provenance information.
+
+##### `NumberShots` metadata field
+
+Note that the type of `NumberShots` field can be either a `number` or an `array of numbers`.
+
+- If a single `number` is provided, this should correspond to the number of `SlicesPerSlab` or `ReconMatrixPE`.
+ However, in this case, `SlicePartialFourier` or `PartialFourierPE` fraction is needed
+ to calculate the number of partitions `before` and `after` of the k-space center to calculate a T1 map.
+
+- If `before/after` calculation is performed during the BIDS conversion of the `MP2RAGE` data,
+ then the value of `NumberShots` metadata field can be given as a 1X2 array,
+ with first entry corresponding to `before` and the second to the `after`.
+
+Formula:
+
+If NumberShots is an array of numbers such that `"NumberShots": [before, after]`,
+the values of `before` and `after` are calculated as follows:
+
+```text
+before = SlicesPerSlab*(SlicePartialFourier - 0.5)
+after = SlicesPerSlab/2
+```
+
+See this [reference implementation](https://github.com/JosePMarques/MP2RAGE-related-scripts/blob/a405df30ac2c617d29d8b1b16025aaa911e86370/func/bids_T1B1correct.m#L16).
+
+##### Other metadata fields
+
+The value of the `RepetitionTimeExcitation` field is not commonly found in the DICOM files.
+When accessible, the value of `EchoSpacing` corresponds to this metadata.
+When not accessible, `2 X EchoTime` can be used as a surrogate.
+
+Further information about other `MP2RAGE` qMRI protocol fields can be found in the
+[qMRLab documentation](https://qmrlab.readthedocs.io/en/master/protocols.html#mp2rage).
+
+#### `TB1SRGE` specific notes
+
+Calculation of `before` and `after` entries for `NumberShots` metadata field of `TB1SRGE` is more involved than that of `MP2RAGE`.
+The formula can be found in a
+[reference implementation](https://github.com/JosePMarques/MP2RAGE-related-scripts/blob/a405df30ac2c617d29d8b1b16025aaa911e86370/DemoForR1Correction.m#L17),
+which requires information about `BaseResolution` (that is, image matrix size in PE direction),
+partial Fourier fraction in the PE direction, number of reference lines for parallel imaging acceleration,
+and the parallel imaging acceleration factor in PE direction.
+
+### Radiofrequency (RF) field mapping
+
+Some RF file collections call for the use of special notations that cannot be resolved by
+by entities that can generalize to other applications.
+Instead of introducing an entity that is exclusive to a single application,
+method developers who commonly use these file collections for the `MPM` application reached
+the consensus on the use of `acq` entity to distinguish individual files.
+These suffixes include: `TB1AFI`, `TB1TFL`, `TB1RMF`, and `RB1COR`.
+
+#### `TB1EPI` specific notes
+
+The `flip` and `echo` entities MUST be used to distinguish images with this suffix.
+The use of `flip` follows the default convention. However, this suffix defines a
+specific use case for the `echo` entity:
+
+| `echo-1` | `echo-2` |
+| -------------------- | --------------------------- |
+| Lower `EchoTime` | Higher `EchoTime` |
+| Spin Echo (SE) image | Stimulated Echo (STE) image |
+
+At each `FlipAngle`, the `TB1EPI` suffix lists two images acquired at two echo times.
+The first echo is a spin echo (SE) formed by the pulses alpha-2alpha. However, the
+second echo in this method is generated in a different fashion compared to a typical
+MESE acquisition. The second echo is a stimulated echo (STE) that is formed by an
+additional alpha pulse (that is, alpha-2alpha-alpha).
+
+The `FlipAngle` value corresponds to the nominal flip angle value of the STE pulse.
+The nominal FA value of the SE pulse is twice this value.
+
+Note that the following metadata fields MUST be defined in the accompanying JSON
+files:
+
+| Field name | Definition |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TotalReadoutTime` | The effective readout length defined as `EffectiveEchoSpacing * PEReconMatrix`, with `EffectiveEchoSpacing = TrueEchoSpacing / PEacceleration` |
+| `MixingTime` | Time interval between the SE and STE pulses |
+
+To properly identify constituents of this particular method, values of the `echo`
+entity MUST index the images as follows:
+
+```text
+└── sub-01/
+ └── fmap/
+ ├── sub-01_echo-1_flip-1_TB1EPI.nii.gz (SE)
+ ├── sub-01_echo-1_flip-1_TB1EPI.json
+ ├── sub-01_echo-2_flip-1_TB1EPI.nii.gz (STE)
+ ├── sub-01_echo-2_flip-1_TB1EPI.json
+ ├── sub-01_echo-1_flip-2_TB1EPI.nii.gz (SE)
+ ├── sub-01_echo-1_flip_2_TB1EPI.json
+ ├── sub-01_echo-2_flip-2_TB1EPI.nii.gz (STE)
+ └── sub-01_echo-2_flip-2_TB1EPI.json
+```
+
+#### `TB1AFI` specific notes
+
+This method calculates a B1+ map from two images acquired at two interleaved excitation repetition times (TR).
+Note that there is no entity for the TR that can be used to label the files corresponding to the two
+repetition times and the definition of repetition time depends on the modality
+(`functional` or `anatomical`) in the specification.
+
+Therefore, to properly identify constituents of this particular method,
+values of the `acq` entity SHOULD begin with either `tr1` (lower TR) or `tr2` (higher TR)
+and MAY be followed by freeform entries:
+
+| First `TR` | Second `TR` | Use case |
+| ---------------- | ---------------- | -------------------- |
+| `_acq-tr1` | `_acq-tr2` | Single acquisition |
+| `_acq-tr1Test` | `_acq-tr2Test` | Acquisition `Test` |
+| `_acq-tr1Retest` | `_acq-tr2Retest` | Acquisition `Retest` |
+
+```text
+└── sub-01/
+ └── fmap/
+ ├── sub-01_acq-tr1_TB1AFI.nii.gz
+ ├── sub-01_acq-tr1_TB1AFI.json
+ ├── sub-01_acq-tr2_TB1AFI.nii.gz
+ └── sub-01_acq-tr2_TB1AFI.json
+```
+
+#### `TB1TFL` and `TB1RMF` specific notes
+
+These suffixes describe two outputs generated by Siemens `tfl_b1_map` and `rf_map` product sequences, respectively.
+Both sequences output two images.
+The first image appears like an anatomical image and the second output is a scaled flip angle map.
+
+To properly identify files of this particular file collection,
+values of the `acq` entity SHOULD begin with either `anat` or `famp` and MAY be followed by freeform entries:
+
+| Anatomical (like) image | Scaled FA map | Use case |
+| ----------------------- | ----------------- | -------------------- |
+| `_acq-anat` | `_acq-famp` | Single acquisition |
+| `_acq-anatTest` | `_acq-fampTest` | Acquisition `Test` |
+| `_acq-anatRetest` | `_acq-fampRetest` | Acquisition `Retest` |
+
+```text
+└── sub-01/
+ └── fmap/
+ ├── sub-01_acq-anat_TB1TFL.nii.gz
+ ├── sub-01_acq-anat_TB1TFL.json
+ ├── sub-01_acq-famp_TB1TFL.nii.gz
+ └── sub-01_acq-famp_TB1TFL.json
+```
+
+The example above applies to the `TB1RFM` suffix as well.
+
+#### `RB1COR` specific notes
+
+This method generates a sensitivity map by combining two low resolution images
+collected by two transmit coils (the body and the head coil) upon subsequent scans
+with identical acquisition parameters.
+
+To properly identify constituents of this particular method, values of the `acq`
+entity SHOULD begin with either `body` or `head` and MAY be followed by freeform
+entries:
+
+| Body coil | Head coil | Use case |
+| -------------- | -------------- | ------------------ |
+| `_acq-body` | `_acq-head` | Single acquisition |
+| `_acq-bodyMTw` | `_acq-headMTw` | `MTw` for `MPM` |
+| `_acq-bodyPDw` | `_acq-headPDw` | `PDw` for `MPM` |
+| `_acq-bodyT1w` | `_acq-headT1w` | `T1w` for `MPM` |
+
+```text
+└── sub-01/
+ └── fmap/
+ ├── sub-01_acq-body_RB1COR.nii.gz (Body coil)
+ ├── sub-01_acq-body_RB1COR.json
+ ├── sub-01_acq-head_RB1COR.nii.gz (Head coil)
+ └── sub-01_acq-head_RB1COR.json
+```
diff --git a/src/schema/datatypes/anat.yaml b/src/schema/datatypes/anat.yaml
index e0b8bad9fb..2babef87a4 100644
--- a/src/schema/datatypes/anat.yaml
+++ b/src/schema/datatypes/anat.yaml
@@ -3,17 +3,12 @@
- suffixes:
- T1w
- T2w
- - T1rho
- - T1map
- - T2map
- - T2star
+ - PDw
+ - T2starw
- FLAIR
- - FLASH
- - PD
- - PDmap
- - PDT2
- inplaneT1
- inplaneT2
+ - PDT2
- angio
extensions:
- .nii.gz
@@ -28,6 +23,38 @@
rec: optional
part: optional
# Second group
+- suffixes:
+ - T1map
+ - T2map
+ - T2starmap
+ - R1map
+ - R2map
+ - R2starmap
+ - PDmap
+ - MTRmap
+ - MTsat
+ - UNIT1
+ - T1rho
+ - MWFmap
+ - MTVmap
+ - PDT2map
+ - Chimap
+ - TB1map
+ - RB1map
+ - S0map
+ - M0map
+ extensions:
+ - .nii.gz
+ - .nii
+ - .json
+ entities:
+ sub: required
+ ses: optional
+ run: optional
+ acq: optional
+ ce: optional
+ rec: optional
+# Third group
- suffixes:
- defacemask
extensions:
@@ -42,3 +69,105 @@
ce: optional
rec: optional
mod: optional
+# Fourth group
+- suffixes:
+ - MESE
+ - MEGRE
+ extensions:
+ - .nii.gz
+ - .nii
+ - .json
+ entities:
+ sub: required
+ ses: optional
+ run: optional
+ acq: optional
+ ce: optional
+ rec: optional
+ echo: required
+ part: optional
+# Fifth group
+- suffixes:
+ - VFA
+ extensions:
+ - .nii.gz
+ - .nii
+ - .json
+ entities:
+ sub: required
+ ses: optional
+ run: optional
+ acq: optional
+ ce: optional
+ rec: optional
+ flip: required
+ part: optional
+# Sixth group
+- suffixes:
+ - IRT1
+ extensions:
+ - .nii.gz
+ - .nii
+ - .json
+ entities:
+ sub: required
+ ses: optional
+ run: optional
+ acq: optional
+ ce: optional
+ rec: optional
+ inv: required
+ part: optional
+# Seventh group
+- suffixes:
+ - MP2RAGE
+ extensions:
+ - .nii.gz
+ - .nii
+ - .json
+ entities:
+ sub: required
+ ses: optional
+ run: optional
+ acq: optional
+ ce: optional
+ rec: optional
+ echo: optional
+ flip: required
+ inv: required
+ part: optional
+# Eighth group
+- suffixes:
+ - MPM
+ - MTS
+ extensions:
+ - .nii.gz
+ - .nii
+ - .json
+ entities:
+ sub: required
+ ses: optional
+ run: optional
+ acq: optional
+ ce: optional
+ rec: optional
+ echo: optional
+ flip: required
+ mt: required
+ part: optional
+# Nineth group
+- suffixes:
+ - MTR
+ extensions:
+ - .nii.gz
+ - .nii
+ - .json
+ entities:
+ sub: required
+ ses: optional
+ run: optional
+ acq: optional
+ ce: optional
+ rec: optional
+ mt: required
+ part: optional
diff --git a/src/schema/datatypes/fmap.yaml b/src/schema/datatypes/fmap.yaml
index 98d0f6c45c..0391a6e0f1 100644
--- a/src/schema/datatypes/fmap.yaml
+++ b/src/schema/datatypes/fmap.yaml
@@ -31,3 +31,36 @@
ce: optional
dir: required
run: optional
+# Third group
+- suffixes:
+ - TB1DAM
+ extensions:
+ - .nii.gz
+ - .nii
+ - .json
+ entities:
+ sub: required
+ ses: optional
+ run: optional
+ acq: optional
+ ce: optional
+ rec: optional
+ flip: required
+ part: optional
+# Fourth group
+- suffixes:
+ - TB1EPI
+ extensions:
+ - .nii.gz
+ - .nii
+ - .json
+ entities:
+ sub: required
+ ses: optional
+ run: optional
+ acq: optional
+ ce: optional
+ rec: optional
+ echo: required
+ flip: required
+ part: optional