[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"

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

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

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:

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