From 04a96f5412f61fb1f90b4dfea23cb033242bcf0f Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Thu, 27 Jun 2024 13:13:11 +1000
Subject: [PATCH] Changes to scanner-generated DWI derivatives

- Rename "TRACE" suffix to "trace".
- Add "exponentiated ADC" measure.
- Fix description of trace-weighted image, resolving #1862.
- Modify descriptions of FA and colFA.
- Fix alphabetic sorting of suffices.
---
 .../magnetic-resonance-imaging-data.md        | 10 +++---
 src/schema/objects/suffixes.yaml              | 35 ++++++++++++-------
 src/schema/rules/files/raw/dwi.yaml           |  5 +--
 3 files changed, 30 insertions(+), 20 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-imaging-data.md b/src/modality-specific-files/magnetic-resonance-imaging-data.md
index a173acbfdc..1961785f6c 100644
--- a/src/modality-specific-files/magnetic-resonance-imaging-data.md
+++ b/src/modality-specific-files/magnetic-resonance-imaging-data.md
@@ -667,7 +667,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", "TRACE", "FA", "colFA"]) }}
+{{ MACROS___make_suffix_table(["ADC", "expADC", "trace", "FA", "colFA"]) }}
 
 <!--
 This block generates a filename templates.
@@ -696,10 +696,10 @@ 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, ADC and fractional anisotropy (FA and colFA) volumes MAY be included
-using the `TRACE`, `ADC`, `FA` and `colFA` suffixes, respectively.
-If TRACE, ADC, FA, or colFA volume filenames match a diffusion series with all applicable entities,
-such volumes SHOULD be computed from that series.
+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,
+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 5bc30ce9bb..afef8b593b 100644
--- a/src/schema/objects/suffixes.yaml
+++ b/src/schema/objects/suffixes.yaml
@@ -42,13 +42,6 @@ DIC:
   display_name: Differential interference contrast microscopy
   description: |
     Differential interference contrast microscopy imaging data
-colFA:
-  value: colFA
-  display_name: Colored Fractional Anisotropy image
-  description: |
-    Diffusion images reflecting the directionality of the diffusion tensor color-coded in red for
-    left-right oriented fibers, in blue for superior-inferior oriented fibers and green for
-    anterior-posterior oriented fibers.
 DF:
   value: DF
   display_name: Dark-field microscopy
@@ -58,7 +51,8 @@ FA:
   value: FA
   display_name: Fractional Anisotropy image
   description: |
-    Diffusion images reflecting the directionality of the diffusion tensor
+    Scanner-generated derivative parametric map
+    reflecting the anisotropy of the diffusion tensor
 FLAIR:
   value: FLAIR
   display_name: Fluid attenuated inversion recovery image
@@ -477,11 +471,6 @@ TEM:
   display_name: Transmission electron microscopy
   description: |
     Transmission electron microscopy imaging data
-TRACE:
-  value: TRACE
-  display_name: Trace diffusion weighted image
-  description: |
-    Diffusion images proportional to the trace of the diffusion tensor
 UNIT1:
   value: UNIT1
   display_name: Homogeneous (flat) T1-weighted MP2RAGE image
@@ -559,6 +548,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 colour 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
@@ -617,6 +615,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
@@ -831,6 +835,11 @@ stim:
   display_name: Continuous recording
   description: |
     Continuous measures, such as parameters of a film or audio stimulus.
+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/raw/dwi.yaml b/src/schema/rules/files/raw/dwi.yaml
index 987206718b..3afa08ce1e 100644
--- a/src/schema/rules/files/raw/dwi.yaml
+++ b/src/schema/rules/files/raw/dwi.yaml
@@ -43,9 +43,10 @@ sbref:
 ScannerDerivatives:
   suffixes:
     - ADC
-    - colFA
     - FA
-    - TRACE
+    - colFA
+    - expADC
+    - trace
   extensions:
     - .nii.gz
     - .nii