ENH: Define channel column for events and Delimiter field for column descriptions (#1483)

* ENH: Define a channel column for events

* ENH: Define a Delimiter field for column descriptions

* be clear that not the column is a list of values, but each row in that column

* extend example in events spec to include delimiters

* use HED in example

* Update src/schema/objects/columns.yaml

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/modality-specific-files/task-events.md

---------

Co-authored-by: Stefan Appelhoff <[email protected]>

Author: effigies

src/common-principles.md

@@ -483,6 +483,7 @@ and a guide for using macros can be found at
         ),
         "Levels": "RECOMMENDED",
         "Units": "RECOMMENDED",
+        "Delimiter": "OPTIONAL",
         "TermURL": "RECOMMENDED",
         "HED": "OPTIONAL",
    }

src/modality-specific-files/task-events.md

@@ -82,9 +82,10 @@ A guide for using macros can be found at
 Example of the content of the TSV file:
 
 ```Text
-onset	duration	trial_type	response_time	stim_file
-1.23	0.65	start	1.435	images/red_square.jpg
-5.65	0.65	stop	1.739	images/blue_square.jpg
+onset	duration	trial_type	response_time	stim_file	channel	annots
+1.23	0.65	start	1.435	images/red_square.jpg	n/a	n/a
+5.65	0.65	stop	1.739	images/blue_square.jpg	n/a	n/a
+12.1	2.35	n/a	n/a	n/a	F,1|F,2|Cz	musc
 ```
 
 In the accompanying JSON sidecar, the `trial_type` column might look as follows:
@@ -98,12 +99,49 @@ In the accompanying JSON sidecar, the `trial_type` column might look as follows:
             "start": "A red square is displayed to indicate starting",
             "stop": "A blue square is displayed to indicate stopping"
         }
+    },
+    "channel": {
+        "Description": "Channel(s) associated with the event",
+        "Delimiter": "|"
+    },
+    "annots": {
+        "LongName": "Annotations",
+        "Description": "Annotations associated with channels indicated in the channel column.",
+        "Levels": {
+            "musc": "Muscle artifact. A very common, high frequency, sharp artifact that corresponds with agitation/nervousness in a patient."
+        },
+        "HED": {
+            "musc": "EMG-artifact"
+        }
     }
 }
 ```
 
-Note that all other columns SHOULD also be described but are omitted for the
-sake of brevity.
+Note that in the example above:
+
+1.  Only a subset of columns are described for the sake of brevity.
+    In a real dataset, all other columns SHOULD also be described.
+
+1.  The `channel` column contains a list of values that are separated
+    by a delimiter (`|`), as is declared in the `Delimiter` metadata
+    field of the `events.json file.
+    Thus, the channels related to the event in the third row of the example
+    are called `F,1`, `F,2`, and `Cz`.
+
+1.  The example contains a column called `annots`.
+    This column is not defined in BIDS, and constitutes additional, arbitrary
+    (that is, unofficial) metadata.
+    In the present case, it is used to describe artifacts in the data,
+    in reference to the `channel` column.
+    The `annots` column is making
+    use of the powerful HED system for documenting events, see below.
+
+Events MAY also be documented in machine-actionable form
+using HED (Hierarchical Event Descriptor) tags.
+This type of documentation is particularly useful for datasets likely to be used
+in event-related analyses.
+See [Hierarchical Event Descriptors](../appendices/hed.md)
+for additional information and examples.
 
 For multi-echo files, the `events.tsv` file is applicable to all echos of
 a particular run:
@@ -125,13 +163,6 @@ A guide for using macros can be found at
    }
 ) }}
 
-Note: Events can also be documented in machine-actionable form
-using HED (Hierarchical Event Descriptor) tags.
-This type of documentation is particularly useful for datasets likely to be used
-in event-related analyses.
-See [Hierarchical Event Descriptors](../appendices/hed.md)
-for additional information and examples.
-
 ## Stimuli
 
 Additional information about the stimuli can be added in the `events.tsv`

src/schema/objects/columns.yaml

@@ -48,6 +48,18 @@ cardiac:
   description: |
     continuous pulse measurement
   type: number
+channel:
+  name: channel
+  display_name: Channel
+  description: |
+    Channel(s) associated with an event.
+    If multiple channels are specified, they MUST be separated by a delimiter
+    specified in the `"Delimiter"` field describing the `channel` column.
+    For example, channels separated with a comma (`,`) require the `events.json`
+    file to contain `"channel": {"Delimiter": ","}`.
+    In the absence of a delimiter, tools MUST interpret any character as being part
+    of a channel name.
+  type: string
 color:
   name: color
   display_name: Color label

src/schema/objects/metadata.yaml

@@ -572,6 +572,13 @@ DelayTime:
     This field is mutually exclusive with `"VolumeTiming"`.
   type: number
   unit: s
+Delimiter:
+  name: Delimiter
+  display_name: Delimiter
+  description: |
+    If rows in a column may be interpreted as a lists of values, the character that
+    separates one value from the next.
+  type: string
 Density:
   name: Density
   display_name: Density

src/schema/rules/tabular_data/task.yaml

@@ -10,6 +10,11 @@ TaskEvents:
     response_time: optional
     HED: optional
     stim_file: optional
+    channel:
+      level: optional
+      description_addendum: |
+        Note that this column only applies to data types where
+        channels are specified, such as EEG, iEEG, MEG or NIRS.
   additional_columns: allowed
   initial_columns:
     - onset