[ENH] Add coil entity for uncombined MR data

src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

@@ -32,6 +32,7 @@ and a guide for using macros can be found at
          "RECOMMENDED",
          "See an example below the table.",
       ),
+      "CoilString": "RECOMMENDED",
       "GradientSetType": "RECOMMENDED",
       "MRTransmitCoilSequence": "RECOMMENDED",
       "MatrixCoilMode": "RECOMMENDED",
@@ -319,6 +320,12 @@ sequences using different contrast enhanced images. The label is the name of the
 contrast agent. The key `ContrastBolusIngredient` MAY be also be added in the
 JSON file, with the same label.
 
+The OPTIONAL [`coil-<label>`](../99-appendices/09-entities.md#coil) key/value can be used to distinguish coil-specific data.
+Typically it is used for sequences not employing coil combination (for example, SWI).
+When the file contains data from a single coil, `coil-<label>` SHOULD be provided.
+The key `CoilString` MAY also be added in the JSON file, with a corresponding
+identifier for the coil.
+
 Some meta information about the acquisition MAY be provided in an additional
 JSON file. See [Common metadata fields](#common-metadata-fields) for a
 list of terms and their definitions. There are also some OPTIONAL JSON
@@ -529,6 +536,11 @@ reconstruction algorithms (for example ones using motion correction).
 See [`fmap` Case 4](01-magnetic-resonance-imaging-data.md#case-4-multiple-phase-encoded-directions-pepolar)
 for more information on `dir` field specification.
 
+Similarly the OPTIONAL [`coil-<label>`](../99-appendices/09-entities.md#coil) key/value can be used to distinguish
+coil-specific data from sequences not employing coil combination.
+The key `CoilString` MAY also be added in the JSON file, with a corresponding
+coil identifier.
+
 Multi-echo data MUST be split into one file per echo using the
 [`echo-<index>`](../99-appendices/09-entities.md#echo) entity. For example:
 

src/schema/metadata/CoilString.yaml

@@ -0,0 +1,17 @@
+---
+name: CoilString
+description: |
+  Information describing the selected element of the receiver coil for channel-level data.
+  This doesn’t correspond to a tag in the DICOM ontology.
+  The vendor-defined identifier for individual channels can go in this field.
+  As an example, for Siemens, while coil channels are typically not activated/selected
+  individually, data from individual channels may be reconstructed separately.
+  The DICOM files containing the combined data will have a `CoilString` entry matching the
+  terminology of `ReceiveCoilActiveElements` (for example, `"HEA;HEP"` for the Siemens standard
+  32-channel coil when both the anterior and posterior groups are activated),
+  while the DICOM files containing channel-level data will have a `CoilString` entry with a
+  unique identifier for the channel (for example, `"H1-H32"` for the Siemens standard 32-channel
+  coil when both the anterior and posterior groups are activated).
+  This is a flexible field that can be used as most appropriate for a given vendor and coil to
+  define the reconstructed channel.
+type: string

src/schema/objects/entities.yaml

@@ -55,6 +55,17 @@ chunk:
     different fields of view acquired in the same imaging experiment.
   type: string
   format: index
+coil:
+  name: coil
+  display_name: Coil
+  description: |
+    The `coil-<label>` key/value pair can be used to distinguish coil-specific data.
+    Typically it is used for sequences not employing coil combination (for example, SWI).
+    When the file contains data from a single coil, `coil-<label>` SHOULD be provided.
+    The key `"CoilString"` MAY also be added in the JSON file, with a
+    corresponding identifier for the coil.
+  type: string
+  format: label
 density:
   name: den
   display_name: Density

src/schema/rules/datatypes/anat.yaml

@@ -27,6 +27,7 @@ nonparametric:
     ceagent: optional
     reconstruction: optional
     part: optional
+    coil: optional
 
 parametric:
   suffixes:

src/schema/rules/datatypes/func.yaml

@@ -21,6 +21,7 @@ func:
     run: optional
     echo: optional
     part: optional
+    coil: optional
 
 phase:
   suffixes:

src/schema/rules/entities.yaml

@@ -18,6 +18,7 @@
 - inversion
 - mtransfer
 - part
+- coil
 - processing
 - hemisphere
 - space