[ENH] Update DWI suffixes to include most common scanner derivatives

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", "TRACE"]) }}
+{{ MACROS___make_suffix_table(["ADC", "expADC", "trace", "FA", "colFA", "S0map"]) }}
 
 <!--
 This block generates a filename templates.
@@ -700,10 +700,12 @@ 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.
+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.
 

src/schema/objects/suffixes.yaml

@@ -47,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
@@ -286,16 +292,23 @@ 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
     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
@@ -465,11 +478,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
@@ -547,6 +555,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
@@ -605,6 +622,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
@@ -819,6 +842,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

src/schema/rules/files/deriv/imaging.yaml

@@ -26,10 +26,10 @@ dwi_volumetric:
     density: optional
     description: optional
 
-dwi_isotropic:
-  $ref: rules.files.raw.dwi.isotropic
+dwi_scannerderivatives:
+  $ref: rules.files.raw.dwi.ScannerDerivatives
   entities:
-    $ref: rules.files.raw.dwi.isotropic.entities
+    $ref: rules.files.raw.dwi.ScannerDerivatives.entities
     space: optional
     resolution: optional
     density: optional

src/schema/rules/files/raw/dwi.yaml

@@ -40,10 +40,14 @@ sbref:
     chunk: optional
 
 # Common scanner-generated derivatives need raw names
-isotropic:
+ScannerDerivatives:
   suffixes:
     - ADC
-    - TRACE
+    - FA
+    - S0map
+    - colFA
+    - expADC
+    - trace
   extensions:
     - .nii.gz
     - .nii