diff --git a/src/common-principles.md b/src/common-principles.md index 83d0b0e2c4..d3ff223dcb 100644 --- a/src/common-principles.md +++ b/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", } diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md index 0b56967fd1..0fb6ec2a52 100644 --- a/src/modality-specific-files/task-events.md +++ b/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` diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml index 5bb4b84a53..ba9f86ba31 100644 --- a/src/schema/objects/columns.yaml +++ b/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 diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml index 6de0e31e37..7e85b4ac75 100644 --- a/src/schema/objects/metadata.yaml +++ b/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 diff --git a/src/schema/rules/tabular_data/task.yaml b/src/schema/rules/tabular_data/task.yaml index 1b07b24936..0ca01afe25 100644 --- a/src/schema/rules/tabular_data/task.yaml +++ b/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