From ed1357cf5eacd91c482e88dea3fc9665dab3d717 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Tue, 20 Jul 2021 10:58:23 -0400 Subject: [PATCH] [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 * Further address review. * Apply suggestions from code review Co-authored-by: Chris Markiewicz * Remove hardcoded tables. Co-authored-by: Chris Markiewicz --- .../01-magnetic-resonance-imaging-data.md | 115 +++++++++++------- src/schema/README.md | 7 ++ src/schema/suffixes/Chimap.yaml | 10 ++ src/schema/suffixes/FLAIR.yaml | 8 ++ src/schema/suffixes/FLASH.yaml | 12 ++ src/schema/suffixes/IRT1.yaml | 6 + src/schema/suffixes/M0map.yaml | 9 ++ src/schema/suffixes/MEGRE.yaml | 6 + src/schema/suffixes/MESE.yaml | 7 ++ src/schema/suffixes/MP2RAGE.yaml | 7 ++ src/schema/suffixes/MPM.yaml | 10 ++ src/schema/suffixes/MTR.yaml | 5 + src/schema/suffixes/MTRmap.yaml | 11 ++ src/schema/suffixes/MTS.yaml | 8 ++ src/schema/suffixes/MTVmap.yaml | 7 ++ src/schema/suffixes/MTsat.yaml | 7 ++ src/schema/suffixes/MWFmap.yaml | 11 ++ src/schema/suffixes/PD.yaml | 6 + src/schema/suffixes/PDT2.yaml | 8 ++ src/schema/suffixes/PDT2map.yaml | 7 ++ src/schema/suffixes/PDmap.yaml | 7 ++ src/schema/suffixes/PDw.yaml | 11 ++ src/schema/suffixes/R1map.yaml | 7 ++ src/schema/suffixes/R2map.yaml | 7 ++ src/schema/suffixes/R2starmap.yaml | 7 ++ src/schema/suffixes/RB1COR.yaml | 7 ++ src/schema/suffixes/RB1map.yaml | 10 ++ src/schema/suffixes/S0map.yaml | 11 ++ src/schema/suffixes/T1map.yaml | 9 ++ src/schema/suffixes/T1rho.yaml | 7 ++ src/schema/suffixes/T1w.yaml | 14 +++ src/schema/suffixes/T2map.yaml | 7 ++ src/schema/suffixes/T2star.yaml | 8 ++ src/schema/suffixes/T2starmap.yaml | 7 ++ src/schema/suffixes/T2starw.yaml | 13 ++ src/schema/suffixes/T2w.yaml | 12 ++ src/schema/suffixes/TB1AFI.yaml | 6 + src/schema/suffixes/TB1DAM.yaml | 9 ++ src/schema/suffixes/TB1EPI.yaml | 8 ++ src/schema/suffixes/TB1RFM.yaml | 7 ++ src/schema/suffixes/TB1SRGE.yaml | 10 ++ src/schema/suffixes/TB1TFL.yaml | 7 ++ src/schema/suffixes/TB1map.yaml | 10 ++ src/schema/suffixes/UNIT1.yaml | 12 ++ src/schema/suffixes/VFA.yaml | 8 ++ src/schema/suffixes/_template.yaml | 3 + src/schema/suffixes/angio.yaml | 6 + src/schema/suffixes/asl.yaml | 6 + src/schema/suffixes/aslcontext.yaml | 4 + src/schema/suffixes/asllabeling.yaml | 6 + src/schema/suffixes/beh.yaml | 6 + src/schema/suffixes/blood.yaml | 6 + src/schema/suffixes/bold.yaml | 4 + src/schema/suffixes/cbv.yaml | 4 + src/schema/suffixes/channels.yaml | 4 + src/schema/suffixes/coordsystem.yaml | 5 + src/schema/suffixes/defacemask.yaml | 5 + src/schema/suffixes/dwi.yaml | 4 + src/schema/suffixes/eeg.yaml | 4 + src/schema/suffixes/electrodes.yaml | 4 + src/schema/suffixes/epi.yaml | 6 + src/schema/suffixes/events.yaml | 4 + src/schema/suffixes/fieldmap.yaml | 5 + src/schema/suffixes/headshape.yaml | 5 + src/schema/suffixes/ieeg.yaml | 4 + src/schema/suffixes/inplaneT1.yaml | 6 + src/schema/suffixes/inplaneT2.yaml | 6 + src/schema/suffixes/m0scan.yaml | 5 + src/schema/suffixes/magnitude.yaml | 6 + src/schema/suffixes/magnitude1.yaml | 5 + src/schema/suffixes/magnitude2.yaml | 5 + src/schema/suffixes/markers.yaml | 8 ++ src/schema/suffixes/meg.yaml | 5 + src/schema/suffixes/pet.yaml | 7 ++ src/schema/suffixes/phase.yaml | 12 ++ src/schema/suffixes/phase1.yaml | 5 + src/schema/suffixes/phase2.yaml | 5 + src/schema/suffixes/phasediff.yaml | 7 ++ src/schema/suffixes/photo.yaml | 5 + src/schema/suffixes/physio.yaml | 4 + src/schema/suffixes/sbref.yaml | 4 + src/schema/suffixes/stim.yaml | 4 + tools/mkdocs_macros_bidsschema/main.py | 12 +- tools/schemacode/macros.py | 20 +++ tools/schemacode/schema.py | 51 ++++++++ 85 files changed, 715 insertions(+), 50 deletions(-) create mode 100644 src/schema/suffixes/Chimap.yaml create mode 100644 src/schema/suffixes/FLAIR.yaml create mode 100644 src/schema/suffixes/FLASH.yaml create mode 100644 src/schema/suffixes/IRT1.yaml create mode 100644 src/schema/suffixes/M0map.yaml create mode 100644 src/schema/suffixes/MEGRE.yaml create mode 100644 src/schema/suffixes/MESE.yaml create mode 100644 src/schema/suffixes/MP2RAGE.yaml create mode 100644 src/schema/suffixes/MPM.yaml create mode 100644 src/schema/suffixes/MTR.yaml create mode 100644 src/schema/suffixes/MTRmap.yaml create mode 100644 src/schema/suffixes/MTS.yaml create mode 100644 src/schema/suffixes/MTVmap.yaml create mode 100644 src/schema/suffixes/MTsat.yaml create mode 100644 src/schema/suffixes/MWFmap.yaml create mode 100644 src/schema/suffixes/PD.yaml create mode 100644 src/schema/suffixes/PDT2.yaml create mode 100644 src/schema/suffixes/PDT2map.yaml create mode 100644 src/schema/suffixes/PDmap.yaml create mode 100644 src/schema/suffixes/PDw.yaml create mode 100644 src/schema/suffixes/R1map.yaml create mode 100644 src/schema/suffixes/R2map.yaml create mode 100644 src/schema/suffixes/R2starmap.yaml create mode 100644 src/schema/suffixes/RB1COR.yaml create mode 100644 src/schema/suffixes/RB1map.yaml create mode 100644 src/schema/suffixes/S0map.yaml create mode 100644 src/schema/suffixes/T1map.yaml create mode 100644 src/schema/suffixes/T1rho.yaml create mode 100644 src/schema/suffixes/T1w.yaml create mode 100644 src/schema/suffixes/T2map.yaml create mode 100644 src/schema/suffixes/T2star.yaml create mode 100644 src/schema/suffixes/T2starmap.yaml create mode 100644 src/schema/suffixes/T2starw.yaml create mode 100644 src/schema/suffixes/T2w.yaml create mode 100644 src/schema/suffixes/TB1AFI.yaml create mode 100644 src/schema/suffixes/TB1DAM.yaml create mode 100644 src/schema/suffixes/TB1EPI.yaml create mode 100644 src/schema/suffixes/TB1RFM.yaml create mode 100644 src/schema/suffixes/TB1SRGE.yaml create mode 100644 src/schema/suffixes/TB1TFL.yaml create mode 100644 src/schema/suffixes/TB1map.yaml create mode 100644 src/schema/suffixes/UNIT1.yaml create mode 100644 src/schema/suffixes/VFA.yaml create mode 100644 src/schema/suffixes/_template.yaml create mode 100644 src/schema/suffixes/angio.yaml create mode 100644 src/schema/suffixes/asl.yaml create mode 100644 src/schema/suffixes/aslcontext.yaml create mode 100644 src/schema/suffixes/asllabeling.yaml create mode 100644 src/schema/suffixes/beh.yaml create mode 100644 src/schema/suffixes/blood.yaml create mode 100644 src/schema/suffixes/bold.yaml create mode 100644 src/schema/suffixes/cbv.yaml create mode 100644 src/schema/suffixes/channels.yaml create mode 100644 src/schema/suffixes/coordsystem.yaml create mode 100644 src/schema/suffixes/defacemask.yaml create mode 100644 src/schema/suffixes/dwi.yaml create mode 100644 src/schema/suffixes/eeg.yaml create mode 100644 src/schema/suffixes/electrodes.yaml create mode 100644 src/schema/suffixes/epi.yaml create mode 100644 src/schema/suffixes/events.yaml create mode 100644 src/schema/suffixes/fieldmap.yaml create mode 100644 src/schema/suffixes/headshape.yaml create mode 100644 src/schema/suffixes/ieeg.yaml create mode 100644 src/schema/suffixes/inplaneT1.yaml create mode 100644 src/schema/suffixes/inplaneT2.yaml create mode 100644 src/schema/suffixes/m0scan.yaml create mode 100644 src/schema/suffixes/magnitude.yaml create mode 100644 src/schema/suffixes/magnitude1.yaml create mode 100644 src/schema/suffixes/magnitude2.yaml create mode 100644 src/schema/suffixes/markers.yaml create mode 100644 src/schema/suffixes/meg.yaml create mode 100644 src/schema/suffixes/pet.yaml create mode 100644 src/schema/suffixes/phase.yaml create mode 100644 src/schema/suffixes/phase1.yaml create mode 100644 src/schema/suffixes/phase2.yaml create mode 100644 src/schema/suffixes/phasediff.yaml create mode 100644 src/schema/suffixes/photo.yaml create mode 100644 src/schema/suffixes/physio.yaml create mode 100644 src/schema/suffixes/sbref.yaml create mode 100644 src/schema/suffixes/stim.yaml 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 d637e5b5a6..c4d7125bbd 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 @@ -195,6 +195,21 @@ whenever possible. See also Anatomical (structural) data acquired for that participant. Currently supported non-parametric structural MR images include: +{{ MACROS___make_suffix_table( + [ + "T1w", + "T2w", + "PDw", + "T2starw", + "FLAIR", + "inplaneT1", + "inplaneT2", + "PDT2", + "UNIT1", + ] + ) +}} + | **Name** | `suffix` | **Description** | | -------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | T1 weighted images | T1w | 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`). | @@ -297,26 +312,29 @@ 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). | +{{ MACROS___make_suffix_table( + [ + "T1map", + "R1map", + "T2map", + "R2map", + "T2starmap", + "R2starmap", + "PDmap", + "MTRmap", + "MTsat", + "T1rho", + "MWFmap", + "MTVmap", + "PDT2map", + "Chimap", + "TB1map", + "RB1map", + "S0map", + "M0map", + ] + ) +}} Parametric images listed in the table above are typically generated by processing a [file collection](../02-common-principles.md#entity-linked-file-collections). @@ -339,21 +357,27 @@ 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`. | +{{ MACROS___make_suffix_table( + [ + "T2star", + "FLASH", + "PD", + ] + ) +}} ## Task (including resting state) imaging data Currently supported image contrasts include: -| **Name** | `suffix` | **Description** | -| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| BOLD | bold | Blood-Oxygen-Level Dependent contrast (specialized T2\* weighting) | -| CBV | cbv | Cerebral Blood Volume contrast (specialized T2\* weighting or difference between T1 weighted images) | -| Phase | phase | [DEPRECATED](../02-common-principles.md#definitions). Phase information associated with magnitude information stored in BOLD contrast. This suffix should be replaced by the [`part-phase`](../99-appendices/09-entities.md#part) in conjunction with the `bold` suffix. | +{{ MACROS___make_suffix_table( + [ + "bold", + "cbv", + "phase", + ] + ) +}} {{ MACROS___make_filename_template(datatypes=["func"]) }} @@ -548,10 +572,13 @@ participant, task and run takes precedence. Diffusion-weighted imaging data acquired for a participant. Currently supported image types include: -| **Name** | `suffix` | **Description** | -| --------------------- | -------- | ----------------------------------------------------------------- | -| DWI | dwi | Diffusion-weighted imaging contrast (specialized T2\* weighting). | -| Single-Band Reference | sbref | Single-band reference for one or more multi-band `dwi` images. | +{{ MACROS___make_suffix_table( + [ + "dwi", + "sbref", + ] + ) +}} {{ MACROS___make_filename_template(datatypes=["dwi"]) }} @@ -888,13 +915,19 @@ The current version of this standard considers four different scenarios: These four different types of field mapping strategies can be encoded using the following image types: -| **Name** | **`suffix`** | **Description** | -| ---------------- | -----------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Magnitude | magnitude\[1,2\] | Field-mapping MR schemes such as gradient-recalled echo (GRE) generate a Magnitude image to be used for anatomical reference. Requires the existence of Phase, Phase-difference or Fieldmap maps. | -| Phase | phase{1,2} | Phase map generated by GRE or similar schemes, each associated with the first (`phase1`) or second (`phase2`) echoes in the sequence. | -| Phase-difference | phasediff | Some scanners subtract the `phase1` from the `phase2` map and generate a unique `phasediff` file. For instance, this is a common output for the built-in fieldmap sequence of Siemens scanners. | -| Fieldmap | fieldmap | Some MR schemes such as spiral-echo imaging (SEI) sequences are able to directly provide maps of the *B0* field inhomogeneity. | -| EPI | epi | The phase-encoding polarity (PEpolar) technique combines two or more Spin Echo EPI scans with different phase encoding directions to estimate the underlying inhomogeneity/deformation map. | +{{ MACROS___make_suffix_table( + [ + "magnitude", + "magnitude1", + "magnitude2", + "phase1", + "phase2", + "phasediff", + "fieldmap", + "epi", + ] + ) +}} Two OPTIONAL entities, following more general rules of the specification, are allowed across all the four scenarios: diff --git a/src/schema/README.md b/src/schema/README.md index 989ee904c2..10a177ae0d 100644 --- a/src/schema/README.md +++ b/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. diff --git a/src/schema/suffixes/Chimap.yaml b/src/schema/suffixes/Chimap.yaml new file mode 100644 index 0000000000..d5c1463da7 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/FLAIR.yaml b/src/schema/suffixes/FLAIR.yaml new file mode 100644 index 0000000000..15a5d177a8 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/FLASH.yaml b/src/schema/suffixes/FLASH.yaml new file mode 100644 index 0000000000..5e8f678a53 --- /dev/null +++ b/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. diff --git a/src/schema/suffixes/IRT1.yaml b/src/schema/suffixes/IRT1.yaml new file mode 100644 index 0000000000..0c362a5ee4 --- /dev/null +++ b/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)). diff --git a/src/schema/suffixes/M0map.yaml b/src/schema/suffixes/M0map.yaml new file mode 100644 index 0000000000..32449df3cd --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/MEGRE.yaml b/src/schema/suffixes/MEGRE.yaml new file mode 100644 index 0000000000..c30fa512cc --- /dev/null +++ b/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. diff --git a/src/schema/suffixes/MESE.yaml b/src/schema/suffixes/MESE.yaml new file mode 100644 index 0000000000..b9633cf763 --- /dev/null +++ b/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. diff --git a/src/schema/suffixes/MP2RAGE.yaml b/src/schema/suffixes/MP2RAGE.yaml new file mode 100644 index 0000000000..ab98964bc0 --- /dev/null +++ b/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)). diff --git a/src/schema/suffixes/MPM.yaml b/src/schema/suffixes/MPM.yaml new file mode 100644 index 0000000000..a536ff06ca --- /dev/null +++ b/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. diff --git a/src/schema/suffixes/MTR.yaml b/src/schema/suffixes/MTR.yaml new file mode 100644 index 0000000000..47a8946ce0 --- /dev/null +++ b/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. diff --git a/src/schema/suffixes/MTRmap.yaml b/src/schema/suffixes/MTRmap.yaml new file mode 100644 index 0000000000..654df49e78 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/MTS.yaml b/src/schema/suffixes/MTS.yaml new file mode 100644 index 0000000000..f2417db654 --- /dev/null +++ b/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)). diff --git a/src/schema/suffixes/MTVmap.yaml b/src/schema/suffixes/MTVmap.yaml new file mode 100644 index 0000000000..524dc29fc9 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/MTsat.yaml b/src/schema/suffixes/MTsat.yaml new file mode 100644 index 0000000000..f708c2bd16 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/MWFmap.yaml b/src/schema/suffixes/MWFmap.yaml new file mode 100644 index 0000000000..f6d95736ee --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/PD.yaml b/src/schema/suffixes/PD.yaml new file mode 100644 index 0000000000..2a7b928606 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/PDT2.yaml b/src/schema/suffixes/PDT2.yaml new file mode 100644 index 0000000000..2a31c9cfcb --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/PDT2map.yaml b/src/schema/suffixes/PDT2map.yaml new file mode 100644 index 0000000000..10d5d08829 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/PDmap.yaml b/src/schema/suffixes/PDmap.yaml new file mode 100644 index 0000000000..51b4d02102 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/PDw.yaml b/src/schema/suffixes/PDw.yaml new file mode 100644 index 0000000000..94a259f393 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/R1map.yaml b/src/schema/suffixes/R1map.yaml new file mode 100644 index 0000000000..5d6721d2c4 --- /dev/null +++ b/src/schema/suffixes/R1map.yaml @@ -0,0 +1,7 @@ +--- +name: Longitudinal relaxation rate image +description: | + In seconds-1 (1/s). + R1 maps (R1 = 1/T1) are REQUIRED to use this suffix regardless of the method + used to generate them. +unit: 1/s diff --git a/src/schema/suffixes/R2map.yaml b/src/schema/suffixes/R2map.yaml new file mode 100644 index 0000000000..fb43e69981 --- /dev/null +++ b/src/schema/suffixes/R2map.yaml @@ -0,0 +1,7 @@ +--- +name: True transverse relaxation rate image +description: | + In seconds-1 (1/s). + R2 maps (R2 = 1/T2) are REQUIRED to use this suffix regardless of the method + used to generate them. +unit: 1/s diff --git a/src/schema/suffixes/R2starmap.yaml b/src/schema/suffixes/R2starmap.yaml new file mode 100644 index 0000000000..5306f9fe1e --- /dev/null +++ b/src/schema/suffixes/R2starmap.yaml @@ -0,0 +1,7 @@ +--- +name: Observed transverse relaxation rate image +description: | + 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. +unit: 1/s diff --git a/src/schema/suffixes/RB1COR.yaml b/src/schema/suffixes/RB1COR.yaml new file mode 100644 index 0000000000..404432908e --- /dev/null +++ b/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). diff --git a/src/schema/suffixes/RB1map.yaml b/src/schema/suffixes/RB1map.yaml new file mode 100644 index 0000000000..0202e74ad3 --- /dev/null +++ b/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 Amplitudeeffective = + B1-intensity\*Amplitudeideal. +unit: arbitrary diff --git a/src/schema/suffixes/S0map.yaml b/src/schema/suffixes/S0map.yaml new file mode 100644 index 0000000000..e8f8f8a273 --- /dev/null +++ b/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. diff --git a/src/schema/suffixes/T1map.yaml b/src/schema/suffixes/T1map.yaml new file mode 100644 index 0000000000..8aea121aee --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/T1rho.yaml b/src/schema/suffixes/T1rho.yaml new file mode 100644 index 0000000000..3d39ee40d1 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/T1w.yaml b/src/schema/suffixes/T1w.yaml new file mode 100644 index 0000000000..68c81a8d32 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/T2map.yaml b/src/schema/suffixes/T2map.yaml new file mode 100644 index 0000000000..e6f99e1599 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/T2star.yaml b/src/schema/suffixes/T2star.yaml new file mode 100644 index 0000000000..1af9d615c1 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/T2starmap.yaml b/src/schema/suffixes/T2starmap.yaml new file mode 100644 index 0000000000..479762abd9 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/T2starw.yaml b/src/schema/suffixes/T2starw.yaml new file mode 100644 index 0000000000..6e3ede6b71 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/T2w.yaml b/src/schema/suffixes/T2w.yaml new file mode 100644 index 0000000000..c2390df393 --- /dev/null +++ b/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 diff --git a/src/schema/suffixes/TB1AFI.yaml b/src/schema/suffixes/TB1AFI.yaml new file mode 100644 index 0000000000..a18a3e2091 --- /dev/null +++ b/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+ map from two images acquired at interleaved (two) + TRs with identical RF pulses using a steady-state sequence. diff --git a/src/schema/suffixes/TB1DAM.yaml b/src/schema/suffixes/TB1DAM.yaml new file mode 100644 index 0000000000..abb23b39f3 --- /dev/null +++ b/src/schema/suffixes/TB1DAM.yaml @@ -0,0 +1,9 @@ +--- +name: TB1DAM +description: | + 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. diff --git a/src/schema/suffixes/TB1EPI.yaml b/src/schema/suffixes/TB1EPI.yaml new file mode 100644 index 0000000000..d67422c8ea --- /dev/null +++ b/src/schema/suffixes/TB1EPI.yaml @@ -0,0 +1,8 @@ +--- +name: TB1EPI +description: | + 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. diff --git a/src/schema/suffixes/TB1RFM.yaml b/src/schema/suffixes/TB1RFM.yaml new file mode 100644 index 0000000000..12e73de764 --- /dev/null +++ b/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. diff --git a/src/schema/suffixes/TB1SRGE.yaml b/src/schema/suffixes/TB1SRGE.yaml new file mode 100644 index 0000000000..5e67f92980 --- /dev/null +++ b/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)). diff --git a/src/schema/suffixes/TB1TFL.yaml b/src/schema/suffixes/TB1TFL.yaml new file mode 100644 index 0000000000..5c60475469 --- /dev/null +++ b/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. diff --git a/src/schema/suffixes/TB1map.yaml b/src/schema/suffixes/TB1map.yaml new file mode 100644 index 0000000000..5c26e19f12 --- /dev/null +++ b/src/schema/suffixes/TB1map.yaml @@ -0,0 +1,10 @@ +--- +name: RF transmit field image +description: | + 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 . +unit: arbitrary diff --git a/src/schema/suffixes/UNIT1.yaml b/src/schema/suffixes/UNIT1.yaml new file mode 100644 index 0000000000..185559c56d --- /dev/null +++ b/src/schema/suffixes/UNIT1.yaml @@ -0,0 +1,12 @@ +--- +name: Homogeneous (flat) T1-weighted MP2RAGE image +description: | + In arbitrary units (arbitrary). + UNIT1 images are REQUIRED to use this suffix regardless of the method used to + generate them. + Note that although this image is T1-weighted, regions without MR signal will + contain white salt-and-pepper noise that most segmentation algorithms will + fail on. + Therefore, it is important to dissociate it from from `T1w`. + Plase see [`MP2RAGE` specific notes](/99-appendices/11-qmri.html#unit1-images) + in the qMRI appendix for further information. diff --git a/src/schema/suffixes/VFA.yaml b/src/schema/suffixes/VFA.yaml new file mode 100644 index 0000000000..fbdedad562 --- /dev/null +++ b/src/schema/suffixes/VFA.yaml @@ -0,0 +1,8 @@ +--- +name: Variable flip angle +description: | + 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)). diff --git a/src/schema/suffixes/_template.yaml b/src/schema/suffixes/_template.yaml new file mode 100644 index 0000000000..d5f7e6e4e8 --- /dev/null +++ b/src/schema/suffixes/_template.yaml @@ -0,0 +1,3 @@ +--- +name: +description: diff --git a/src/schema/suffixes/angio.yaml b/src/schema/suffixes/angio.yaml new file mode 100644 index 0000000000..f9dae61183 --- /dev/null +++ b/src/schema/suffixes/angio.yaml @@ -0,0 +1,6 @@ +--- +name: Angiogram +description: | + Magnetic resonance angiography sequences focus on enhancing the contrast of + blood vessels (generally arteries, but sometimes veins) against other tissue + types. diff --git a/src/schema/suffixes/asl.yaml b/src/schema/suffixes/asl.yaml new file mode 100644 index 0000000000..deade6a50b --- /dev/null +++ b/src/schema/suffixes/asl.yaml @@ -0,0 +1,6 @@ +--- +name: Arterial Spin Labeling +description: | + The complete ASL time series stored as a 4D NIfTI file in the original + acquisition order, with possible volume types including: control, label, + m0scan, deltam, cbf. diff --git a/src/schema/suffixes/aslcontext.yaml b/src/schema/suffixes/aslcontext.yaml new file mode 100644 index 0000000000..75e6851bf4 --- /dev/null +++ b/src/schema/suffixes/aslcontext.yaml @@ -0,0 +1,4 @@ +--- +name: Arterial Spin Labeling Context +description: | + A TSV file defining the image types for volumes in an associated ASL file. diff --git a/src/schema/suffixes/asllabeling.yaml b/src/schema/suffixes/asllabeling.yaml new file mode 100644 index 0000000000..7a4043622c --- /dev/null +++ b/src/schema/suffixes/asllabeling.yaml @@ -0,0 +1,6 @@ +--- +name: ASL Labeling Screenshot +description: | + An anonymized screenshot of the planning of the labeling slab/plane with + respect to the imaging slab or slices `*_asllabeling.jpg`. + Based on DICOM macro C.8.13.5.14. diff --git a/src/schema/suffixes/beh.yaml b/src/schema/suffixes/beh.yaml new file mode 100644 index 0000000000..a6c99ba991 --- /dev/null +++ b/src/schema/suffixes/beh.yaml @@ -0,0 +1,6 @@ +--- +name: Behavioral recording +description: | + Behavioral recordings from tasks. + These files are similar to events files, but do not include the `"onset"` and + `"duration"` columns that are mandatory for events files. diff --git a/src/schema/suffixes/blood.yaml b/src/schema/suffixes/blood.yaml new file mode 100644 index 0000000000..b162a421b6 --- /dev/null +++ b/src/schema/suffixes/blood.yaml @@ -0,0 +1,6 @@ +--- +name: Blood recording data +description: | + Blood measurements of radioactivity stored in + [tabular files](/02-common-principles.html#tabular-files) + and located in the `pet/` directory along with the corresponding PET data. diff --git a/src/schema/suffixes/bold.yaml b/src/schema/suffixes/bold.yaml new file mode 100644 index 0000000000..fbc624fed9 --- /dev/null +++ b/src/schema/suffixes/bold.yaml @@ -0,0 +1,4 @@ +--- +name: Blood-Oxygen-Level Dependent image +description: | + Blood-Oxygen-Level Dependent contrast (specialized T2\* weighting) diff --git a/src/schema/suffixes/cbv.yaml b/src/schema/suffixes/cbv.yaml new file mode 100644 index 0000000000..344e42ce65 --- /dev/null +++ b/src/schema/suffixes/cbv.yaml @@ -0,0 +1,4 @@ +--- +name: Cerebral blood volume image +description: | + Cerebral Blood Volume contrast (specialized T2\* weighting or difference between T1 weighted images) diff --git a/src/schema/suffixes/channels.yaml b/src/schema/suffixes/channels.yaml new file mode 100644 index 0000000000..cc4d529767 --- /dev/null +++ b/src/schema/suffixes/channels.yaml @@ -0,0 +1,4 @@ +--- +name: Channels File +description: | + Channel information. diff --git a/src/schema/suffixes/coordsystem.yaml b/src/schema/suffixes/coordsystem.yaml new file mode 100644 index 0000000000..d3228210d1 --- /dev/null +++ b/src/schema/suffixes/coordsystem.yaml @@ -0,0 +1,5 @@ +--- +name: Coordinate System File +description: | + A JSON document specifying the coordinate system(s) used for the MEG, EEG, + head localization coils, and anatomical landmarks. diff --git a/src/schema/suffixes/defacemask.yaml b/src/schema/suffixes/defacemask.yaml new file mode 100644 index 0000000000..32fa386ac2 --- /dev/null +++ b/src/schema/suffixes/defacemask.yaml @@ -0,0 +1,5 @@ +--- +name: Defacing Mask +description: | + A binary mask that was used to remove facial features from an anatomical MRI + image. diff --git a/src/schema/suffixes/dwi.yaml b/src/schema/suffixes/dwi.yaml new file mode 100644 index 0000000000..a3c63a101a --- /dev/null +++ b/src/schema/suffixes/dwi.yaml @@ -0,0 +1,4 @@ +--- +name: Diffusion-weighted image +description: | + Diffusion-weighted imaging contrast (specialized T2\* weighting). diff --git a/src/schema/suffixes/eeg.yaml b/src/schema/suffixes/eeg.yaml new file mode 100644 index 0000000000..6aa40fdf39 --- /dev/null +++ b/src/schema/suffixes/eeg.yaml @@ -0,0 +1,4 @@ +--- +name: Electroencephalography +description: | + Electroencephalography recording data. diff --git a/src/schema/suffixes/electrodes.yaml b/src/schema/suffixes/electrodes.yaml new file mode 100644 index 0000000000..056e5fb046 --- /dev/null +++ b/src/schema/suffixes/electrodes.yaml @@ -0,0 +1,4 @@ +--- +name: Electrodes +description: | + File that gives the location of (i)EEG electrodes. diff --git a/src/schema/suffixes/epi.yaml b/src/schema/suffixes/epi.yaml new file mode 100644 index 0000000000..2c8600f63f --- /dev/null +++ b/src/schema/suffixes/epi.yaml @@ -0,0 +1,6 @@ +--- +name: EPI +description: | + The phase-encoding polarity (PEpolar) technique combines two or more Spin Echo + EPI scans with different phase encoding directions to estimate the underlying + inhomogeneity/deformation map. diff --git a/src/schema/suffixes/events.yaml b/src/schema/suffixes/events.yaml new file mode 100644 index 0000000000..0e53d7d34e --- /dev/null +++ b/src/schema/suffixes/events.yaml @@ -0,0 +1,4 @@ +--- +name: Events +description: | + Event timing information from a behavioral task. diff --git a/src/schema/suffixes/fieldmap.yaml b/src/schema/suffixes/fieldmap.yaml new file mode 100644 index 0000000000..bbce32c57f --- /dev/null +++ b/src/schema/suffixes/fieldmap.yaml @@ -0,0 +1,5 @@ +--- +name: Fieldmap +description: | + Some MR schemes such as spiral-echo imaging (SEI) sequences are able to + directly provide maps of the *B0* field inhomogeneity. diff --git a/src/schema/suffixes/headshape.yaml b/src/schema/suffixes/headshape.yaml new file mode 100644 index 0000000000..f4a53833a9 --- /dev/null +++ b/src/schema/suffixes/headshape.yaml @@ -0,0 +1,5 @@ +--- +name: Headshape File +description: | + The 3-D locations of points that describe the head shape and/or electrode + locations can be digitized and stored in separate files. diff --git a/src/schema/suffixes/ieeg.yaml b/src/schema/suffixes/ieeg.yaml new file mode 100644 index 0000000000..dd670af006 --- /dev/null +++ b/src/schema/suffixes/ieeg.yaml @@ -0,0 +1,4 @@ +--- +name: Intracranial Electroencephalography +description: | + Intracranial electroencephalography recording data. diff --git a/src/schema/suffixes/inplaneT1.yaml b/src/schema/suffixes/inplaneT1.yaml new file mode 100644 index 0000000000..aca7bf2f4f --- /dev/null +++ b/src/schema/suffixes/inplaneT1.yaml @@ -0,0 +1,6 @@ +--- +name: Inplane T1 +description: | + In arbitrary units (arbitrary). + T1 weighted structural image matched to a functional (task) image. +unit: arbitrary diff --git a/src/schema/suffixes/inplaneT2.yaml b/src/schema/suffixes/inplaneT2.yaml new file mode 100644 index 0000000000..8fe58a0bdf --- /dev/null +++ b/src/schema/suffixes/inplaneT2.yaml @@ -0,0 +1,6 @@ +--- +name: Inplane T2 +description: | + In arbitrary units (arbitrary). + T2 weighted structural image matched to a functional (task) image. +unit: arbitrary diff --git a/src/schema/suffixes/m0scan.yaml b/src/schema/suffixes/m0scan.yaml new file mode 100644 index 0000000000..78b04cc145 --- /dev/null +++ b/src/schema/suffixes/m0scan.yaml @@ -0,0 +1,5 @@ +--- +name: M0 image +description: | + The M0 image is a calibration image, used to estimate the equilibrium + magnetization of blood. diff --git a/src/schema/suffixes/magnitude.yaml b/src/schema/suffixes/magnitude.yaml new file mode 100644 index 0000000000..22d5aa6560 --- /dev/null +++ b/src/schema/suffixes/magnitude.yaml @@ -0,0 +1,6 @@ +--- +name: Magnitude +description: | + Field-mapping MR schemes such as gradient-recalled echo (GRE) generate a + Magnitude image to be used for anatomical reference. + Requires the existence of Phase, Phase-difference or Fieldmap maps. diff --git a/src/schema/suffixes/magnitude1.yaml b/src/schema/suffixes/magnitude1.yaml new file mode 100644 index 0000000000..e9787e617f --- /dev/null +++ b/src/schema/suffixes/magnitude1.yaml @@ -0,0 +1,5 @@ +--- +name: Magnitude +description: | + Magnitude map generated by GRE or similar schemes, associated with the first + echo in the sequence. diff --git a/src/schema/suffixes/magnitude2.yaml b/src/schema/suffixes/magnitude2.yaml new file mode 100644 index 0000000000..c4f056ed07 --- /dev/null +++ b/src/schema/suffixes/magnitude2.yaml @@ -0,0 +1,5 @@ +--- +name: Magnitude +description: | + Magnitude map generated by GRE or similar schemes, associated with the second + echo in the sequence. diff --git a/src/schema/suffixes/markers.yaml b/src/schema/suffixes/markers.yaml new file mode 100644 index 0000000000..8ab8dd9fb6 --- /dev/null +++ b/src/schema/suffixes/markers.yaml @@ -0,0 +1,8 @@ +--- +name: MEG Sensor Coil Positions +description: | + Another manufacturer-specific detail pertains to the KIT/Yokogawa/Ricoh + system, which saves the MEG sensor coil positions in a separate file with two + possible filename extensions (`.sqd`, `.mrk`). + For these files, the `markers` suffix MUST be used. + For example: `sub-01_task-nback_markers.sqd` diff --git a/src/schema/suffixes/meg.yaml b/src/schema/suffixes/meg.yaml new file mode 100644 index 0000000000..713d402075 --- /dev/null +++ b/src/schema/suffixes/meg.yaml @@ -0,0 +1,5 @@ +--- +name: Magnetoencephalography +description: | + Unprocessed MEG data stored in the native file format of the MEG instrument + with which the data was collected. diff --git a/src/schema/suffixes/pet.yaml b/src/schema/suffixes/pet.yaml new file mode 100644 index 0000000000..ce4135481a --- /dev/null +++ b/src/schema/suffixes/pet.yaml @@ -0,0 +1,7 @@ +--- +name: Positron Emission Tomography +description: | + PET imaging data SHOULD be stored in 4D + (or 3D, if only one volume was acquired) NIfTI files with the `_pet` suffix. + Volumes MUST be stored in chronological order + (the order they were acquired in). diff --git a/src/schema/suffixes/phase.yaml b/src/schema/suffixes/phase.yaml new file mode 100644 index 0000000000..2c3e17cac8 --- /dev/null +++ b/src/schema/suffixes/phase.yaml @@ -0,0 +1,12 @@ +--- +name: Phase image +description: | + [DEPRECATED](/02-common-principles.html#definitions). + Phase information associated with magnitude information stored in BOLD + contrast. + This suffix should be replaced by the + [`part-phase`](/99-appendices/09-entities.html#part) + in conjunction with the `bold` suffix. +anyOf: + - unit: arbitrary + - unit: rad diff --git a/src/schema/suffixes/phase1.yaml b/src/schema/suffixes/phase1.yaml new file mode 100644 index 0000000000..d0dadf485c --- /dev/null +++ b/src/schema/suffixes/phase1.yaml @@ -0,0 +1,5 @@ +--- +name: Phase +description: | + Phase map generated by GRE or similar schemes, associated with the first + echo in the sequence. diff --git a/src/schema/suffixes/phase2.yaml b/src/schema/suffixes/phase2.yaml new file mode 100644 index 0000000000..757afefca6 --- /dev/null +++ b/src/schema/suffixes/phase2.yaml @@ -0,0 +1,5 @@ +--- +name: Phase +description: | + Phase map generated by GRE or similar schemes, associated with the second + echo in the sequence. diff --git a/src/schema/suffixes/phasediff.yaml b/src/schema/suffixes/phasediff.yaml new file mode 100644 index 0000000000..bf67fa2dfe --- /dev/null +++ b/src/schema/suffixes/phasediff.yaml @@ -0,0 +1,7 @@ +--- +name: Phase-difference +description: | + Some scanners subtract the `phase1` from the `phase2` map and generate a + unique `phasediff` file. + For instance, this is a common output for the built-in fieldmap sequence of + Siemens scanners. diff --git a/src/schema/suffixes/photo.yaml b/src/schema/suffixes/photo.yaml new file mode 100644 index 0000000000..fb715f0ece --- /dev/null +++ b/src/schema/suffixes/photo.yaml @@ -0,0 +1,5 @@ +--- +name: Photo File +description: | + Photos of the anatomical landmarks and/or head localization coils + (`*_photo.jpg`). diff --git a/src/schema/suffixes/physio.yaml b/src/schema/suffixes/physio.yaml new file mode 100644 index 0000000000..971d80d377 --- /dev/null +++ b/src/schema/suffixes/physio.yaml @@ -0,0 +1,4 @@ +--- +name: Physiological recording +description: | + Physiological recordings such as cardiac and respiratory signals. diff --git a/src/schema/suffixes/sbref.yaml b/src/schema/suffixes/sbref.yaml new file mode 100644 index 0000000000..3f209f4f23 --- /dev/null +++ b/src/schema/suffixes/sbref.yaml @@ -0,0 +1,4 @@ +--- +name: Single-band reference image +description: | + Single-band reference for one or more multi-band `dwi` images. diff --git a/src/schema/suffixes/stim.yaml b/src/schema/suffixes/stim.yaml new file mode 100644 index 0000000000..ec1eba6b7f --- /dev/null +++ b/src/schema/suffixes/stim.yaml @@ -0,0 +1,4 @@ +--- +name: Continuous recording +description: | + Continuous measures, such as parameters of a film or audio stimulus. diff --git a/tools/mkdocs_macros_bidsschema/main.py b/tools/mkdocs_macros_bidsschema/main.py index 0809527cc8..7dff369382 100644 --- a/tools/mkdocs_macros_bidsschema/main.py +++ b/tools/mkdocs_macros_bidsschema/main.py @@ -32,13 +32,7 @@ def define_env(env): env.macro(macros.make_entity_table, "MACROS___make_entity_table") env.macro( macros.make_entity_definitions, - "MACROS___make_entity_definitions" + "MACROS___make_entity_definitions", ) - env.macro( - macros.make_metadata_table, - "MACROS___make_metadata_table" - ) - - @env.macro - def make_suffix_table(suffixes): - return None + env.macro(macros.make_suffix_table, "MACROS___make_suffix_table") + env.macro(macros.make_metadata_table, "MACROS___make_metadata_table") diff --git a/tools/schemacode/macros.py b/tools/schemacode/macros.py index 2e04b95479..1ad31bcfce 100644 --- a/tools/schemacode/macros.py +++ b/tools/schemacode/macros.py @@ -63,6 +63,26 @@ def make_entity_definitions(): return text +def make_suffix_table(suffixes): + """Generate a markdown table of suffix information. + + Parameters + ---------- + suffixes : list of str + A list of the suffixes to include in the table. + + Returns + ------- + table : str + A Markdown-format table containing the corresponding table for + the requested fields. + """ + schemapath = utils.get_schema_path() + schema_obj = schema.load_schema(schemapath) + table = schema.make_suffix_table(schema_obj, suffixes) + return table + + def make_metadata_table(field_info): """Generate a markdown table of metadata field information. diff --git a/tools/schemacode/schema.py b/tools/schemacode/schema.py index 5e64e204c3..02ff9a16f2 100755 --- a/tools/schemacode/schema.py +++ b/tools/schemacode/schema.py @@ -367,6 +367,57 @@ def make_entity_table(schema, tablefmt="github", **kwargs): return table_str +def make_suffix_table(schema, suffixes, tablefmt="github"): + """Produce suffix table (markdown) based on requested suffixes. + Parameters + ---------- + schema : dict + suffixes : list of str + tablefmt : str + Returns + ------- + table_str : str + Tabulated table as a string. + """ + # The filter function doesn't work here. + suffix_schema = schema["suffixes"] + + suffixes_found = [f for f in suffixes if f in suffix_schema.keys()] + suffixes_not_found = [f for f in suffixes if f not in suffix_schema.keys()] + if suffixes_not_found: + raise Exception( + "Warning: Missing suffixes: {}".format( + ", ".join(suffixes_not_found) + ) + ) + + df = pd.DataFrame( + index=suffixes_found, + columns=["**Name**", "**Description**"], + ) + # Index by suffix because name cannot be assumed to be unique + df.index.name = "`suffix`" + for suffix in suffixes_found: + suffix_info = suffix_schema[suffix] + description = suffix_info["description"] + # A backslash before a newline means continue a string + description = description.replace("\\\n", "") + # Two newlines should be respected + description = description.replace("\n\n", "
") + # Otherwise a newline corresponds to a space + description = description.replace("\n", " ") + + df.loc[suffix] = [suffix_info["name"], description] + + df = df.reset_index(drop=False) + df = df.set_index("**Name**") + df = df[["`suffix`", "**Description**"]] + + # Print it as markdown + table_str = tabulate(df, headers="keys", tablefmt=tablefmt) + return table_str + + def _get_link(string): refs = { "array": "https://www.w3schools.com/js/js_json_arrays.asp",