From 1d929e587775fa09489f95c94ffc0470b76020eb Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Wed, 22 May 2024 13:13:17 -0400
Subject: [PATCH] [ENH] Specify the naming of scanner-generated TRACE and ADC
 volumes (#1725)

* feat(schema): Define ADC/TRACE suffixes

* feat(schema): Add isotropic DWI volumes

* feat(spec): Specify the naming of scanner-generated TRACE and ADC volumes

* feat(schema): Add derivative rule for TRACE/ADC

* clarity: Split raw and scanner-derivative suffix tables

* Update wording to avoid confusion about "derivatives"
---
 .../magnetic-resonance-imaging-data.md        | 26 ++++++++++++++-----
 src/schema/objects/suffixes.yaml              | 10 +++++++
 src/schema/rules/files/deriv/imaging.yaml     |  9 +++++++
 src/schema/rules/files/raw/dwi.yaml           | 20 ++++++++++++++
 4 files changed, 58 insertions(+), 7 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-imaging-data.md b/src/modality-specific-files/magnetic-resonance-imaging-data.md
index 9a17c36686..6396aa0e8c 100644
--- a/src/modality-specific-files/magnetic-resonance-imaging-data.md
+++ b/src/modality-specific-files/magnetic-resonance-imaging-data.md
@@ -656,13 +656,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", "TRACE"]) }}
 
 <!--
 This block generates a filename templates.
@@ -691,6 +696,13 @@ 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 and ADC volumes MAY be included using the
+`TRACE` and `ADC` suffixes.
+If TRACE or ADC volume filenames match a diffusion series with all applicable entities,
+such volumes SHOULD be 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 06bceb83de..5f57b28ba8 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
@@ -460,6 +465,11 @@ 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
diff --git a/src/schema/rules/files/deriv/imaging.yaml b/src/schema/rules/files/deriv/imaging.yaml
index e037dcc10c..c9a0e12877 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_isotropic:
+  $ref: rules.files.raw.dwi.isotropic
+  entities:
+    $ref: rules.files.raw.dwi.isotropic.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..ff18501af9 100644
--- a/src/schema/rules/files/raw/dwi.yaml
+++ b/src/schema/rules/files/raw/dwi.yaml
@@ -38,3 +38,23 @@ sbref:
     run: optional
     part: optional
     chunk: optional
+
+# Common scanner-generated derivatives need raw names
+isotropic:
+  suffixes:
+    - ADC
+    - TRACE
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - dwi
+  entities:
+    subject: required
+    session: optional
+    acquisition: optional
+    reconstruction: optional
+    direction: optional
+    run: optional
+    chunk: optional