From f47f229265865eaa5c8cc3987b4d8d995bf5686a Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Mon, 28 Dec 2020 11:30:39 +0100 Subject: [PATCH 01/25] create a separate section for stimuli --- .../05-task-events.md | 27 ++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/src/04-modality-specific-files/05-task-events.md b/src/04-modality-specific-files/05-task-events.md index 5285d5594f..35d0f1ad84 100644 --- a/src/04-modality-specific-files/05-task-events.md +++ b/src/04-modality-specific-files/05-task-events.md @@ -40,7 +40,7 @@ and OPTIONAL columns: | sample | OPTIONAL | Onset of the event according to the sampling scheme of the recorded modality (that is, referring to the raw data file that the `events.tsv` file accompanies). | | trial_type | OPTIONAL | Primary categorisation of each trial to identify them as instances of the experimental conditions. For example: for a response inhibition task, it could take on values "go" and "no-go" to refer to response initiation and response inhibition experimental conditions. | | response_time | OPTIONAL | Response time measured in seconds. A negative response time can be used to represent preemptive responses and "n/a" denotes a missed response. | -| stim_file | OPTIONAL | Represents the location of the stimulus file (such as an image, video, or audio file) presented at the given onset time. There are no restrictions on the file formats of the stimuli files, but they should be stored in the /stimuli folder (under the root folder of the dataset; with optional subfolders). The values under the stim_file column correspond to a path relative to "/stimuli". For example "images/cat03.jpg" will be translated to "/stimuli/images/cat03.jpg". | +| value | OPTIONAL | ???? | Marker value associated with the event (for example, the value of a TTL trigger that was recorded at the onset of the event). | | value | OPTIONAL | Marker value associated with the event (for example, the value of a TTL trigger that was recorded at the onset of the event). | | HED | OPTIONAL | Hierarchical Event Descriptor (HED) Tag. See [Appendix III](../99-appendices/03-hed.md) for details. | @@ -100,7 +100,28 @@ sub-01_task-cuedSGT_run-1_echo-2_bold.nii.gz sub-01_task-cuedSGT_run-1_echo-3_bold.nii.gz ``` -## Stimuli databases +Note: Events can also be documented in machine-actionable form using HED (Hierarchical Event Descriptor) tags. +## Stimuli + +Additional information about the stimuli can be added in the `*_events.tsv` +and `*_events.json` files. + +This can be done: + +- either by adding the stimulus files in a `/stimuli` folder +(under the root folder of the dataset; with optional subfolders) AND using a +`stim_file` column in `*_events.tsv` mentioning which stimulus file was used +for a given event, +- or by reference to a stimuli database. + + + +| **Column name** | **Requirement level** | **Data type** |**Description** | +|-----------------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +| stim_file | OPTIONAL | [string][] | Represents the location of the stimulus file (such as an image, video, or audio file) presented at the given onset time. There are no restrictions on the file formats of the stimuli files, but they should be stored in the `/stimuli` folder. The values under the stim_file column correspond to a path relative to "/stimuli". For example "images/cat03.jpg" will be translated to "/stimuli/images/cat03.jpg". | + +### Stimuli databases References to existing databases can also be encoded using additional columns. The following example includes references to the @@ -148,7 +169,7 @@ in the accompanying JSON sidecar as follows: Note that all other columns SHOULD also be described but are omitted for the sake of brevity. -## Stimulus presentation details +### Stimulus presentation details It is RECOMMENDED to include details of the stimulus presentation software, when applicable: From f2415f83fd31ba18698456e61899fe7ea565be8c Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Mon, 28 Dec 2020 11:31:14 +0100 Subject: [PATCH 02/25] move HED notes out of stimuli section --- src/04-modality-specific-files/05-task-events.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/04-modality-specific-files/05-task-events.md b/src/04-modality-specific-files/05-task-events.md index 35d0f1ad84..da4c0da4e0 100644 --- a/src/04-modality-specific-files/05-task-events.md +++ b/src/04-modality-specific-files/05-task-events.md @@ -101,6 +101,9 @@ sub-01_task-cuedSGT_run-1_echo-3_bold.nii.gz ``` 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](../99-appendices/03-hed.md) for additional information and examples. + ## Stimuli Additional information about the stimuli can be added in the `*_events.tsv` @@ -231,10 +234,6 @@ in the accompanying JSON sidecar as follows (based on the example of the previou } ``` -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](../99-appendices/03-hed.md) for additional information and examples. - [object]: https://www.json.org/json-en.html From 0bffe28a254b6c84794efddd1777a805d18e9596 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Mon, 28 Dec 2020 11:31:53 +0100 Subject: [PATCH 03/25] add data type to events description table --- .../05-task-events.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/04-modality-specific-files/05-task-events.md b/src/04-modality-specific-files/05-task-events.md index da4c0da4e0..b8b2a429b1 100644 --- a/src/04-modality-specific-files/05-task-events.md +++ b/src/04-modality-specific-files/05-task-events.md @@ -33,16 +33,15 @@ Each task events file REQUIRES a corresponding task imaging data file The tabular files consists of one row per event and a set of REQUIRED and OPTIONAL columns: -| **Column name** | **Requirement level** | Description | -|-----------------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| onset | REQUIRED | Onset (in seconds) of the event measured from the beginning of the acquisition of the first volume in the corresponding task imaging data file. If any acquired scans have been discarded before forming the imaging data file, ensure that a time of 0 corresponds to the first image stored. In other words negative numbers in "onset" are allowed5. | -| duration | REQUIRED | Duration of the event (measured from onset) in seconds. Must always be either zero or positive. A "duration" value of zero implies that the delta function or event is so short as to be effectively modeled as an impulse. | -| sample | OPTIONAL | Onset of the event according to the sampling scheme of the recorded modality (that is, referring to the raw data file that the `events.tsv` file accompanies). | -| trial_type | OPTIONAL | Primary categorisation of each trial to identify them as instances of the experimental conditions. For example: for a response inhibition task, it could take on values "go" and "no-go" to refer to response initiation and response inhibition experimental conditions. | -| response_time | OPTIONAL | Response time measured in seconds. A negative response time can be used to represent preemptive responses and "n/a" denotes a missed response. | +| **Column name** | **Requirement level** | **Data type** |**Description** | +|-----------------|-----------------------| - |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| onset | REQUIRED | [number][] | Onset (in seconds) of the event measured from the beginning of the acquisition of the first volume in the corresponding task imaging data file. If any acquired scans have been discarded before forming the imaging data file, ensure that a time of 0 corresponds to the first image stored. In other words negative numbers in "onset" are allowed5. | +| duration | REQUIRED | [number][] | Duration of the event (measured from onset) in seconds. Must always be either zero or positive. A "duration" value of zero implies that the delta function or event is so short as to be effectively modeled as an impulse. | +| sample | OPTIONAL | [number][] | Onset of the event according to the sampling scheme of the recorded modality (that is, referring to the raw data file that the `events.tsv` file accompanies). | +| trial_type | OPTIONAL | [string][] | Primary categorisation of each trial to identify them as instances of the experimental conditions. For example: for a response inhibition task, it could take on values "go" and "no-go" to refer to response initiation and response inhibition experimental conditions. | +| response_time | OPTIONAL | [number][] | Response time measured in seconds. A negative response time can be used to represent preemptive responses and "n/a" denotes a missed response. | | value | OPTIONAL | ???? | Marker value associated with the event (for example, the value of a TTL trigger that was recorded at the onset of the event). | -| value | OPTIONAL | Marker value associated with the event (for example, the value of a TTL trigger that was recorded at the onset of the event). | -| HED | OPTIONAL | Hierarchical Event Descriptor (HED) Tag. See [Appendix III](../99-appendices/03-hed.md) for details. | +| HED | OPTIONAL | ???? | Hierarchical Event Descriptor (HED) Tag. See [Appendix III](../99-appendices/03-hed.md) for details. | 5 For example in case there is an in scanner training phase that begins before the scanning sequence has started events from this sequence should @@ -236,6 +235,7 @@ in the accompanying JSON sidecar as follows (based on the example of the previou +[number]: https://www.w3schools.com/js/js_json_datatypes.asp [object]: https://www.json.org/json-en.html [string]: https://www.w3schools.com/js/js_json_datatypes.asp [strings]: https://www.w3schools.com/js/js_json_datatypes.asp From e7393bc95402d39ee54418a2aaf36fa3ee6b4406 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Mon, 28 Dec 2020 11:38:49 +0100 Subject: [PATCH 04/25] fix formatting --- .../05-task-events.md | 33 +++++++++---------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/src/04-modality-specific-files/05-task-events.md b/src/04-modality-specific-files/05-task-events.md index b8b2a429b1..62ce3e6926 100644 --- a/src/04-modality-specific-files/05-task-events.md +++ b/src/04-modality-specific-files/05-task-events.md @@ -33,15 +33,15 @@ Each task events file REQUIRES a corresponding task imaging data file The tabular files consists of one row per event and a set of REQUIRED and OPTIONAL columns: -| **Column name** | **Requirement level** | **Data type** |**Description** | -|-----------------|-----------------------| - |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| onset | REQUIRED | [number][] | Onset (in seconds) of the event measured from the beginning of the acquisition of the first volume in the corresponding task imaging data file. If any acquired scans have been discarded before forming the imaging data file, ensure that a time of 0 corresponds to the first image stored. In other words negative numbers in "onset" are allowed5. | -| duration | REQUIRED | [number][] | Duration of the event (measured from onset) in seconds. Must always be either zero or positive. A "duration" value of zero implies that the delta function or event is so short as to be effectively modeled as an impulse. | -| sample | OPTIONAL | [number][] | Onset of the event according to the sampling scheme of the recorded modality (that is, referring to the raw data file that the `events.tsv` file accompanies). | -| trial_type | OPTIONAL | [string][] | Primary categorisation of each trial to identify them as instances of the experimental conditions. For example: for a response inhibition task, it could take on values "go" and "no-go" to refer to response initiation and response inhibition experimental conditions. | -| response_time | OPTIONAL | [number][] | Response time measured in seconds. A negative response time can be used to represent preemptive responses and "n/a" denotes a missed response. | -| value | OPTIONAL | ???? | Marker value associated with the event (for example, the value of a TTL trigger that was recorded at the onset of the event). | -| HED | OPTIONAL | ???? | Hierarchical Event Descriptor (HED) Tag. See [Appendix III](../99-appendices/03-hed.md) for details. | +| **Column name** | **Requirement level** | **Data type** |**Description** | +|-----------------|-----------------------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| onset | REQUIRED | [number][] | Onset (in seconds) of the event measured from the beginning of the acquisition of the first volume in the corresponding task imaging data file. If any acquired scans have been discarded before forming the imaging data file, ensure that a time of 0 corresponds to the first image stored. In other words negative numbers in "onset" are allowed5. | +| duration | REQUIRED | [number][] | Duration of the event (measured from onset) in seconds. Must always be either zero or positive. A "duration" value of zero implies that the delta function or event is so short as to be effectively modeled as an impulse. | +| sample | OPTIONAL | [number][] | Onset of the event according to the sampling scheme of the recorded modality (that is, referring to the raw data file that the `events.tsv` file accompanies). | +| trial_type | OPTIONAL | [string][] | Primary categorisation of each trial to identify them as instances of the experimental conditions. For example: for a response inhibition task, it could take on values "go" and "no-go" to refer to response initiation and response inhibition experimental conditions. | +| response_time | OPTIONAL | [number][] | Response time measured in seconds. A negative response time can be used to represent preemptive responses and "n/a" denotes a missed response. | +| value | OPTIONAL | ???? | Marker value associated with the event (for example, the value of a TTL trigger that was recorded at the onset of the event). | +| HED | OPTIONAL | ???? | Hierarchical Event Descriptor (HED) Tag. See [Appendix III](../99-appendices/03-hed.md) for details. | 5 For example in case there is an in scanner training phase that begins before the scanning sequence has started events from this sequence should @@ -108,20 +108,19 @@ See [Hierarchical Event Descriptors](../99-appendices/03-hed.md) for additional Additional information about the stimuli can be added in the `*_events.tsv` and `*_events.json` files. -This can be done: +This can be done by using a /stimuli folder or by reference to a stimuli database. -- either by adding the stimulus files in a `/stimuli` folder +The stimulus files can be added in a `/stimuli` folder (under the root folder of the dataset; with optional subfolders) AND using a `stim_file` column in `*_events.tsv` mentioning which stimulus file was used for a given event, -- or by reference to a stimuli database. +There are no restrictions on the file formats of the stimuli files, +but they should be stored in the `/stimuli` folder. - -| **Column name** | **Requirement level** | **Data type** |**Description** | -|-----------------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| - -| stim_file | OPTIONAL | [string][] | Represents the location of the stimulus file (such as an image, video, or audio file) presented at the given onset time. There are no restrictions on the file formats of the stimuli files, but they should be stored in the `/stimuli` folder. The values under the stim_file column correspond to a path relative to "/stimuli". For example "images/cat03.jpg" will be translated to "/stimuli/images/cat03.jpg". | +| **Column name** | **Requirement level** | **Data type** |**Description** | +|-----------------|-----------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| stim_file | OPTIONAL | [string][] | Represents the location of the stimulus file (such as an image, video, or audio file) presented at the given onset time. The values under the `stim_file` column correspond to a path relative to `/stimuli`. For example `images/cat03.jpg` will be translated to `/stimuli/images/cat03.jpg`. | ### Stimuli databases From 4178e5316efbcb5a42ddf203a3c50b03261a1a04 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Sun, 21 Feb 2021 14:21:23 +0100 Subject: [PATCH 05/25] restructure intro events.md --- .../05-task-events.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/src/04-modality-specific-files/05-task-events.md b/src/04-modality-specific-files/05-task-events.md index 62ce3e6926..c23c1f8fb0 100644 --- a/src/04-modality-specific-files/05-task-events.md +++ b/src/04-modality-specific-files/05-task-events.md @@ -1,16 +1,28 @@ # Task events +The purpose of this file is to describe timing and other properties of events +recorded during a run. +Events MAY be either stimuli presented to the participant or participant responses. +A single event file MAY include any combination of stimuli and response events. +Events MAY overlap in time. +Please mind that this does not imply that only so called "event related" study designs +are supported (in contrast to "block" designs) - each "block of events" can be +represented by an individual row in the `_events.tsv` file (with a long +duration). + Template: ```Text sub-