From a3e3d25c02ded298d1c009e133e882486176256b Mon Sep 17 00:00:00 2001 From: Chris Markiewicz Date: Tue, 2 May 2023 07:52:43 -0400 Subject: [PATCH 1/7] ENH: Define a channel column for events --- src/schema/objects/columns.yaml | 8 ++++++++ src/schema/rules/tabular_data/task.yaml | 5 +++++ 2 files changed, 13 insertions(+) diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml index 89d28a5f09..77d997e071 100644 --- a/src/schema/objects/columns.yaml +++ b/src/schema/objects/columns.yaml @@ -48,6 +48,14 @@ 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, separate with commas (`,`) or a + delimiter specified in the `"Delimiter"` field describing the `channel` + column. color: name: color display_name: Color label 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 From ab0e6a9f8d5b6078ea6f597535bcd906f0af5c84 Mon Sep 17 00:00:00 2001 From: Chris Markiewicz Date: Tue, 2 May 2023 07:53:20 -0400 Subject: [PATCH 2/7] ENH: Define a Delimiter field for column descriptions --- src/common-principles.md | 1 + src/schema/objects/columns.yaml | 1 + src/schema/objects/metadata.yaml | 7 +++++++ 3 files changed, 9 insertions(+) diff --git a/src/common-principles.md b/src/common-principles.md index 2dc9905d9a..997fb8b275 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/schema/objects/columns.yaml b/src/schema/objects/columns.yaml index 77d997e071..c6d5478533 100644 --- a/src/schema/objects/columns.yaml +++ b/src/schema/objects/columns.yaml @@ -56,6 +56,7 @@ channel: If multiple channels are specified, separate with commas (`,`) or a delimiter specified in the `"Delimiter"` field describing the `channel` column. + type: string color: name: color display_name: Color label diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml index d0fa480198..53bcbe205e 100644 --- a/src/schema/objects/metadata.yaml +++ b/src/schema/objects/metadata.yaml @@ -570,6 +570,13 @@ DelayTime: This field is mutually exclusive with `"VolumeTiming"`. type: number unit: s +Delimiter: + name: Delimiter + display_name: Delimiter + description: | + If a column may be interpreted as a list of values, the character that + separates one value from the next. + type: string Density: name: Density display_name: Density From df07a154e0cc70484b9a9d38ef0436b59e4123da Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Thu, 26 Oct 2023 15:09:23 +0200 Subject: [PATCH 3/7] be clear that not the column is a list of values, but each row in that column --- src/schema/objects/metadata.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml index 53bcbe205e..bf3428b164 100644 --- a/src/schema/objects/metadata.yaml +++ b/src/schema/objects/metadata.yaml @@ -574,7 +574,7 @@ Delimiter: name: Delimiter display_name: Delimiter description: | - If a column may be interpreted as a list of values, the character that + 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: From 8a88eaf443f32fb64f5ea12be992e9c2ceb29fd1 Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Thu, 26 Oct 2023 15:30:17 +0200 Subject: [PATCH 4/7] extend example in events spec to include delimiters --- src/modality-specific-files/task-events.md | 48 ++++++++++++++++------ 1 file changed, 36 insertions(+), 12 deletions(-) diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md index 0b56967fd1..d4ddb2a1e5 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 artifact +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 sweat ``` In the accompanying JSON sidecar, the `trial_type` column might look as follows: @@ -98,12 +99,42 @@ 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": "|" + }, + "artifact": { + "Description": "Description of an 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 non-default delimiter (that is, *not* with a comma `,`). + See the `Delimiter` field in the accompanying JSON sidecar. + 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 `artifact`. + 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. + Note that in practice, such a hypothetical `artifact` column should make + 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 +156,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` From e64314b5cdcf7b18fe63c918777037dc5c1a4985 Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Mon, 6 Nov 2023 16:35:48 +0100 Subject: [PATCH 5/7] use HED in example --- src/modality-specific-files/task-events.md | 23 ++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md index d4ddb2a1e5..8c899a8157 100644 --- a/src/modality-specific-files/task-events.md +++ b/src/modality-specific-files/task-events.md @@ -82,10 +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 channel artifact +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 sweat +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: @@ -104,8 +104,15 @@ In the accompanying JSON sidecar, the `trial_type` column might look as follows: "Description": "Channel(s) associated with the event", "Delimiter": "|" }, - "artifact": { - "Description": "Description of an artifact." + "annots": { + "LongName": "Annotations", + "Description": "Hierarchical Event Descriptors (HED) annotations", + "Levels": { + "musc": "Muscle artifact. A very common, high frequency, sharp artifact that corresponds with agitation/nervousness in a patient." + }, + "HED": { + "musc": "EMG-artifact" + } } } ``` @@ -116,17 +123,17 @@ Note that in the example above: 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 non-default delimiter (that is, *not* with a comma `,`). - See the `Delimiter` field in the accompanying JSON sidecar. + 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 `artifact`. +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. - Note that in practice, such a hypothetical `artifact` column should make + 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 From d1056c15cfefda08f2d3d6d8006c4490f0577766 Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Mon, 6 Nov 2023 16:57:51 +0100 Subject: [PATCH 6/7] Update src/schema/objects/columns.yaml Co-authored-by: Chris Markiewicz --- src/schema/objects/columns.yaml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml index c6d5478533..2f987c97c1 100644 --- a/src/schema/objects/columns.yaml +++ b/src/schema/objects/columns.yaml @@ -53,9 +53,12 @@ channel: display_name: Channel description: | Channel(s) associated with an event. - If multiple channels are specified, separate with commas (`,`) or a - delimiter specified in the `"Delimiter"` field describing the `channel` - column. + 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 From 2a12171213016cee3d86d6aad8a1202defd6ab20 Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Mon, 13 Nov 2023 15:12:10 +0100 Subject: [PATCH 7/7] Update src/modality-specific-files/task-events.md --- src/modality-specific-files/task-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md index 8c899a8157..0fb6ec2a52 100644 --- a/src/modality-specific-files/task-events.md +++ b/src/modality-specific-files/task-events.md @@ -106,7 +106,7 @@ In the accompanying JSON sidecar, the `trial_type` column might look as follows: }, "annots": { "LongName": "Annotations", - "Description": "Hierarchical Event Descriptors (HED) 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." },