From 8692e1fd12c82201eb63ae8a7098f3a77a4ee1bc Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Thu, 3 Oct 2024 04:15:10 +1000
Subject: [PATCH] [ENH] Update DWI suffixes to include most common scanner
 derivatives (#1864)

---
 .../magnetic-resonance-imaging-data.md        | 28 ++++++++---
 src/schema/objects/suffixes.yaml              | 46 +++++++++++++++++--
 src/schema/rules/files/deriv/imaging.yaml     |  9 ++++
 src/schema/rules/files/raw/dwi.yaml           | 24 ++++++++++
 4 files changed, 97 insertions(+), 10 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-imaging-data.md b/src/modality-specific-files/magnetic-resonance-imaging-data.md
index 73a0b1c13f..2b2078fe04 100644
--- a/src/modality-specific-files/magnetic-resonance-imaging-data.md
+++ b/src/modality-specific-files/magnetic-resonance-imaging-data.md
@@ -685,13 +685,18 @@ 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(
-      [
-         "dwi",
-         "sbref",
-      ]
-   )
-}}
+{{ MACROS___make_suffix_table(["dwi", "sbref"]) }}
+
+Additionally, the following suffixes are used for scanner-generated images:
+
+<!--
+This block generates a suffix table.
+The definitions of these fields can be found in
+  src/schema/rules/files/raw
+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", "S0map"]) }}
 
 <!--
 This block generates a filename templates.
@@ -720,6 +725,15 @@ 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 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 `S0map` 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.
+
 ### REQUIRED gradient orientation information
 
 The REQUIRED gradient orientation information corresponding to a DWI acquisition
diff --git a/src/schema/objects/suffixes.yaml b/src/schema/objects/suffixes.yaml
index 91589b62ff..1e2825ced2 100644
--- a/src/schema/objects/suffixes.yaml
+++ b/src/schema/objects/suffixes.yaml
@@ -6,6 +6,11 @@ TwoPE:
   display_name: 2-photon excitation microscopy
   description: |
     2-photon excitation microscopy imaging data
+ADC:
+  value: ADC
+  display_name: Apparent diffusion coefficient (ADC)
+  description:
+    Apparent diffusion coefficient (ADC) map
 BF:
   value: BF
   display_name: Bright-field microscopy
@@ -42,6 +47,12 @@ DF:
   display_name: Dark-field microscopy
   description: |
     Dark-field microscopy imaging data
+FA:
+  value: FA
+  display_name: Fractional Anisotropy image
+  description: |
+    Scanner-generated derivative parametric map
+    reflecting the anisotropy of the diffusion tensor
 FLAIR:
   value: FLAIR
   display_name: Fluid attenuated inversion recovery image
@@ -281,16 +292,25 @@ 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).
-    For a multi-echo (typically fMRI) sequence, S0 maps index the baseline signal
-    before exponential (T2-star) signal decay.
+    This represents a model-based estimate of signal intensity
+    in the absence of the contrast under investigation.
+    For a multi-echo sequence
+    (for example, multi-echo spin echo T2 relaxometry or multi-echo fMRI),
+    S0 maps index the baseline signal at a hypothetical echo time of zero
+    (that is, in the absence of any T2 or T2-star 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.
+    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
@@ -537,6 +557,15 @@ channels:
   display_name: Channels File
   description: |
     Channel information.
+colFA:
+  value: colFA
+  display_name: Colored Fractional Anisotropy image
+  description: |
+    Scanner-derived parametric map encoding both the anisotropy and principal direction of the diffusion tensor.
+    Image intensity is proportional to the Fractional Anisotropy (FA) measure;
+    image color is determined by the principal eigenvector of the diffusion tensor,
+    where red encodes the magnitude of the left-right component of that orientation,
+    with green and blue similarly encoding the anterior-posterior and inferior-superior components respectively.
 coordsystem:
   value: coordsystem
   display_name: Coordinate System File
@@ -595,6 +624,12 @@ events:
   display_name: Events
   description: |
     Event timing information from a behavioral task.
+expADC:
+  value: expADC
+  display_name: Exponental ADC
+  description: |
+    Exponental ADC / Attenuation Coefficient / Attenuation Factor map,
+    as the ratio of trace-weighted to non-diffusion-weighted image intensity
 fieldmap:
   value: fieldmap
   display_name: Fieldmap
@@ -826,6 +861,11 @@ svs:
   display_name: Single-voxel spectroscopy
   description: |
     MRS acquisitions where the detected MR signal is spatially localized to a single volume.
+trace:
+  value: trace
+  display_name: Trace-weighted diffusion image
+  description: |
+    Trace-weighted image, as the mean intensity of diffusion-weighted images
 uCT:
   value: uCT
   display_name: Micro-CT
diff --git a/src/schema/rules/files/deriv/imaging.yaml b/src/schema/rules/files/deriv/imaging.yaml
index e037dcc10c..07f7678115 100644
--- a/src/schema/rules/files/deriv/imaging.yaml
+++ b/src/schema/rules/files/deriv/imaging.yaml
@@ -26,6 +26,15 @@ dwi_volumetric:
     density: optional
     description: optional
 
+dwi_scannerderivatives:
+  $ref: rules.files.raw.dwi.ScannerDerivatives
+  entities:
+    $ref: rules.files.raw.dwi.ScannerDerivatives.entities
+    space: optional
+    resolution: optional
+    density: optional
+    description: optional
+
 func_volumetric:
   $ref: rules.files.raw.func.func
   entities:
diff --git a/src/schema/rules/files/raw/dwi.yaml b/src/schema/rules/files/raw/dwi.yaml
index 22b224b023..91319046dc 100644
--- a/src/schema/rules/files/raw/dwi.yaml
+++ b/src/schema/rules/files/raw/dwi.yaml
@@ -38,3 +38,27 @@ sbref:
     run: optional
     part: optional
     chunk: optional
+
+# Common scanner-generated derivatives need raw names
+ScannerDerivatives:
+  suffixes:
+    - ADC
+    - FA
+    - S0map
+    - colFA
+    - expADC
+    - trace
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - dwi
+  entities:
+    subject: required
+    session: optional
+    acquisition: optional
+    reconstruction: optional
+    direction: optional
+    run: optional
+    chunk: optional