[SCHEMA] Add suffix term files (#772)

* Draft schema for suffixes.

* Delete Untitled.ipynb

* Clean up suffixes from Anatomical MRI's first table.

* Add second table from Anatomical MRI.

* Add third table from Anatomical MRI.

* Add first table from Task imaging data

* Add DWI and B0 field map suffixes.

* Add anatomical qMRI table suffixes

* Add field map qMRI table suffixes

* Add ASL suffixes.

* Add MEG suffixes.

* Add EEG suffixes.

* Add remaining suffixes.

* Fix T1map.

* Add make_suffix_table.

* Add angio to first suffix table.

* Add suffix info to README.

* Add descriptions for remaining suffixes.

* Update fieldmap suffix definition from #622.

* Fix bad merge.

* Use three underscores, not two.

* Apply suggestions from code review

Co-authored-by: Chris Markiewicz <effigies@gmail.com>

* Further address review.

* Apply suggestions from code review

Co-authored-by: Chris Markiewicz <effigies@gmail.com>

* Remove hardcoded tables.

Co-authored-by: Chris Markiewicz <effigies@gmail.com>

src/schema/README.md

@@ -36,6 +36,13 @@ of the schema, roughly in order of importance:
     internally, such as `code` or `sourcedata`. The schema specifies which
     folders are accepted and whether they are required or optional.
 
+-   `suffixes/*.yaml`: Suffixes supported by the specification.
+    Each suffix schema file contains, at minimum, `name` and `description`
+    fields. Additionally, it may have a `unit` field defining possible
+    units for data associated with that suffix, as well as fields
+    defining the range or types of values which are allowed for the data,
+    such as `minValue` and `maxValue`.
+
 -   `metadata/*.yaml`: Valid fields for sidecar metadata json files.
     These files contain, at minimum, the following fields: `name`,
     `description`, and a set of fields for describing the field's data type.

src/schema/suffixes/Chimap.yaml

@@ -0,0 +1,10 @@
+---
+name: Quantitative susceptibility map (QSM)
+description: |
+  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.
+unit: ppm

src/schema/suffixes/FLAIR.yaml

@@ -0,0 +1,8 @@
+---
+name: Fluid attenuated inversion recovery image
+description: |
+  In arbitrary units (arbitrary).
+  Structural images with predominant T2 contribution (also known as T2-FLAIR),
+  in which signal from fluids (for example, CSF) is nulled out by adjusting
+  inversion time, coupled with notably long repetition and echo times.
+unit: arbitrary

src/schema/suffixes/FLASH.yaml

@@ -0,0 +1,12 @@
+---
+name: Fast-Low-Angle-Shot image
+description: |
+  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.

src/schema/suffixes/IRT1.yaml

@@ -0,0 +1,6 @@
+---
+name: Inversion recovery T1 mapping
+description: |
+  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)).

src/schema/suffixes/M0map.yaml

@@ -0,0 +1,9 @@
+---
+name: Equilibrium magnetization (M0) map
+description: |
+  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).
+unit: arbitrary

src/schema/suffixes/MEGRE.yaml

@@ -0,0 +1,6 @@
+---
+name: Multi-echo Gradient Recalled Echo
+description: |
+  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.

src/schema/suffixes/MESE.yaml

@@ -0,0 +1,7 @@
+---
+name: Multi-echo Spin Echo
+description: |
+  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.

src/schema/suffixes/MP2RAGE.yaml

@@ -0,0 +1,7 @@
+---
+name: Magnetization Prepared Two Gradient Echoes
+description: |
+  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)).

src/schema/suffixes/MPM.yaml

@@ -0,0 +1,10 @@
+---
+name: Multi-parametric Mapping
+description: |
+  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.

src/schema/suffixes/MTR.yaml

@@ -0,0 +1,5 @@
+---
+name: Magnetization Transfer Ratio
+description: |
+  This method is to calculate a semi-quantitative magnetization transfer ratio
+  map.

src/schema/suffixes/MTRmap.yaml

@@ -0,0 +1,11 @@
+---
+name: Magnetization transfer ratio image
+description: |
+  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%.
+unit: arbitrary
+minValue: 0
+maxValue: 100

src/schema/suffixes/MTS.yaml

@@ -0,0 +1,8 @@
+---
+name: Magnetization transfer saturation
+description: |
+  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)).

src/schema/suffixes/MTVmap.yaml

@@ -0,0 +1,7 @@
+---
+name: Macromolecular tissue volume (MTV) image
+description: |
+  In arbitrary units (arbitrary).
+  MTV maps are REQUIRED to use this suffix regardless of the method used to
+  generate them.
+unit: arbitrary

src/schema/suffixes/MTsat.yaml

@@ -0,0 +1,7 @@
+---
+name: Magnetization transfer saturation image
+description: |
+  In arbitrary units (arbitrary).
+  MTsat maps are REQUIRED to use this suffix regardless of the method used to
+  generate them.
+unit: arbitrary

src/schema/suffixes/MWFmap.yaml

@@ -0,0 +1,11 @@
+---
+name: Myelin water fraction image
+description: |
+  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%.
+unit: arbitrary
+minValue: 0
+maxValue: 100

src/schema/suffixes/PD.yaml

@@ -0,0 +1,6 @@
+---
+name: Proton density image
+description: |
+  Ambiguous, may refer to a parametric image or to a conventional image.
+  **Change:** Replaced by `PDw` or `PDmap`.
+unit: arbitrary

src/schema/suffixes/PDT2.yaml

@@ -0,0 +1,8 @@
+---
+name: PD and T2 weighted image
+description: |
+  In arbitrary units (arbitrary).
+  PDw and T2w images acquired using a dual echo FSE sequence through view
+  sharing process
+  ([Johnson et al. 1994](https://pubmed.ncbi.nlm.nih.gov/8010268/)).
+unit: arbitrary

src/schema/suffixes/PDT2map.yaml

@@ -0,0 +1,7 @@
+---
+name: Combined PD/T2 image
+description: |
+  In arbitrary units (arbitrary).
+  Combined PD/T2 maps are REQUIRED to use this suffix regardless of the method
+  used to generate them.
+unit: arbitrary

src/schema/suffixes/PDmap.yaml

@@ -0,0 +1,7 @@
+---
+name: Proton density image
+description: |
+  In arbitrary units (arbitrary).
+  PD maps are REQUIRED to use this suffix regardless of the method used to
+  generate them.
+unit: arbitrary

src/schema/suffixes/PDw.yaml

@@ -0,0 +1,11 @@
+---
+name: Proton density (PD) weighted image
+description: |
+  In arbitrary units (arbitrary).
+  The contrast of these images is mainly determined by spatial variations in
+  the spin density (1H) of the imaged specimen.
+  In spin-echo sequences this contrast is achieved at short repetition and long
+  echo times.
+  In a gradient-echo acquisition, PD weighting dominates the contrast at long
+  repetition and short echo times, and at small flip angles.
+unit: arbitrary

src/schema/suffixes/R1map.yaml

@@ -0,0 +1,7 @@
+---
+name: Longitudinal relaxation rate image
+description: |
+  In seconds<sup>-1</sup> (1/s).
+  R1 maps (R1 = 1/T1) are REQUIRED to use this suffix regardless of the method
+  used to generate them.
+unit: 1/s

src/schema/suffixes/R2map.yaml

@@ -0,0 +1,7 @@
+---
+name: True transverse relaxation rate image
+description: |
+  In seconds<sup>-1</sup> (1/s).
+  R2 maps (R2 = 1/T2) are REQUIRED to use this suffix regardless of the method
+  used to generate them.
+unit: 1/s

src/schema/suffixes/R2starmap.yaml

@@ -0,0 +1,7 @@
+---
+name: Observed transverse relaxation rate image
+description: |
+  In seconds<sup>-1</sup> (1/s).
+  R2-star maps (R2star = 1/T2star) are REQUIRED to use this suffix regardless
+  of the method used to generate them.
+unit: 1/s

src/schema/suffixes/RB1COR.yaml

@@ -0,0 +1,7 @@
+---
+name: RB1COR
+description: |
+  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).

src/schema/suffixes/RB1map.yaml

@@ -0,0 +1,10 @@
+---
+name: RF receive sensitivity map
+description: |
+  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 Amplitude<sub>effective</sub> =
+  B1-<sub>intensity</sub>\*Amplitude<sub>ideal</sub>.
+unit: arbitrary

src/schema/suffixes/S0map.yaml

@@ -0,0 +1,11 @@
+---
+name: Observed signal amplitude (S0) image
+description: |
+  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.

src/schema/suffixes/T1map.yaml

@@ -0,0 +1,9 @@
+---
+name: Longitudinal relaxation time image
+description: |
+  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.
+unit: s

src/schema/suffixes/T1rho.yaml

@@ -0,0 +1,7 @@
+---
+name: T1 in rotating frame (T1 rho) image
+description: |
+  In seconds (s).
+  T1-rho maps are REQUIRED to use this suffix regardless of the method used to
+  generate them.
+unit: s

src/schema/suffixes/T1w.yaml

@@ -0,0 +1,14 @@
+---
+name: T1-weighted image
+description: |
+  In arbitrary units (arbitrary).
+  The contrast of these images is mainly determined by spatial variations in
+  the longitudinal relaxation time of the imaged specimen.
+  In spin-echo sequences this contrast is achieved at relatively short
+  repetition and echo times.
+  To achieve this weighting in gradient-echo images, again, short repetition
+  and echo times are selected; however, at relatively large flip angles.
+  Another common approach to increase T1 weighting in gradient-echo images is
+  to add an inversion preparation block to the beginning of the imaging
+  sequence (for example, `TurboFLASH` or `MP-RAGE`).
+unit: arbitrary

src/schema/suffixes/T2map.yaml

@@ -0,0 +1,7 @@
+---
+name: True transverse relaxation time image
+description: |
+  In seconds (s).
+  T2 maps are REQUIRED to use this suffix regardless of the method used to
+  generate them.
+unit: s

src/schema/suffixes/T2star.yaml

@@ -0,0 +1,8 @@
+---
+name: T2\* image
+description: |
+  Ambiguous, may refer to a parametric image or to a conventional image.
+  **Change:** Replaced by `T2starw` or `T2starmap`.
+anyOf:
+  - unit: arbitrary
+  - unit: s

src/schema/suffixes/T2starmap.yaml

@@ -0,0 +1,7 @@
+---
+name: Observed transverse relaxation time image
+description: |
+  In seconds (s).
+  T2-star maps are REQUIRED to use this suffix regardless of the method used to
+  generate them.
+unit: s

src/schema/suffixes/T2starw.yaml

@@ -0,0 +1,13 @@
+---
+name: T2star weighted image
+description: |
+  In arbitrary units (arbitrary).
+  The contrast of these images is mainly determined by spatial variations in
+  the (observed) transverse relaxation time of the imaged specimen.
+  In spin-echo sequences, this effect is negated as the excitation is followed
+  by an inversion pulse.
+  The contrast of gradient-echo images natively depends on T2-star effects.
+  However, for T2-star variation to dominate the image contrast,
+  gradient-echo acquisitions are carried out at long repetition and echo times,
+  and at small flip angles.
+unit: arbitrary

src/schema/suffixes/T2w.yaml

@@ -0,0 +1,12 @@
+---
+name: T2-weighted image
+description: |
+  In arbitrary units (arbitrary).
+  The contrast of these images is mainly determined by spatial variations in
+  the (true) transverse relaxation time of the imaged specimen.
+  In spin-echo sequences this contrast is achieved at relatively long
+  repetition and echo times.
+  Generally, gradient echo sequences are not the most suitable option for
+  achieving T2 weighting, as their contrast natively depends on T2-star rather
+  than on T2.
+unit: arbitrary

src/schema/suffixes/TB1AFI.yaml

@@ -0,0 +1,6 @@
+---
+name: TB1AFI
+description: |
+  This method ([Yarnykh 2007](https://doi.org/10.1002/mrm.21120))
+  calculates a B1<sup>+</sup> map from two images acquired at interleaved (two)
+  TRs with identical RF pulses using a steady-state sequence.

src/schema/suffixes/TB1DAM.yaml

@@ -0,0 +1,9 @@
+---
+name: TB1DAM
+description: |
+  The double-angle B1<sup>+</sup> 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.

src/schema/suffixes/TB1EPI.yaml

@@ -0,0 +1,8 @@
+---
+name: TB1EPI
+description: |
+  This B1<sup>+</sup> 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.

src/schema/suffixes/TB1RFM.yaml

@@ -0,0 +1,7 @@
+---
+name: TB1RFM
+description: |
+  The result of a Siemens `rf_map` product sequence.
+  This sequence produces two images.
+  The first image appears like an anatomical image and the second output is a
+  scaled flip angle map.

src/schema/suffixes/TB1SRGE.yaml

@@ -0,0 +1,10 @@
+---
+name: TB1SRGE
+description: |
+  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)).

src/schema/suffixes/TB1TFL.yaml

@@ -0,0 +1,7 @@
+---
+name: TB1TFL
+description: |
+  The result of a Siemens `tfl_b1_map` product sequence.
+  This sequence produces two images.
+  The first image appears like an anatomical image and the second output is a
+  scaled flip angle map.