From 7241c2b24669488f56a800d532270e3611233d55 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Mon, 12 Aug 2024 12:34:44 +1000
Subject: [PATCH] MRI: DWI scanner derivatives: Adopt "S0map" suffix

---
 .../magnetic-resonance-imaging-data.md                 | 10 ++++++----
 src/schema/objects/suffixes.yaml                       |  9 ++++++++-
 src/schema/rules/files/raw/dwi.yaml                    |  1 +
 3 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-imaging-data.md b/src/modality-specific-files/magnetic-resonance-imaging-data.md
index 8f2c44429b..ba4161e050 100644
--- a/src/modality-specific-files/magnetic-resonance-imaging-data.md
+++ b/src/modality-specific-files/magnetic-resonance-imaging-data.md
@@ -671,7 +671,7 @@ The definitions of these fields can be found in
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_suffix_table(["ADC", "expADC", "trace", "FA", "colFA"]) }}
+{{ MACROS___make_suffix_table(["ADC", "expADC", "trace", "FA", "colFA", "S0"]) }}
 
 <!--
 This block generates a filename templates.
@@ -700,9 +700,11 @@ In such a case, two files could have the following names:
 The user is free to choose any other label than `singleband` and
 `multiband`, as long as they are consistent across subjects and sessions.
 
-Scanner-generated trace-weighted, ADC, exponentiated ADC, and fractional anisotropy (FA and colFA) volumes
-MAY be included using the `trace`, `ADC`, `expADC`, `FA` and `colFA` suffixes, respectively.
-If trace, ADC, expADC, FA, or colFA volume filenames match a diffusion series with all applicable entities,
+Scanner-generated derivative images,
+such as trace-weighted, ADC, exponentiated ADC,
+fractional anisotropy (FA and colFA), and estimated unweighted signal intensity,
+MAY be included using the `trace`, `ADC`, `expADC`, `FA`, `colFA` and `S0` suffixes, respectively.
+If trace, ADC, expADC, FA, colFA, or S0 volume filenames match a diffusion series with all applicable entities,
 such volumes SHOULD have been computed from that series.
 Otherwise, some entity, such as [`acq-<label>`](../appendices/entities.md#acq),
 SHOULD be used to indicate that the files are unrelated.
diff --git a/src/schema/objects/suffixes.yaml b/src/schema/objects/suffixes.yaml
index 68bd39baba..f11740b65b 100644
--- a/src/schema/objects/suffixes.yaml
+++ b/src/schema/objects/suffixes.yaml
@@ -292,9 +292,11 @@ RB1map:
   unit: arbitrary
 S0map:
   value: S0map
-  display_name: Observed signal amplitude (S0) image
+  display_name: Projected baseline signal amplitude (S0) image
   description: |
     In arbitrary units (arbitrary).
+    This represents a model-based estimate of signal intensity
+    in the absence of the contrast under investigation.
     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
@@ -302,6 +304,11 @@ S0map:
     [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.
+    For a diffusion-weighted sequence,
+    S0 maps represent the model-based estimate of the signal intensity
+    in the absence of any diffusion weighting;
+    in other words, the image intensity at *b*=0
+    as estimated by a diffusion model fit.
 SEM:
   value: SEM
   display_name: Scanning electron microscopy
diff --git a/src/schema/rules/files/raw/dwi.yaml b/src/schema/rules/files/raw/dwi.yaml
index 3afa08ce1e..91319046dc 100644
--- a/src/schema/rules/files/raw/dwi.yaml
+++ b/src/schema/rules/files/raw/dwi.yaml
@@ -44,6 +44,7 @@ ScannerDerivatives:
   suffixes:
     - ADC
     - FA
+    - S0map
     - colFA
     - expADC
     - trace