Task events
The purpose of this file is to describe timing and other properties of events
recorded during a run.
Events are, for example, stimuli presented to the participant or participant responses
(see Definitions).
A single event file MAY include any combination of stimulus, response, and other 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:
sub-<label>/[ses-<label>]
<data_type>/
<matches>_events.tsv
<matches>_events.json
Where <matches>
corresponds to task filename. For example:
sub-control01_task-nback
.
Each task events file REQUIRES a corresponding task data file.
It is also possible to have a single events.tsv
file describing events
for all participants and runs (see
Inheritance Principle).
As with all other tabular data, events.tsv
files MAY be accompanied by a JSON
file describing the columns in detail (see
Tabular Files).
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 data point stored in the corresponding task data file. Negative onsets are allowed, to account for events that occur prior to the first stored data point. For example, in case there is an in-scanner training phase that begins before the scanning sequence has started events from this sequence should have negative onset time counting down to the beginning of the acquisition of the first volume. If any data points have been discarded before forming the data file (for example, "dummy volumes" in BOLD fMRI), a time of 0 corresponds to the first stored data point and not the first acquired data point. This column must appear first in the file. |
duration | REQUIRED | number or "n/a" |
Duration of the event (measured from onset) in seconds. Must always be either zero or positive (or n/a if unavailable). A "duration" value of zero implies that the delta function or event is so short as to be effectively modeled as an impulse. This column must appear second in the file. |
sample | OPTIONAL | integer | 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). When there are several sampling schemes present in the raw data file (as can be the case for example for .edf files), this column is ambiguous and SHOULD NOT be used. This column may appear anywhere in the file. |
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. This column may appear anywhere in the file. |
response_time | OPTIONAL | number or "n/a" |
Response time measured in seconds. A negative response time can be used to represent preemptive responses and n/a denotes a missed response. This column may appear anywhere in the file. |
value | OPTIONAL | number or string | Marker value associated with the event (for example, the value of a TTL trigger that was recorded at the onset of the event). This column may appear anywhere in the file. |
HED | OPTIONAL | string | Hierarchical Event Descriptor (HED) Tag. See the HED Appendix for details. This column may appear anywhere in the file. |
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 directory (under the root directory of the dataset; with OPTIONAL subdirectories). 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 . This column may appear anywhere in the file. |
Additional Columns | OPTIONAL | n/a |
Additional columns are allowed. |
Note for MRI data:
If any acquired scans have been discarded before forming the imaging data file,
ensure that an onset
of 0 corresponds to the time the first image was stored.
For example in case there is an in scanner training phase that
begins before the scanning sequence has started events from this sequence should
have negative onset time counting down to the beginning of the acquisition of
the first volume.
Note regarding the precision of numeric metadata:
It is RECOMMENDENDED that dataset curators specify numeric metadata like onset
and
duration
with as much decimal precision as is reasonable in the context of the experiment.
For example in an EEG experiment with devices operating at 1000 Hz sampling frequency,
dataset curators SHOULD specify at least 3 figures after the decimal point.
An arbitrary number of additional columns can be added. Those allow describing
other properties of events that could be later referenced in modelling and
hypothesis extensions of BIDS.
Note that the trial_type
and any additional columns in a TSV file
SHOULD be documented in an accompanying JSON sidecar file.
Example:
└─ sub-control01/
└─ func/
├─ sub-control01_task-stopsignal_events.tsv
└─ sub-control01_task-stopsignal_events.json
Example of the content of the TSV file:
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
In the accompanying JSON sidecar, the trial_type
column might look as follows:
{
"trial_type": {
"LongName": "Event category",
"Description": "Indicator of type of action that is expected",
"Levels": {
"start": "A red square is displayed to indicate starting",
"stop": "A blue square is displayed to indicate stopping"
}
}
}
Note that all other columns SHOULD also be described but are omitted for the sake of brevity.
For multi-echo files, the events.tsv
file is applicable to all echos of
a particular run:
└─ sub-01/
└─ func/
├─ sub-01_task-cuedSGT_run-1_events.tsv
├─ sub-01_task-cuedSGT_run-1_echo-1_bold.nii.gz
├─ sub-01_task-cuedSGT_run-1_echo-2_bold.nii.gz
└─ 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 for additional information and examples.
Stimuli
Additional information about the stimuli can be added in the events.tsv
and events.json
files.
This can be done by using a /stimuli
directory or by reference to a stimuli database.
Stimuli directory
The stimulus files can be added in a /stimuli
directory
(under the root directory of the dataset; with optional subdirectories) AND using a
stim_file
column in events.tsv
mentioning which stimulus file was used
for a given event,
There are no restrictions on the file formats of the stimuli files,
but they should be stored in the /stimuli
directory.
Stimuli databases
References to existing databases can also be encoded using additional columns. The following example includes references to the Karolinska Directed Emotional Faces (KDEF) database.
Example:
└─ sub-control01/
└─ func/
├─ sub-control01_task-emoface_events.tsv
└─ sub-control01_task-emoface_events.json
Example of the content of the TSV file:
onset duration trial_type identifier database response_time
1.2 0.6 afraid AF01AFAF kdef 1.435
5.6 0.6 angry AM01AFAN kdef 1.739
5.6 0.6 sad AF01ANSA kdef 1.739
The trial_type
and identifier
columns from the events.tsv
files might be described
in the accompanying JSON sidecar as follows:
{
"trial_type": {
"LongName": "Emotion image type",
"Description": "Type of emotional face from Karolinska database that is displayed",
"Levels": {
"afraid": "A face showing fear is displayed",
"angry": "A face showing anger is displayed",
"sad": "A face showing sadness is displayed"
}
},
"identifier": {
"LongName": "Karolinska (KDEF) database identifier",
"Description": "ID from KDEF database used to identify the displayed image"
}
}
Note that all other columns SHOULD also be described but are omitted for the sake of brevity.
Stimulus presentation details
It is RECOMMENDED to include details of the stimulus presentation software, when applicable:
Key name | Requirement Level | Data type | Description |
---|---|---|---|
StimulusPresentation | RECOMMENDED | object | Object containing key-value pairs related to the software used to present the stimuli during the experiment, specifically: "OperatingSystem" , "SoftwareName" , "SoftwareRRID" , "SoftwareVersion" and "Code" . See table below for more information. |
The object supplied for StimulusPresentation
SHOULD include the following key-value pairs:
Key name | Requirement Level | Data type | Description |
---|---|---|---|
OperatingSystem | RECOMMENDED | string | Operating system used to run the stimuli presentation software (for formatting recommendations, see examples below this table). |
SoftwareName | RECOMMENDED | string | Name of the software that was used to present the stimuli. |
SoftwareRRID | RECOMMENDED | string | Research Resource Identifier of the software that was used to present the stimuli. Examples: The RRID for Psychtoolbox is 'SCR_002881', and that of PsychoPy is 'SCR_006571'. |
SoftwareVersion | RECOMMENDED | string | Version of the software that was used to present the stimuli. |
Code | RECOMMENDED | string | URI of the code used to present the stimuli. Persistent identifiers such as DOIs are preferred. If multiple versions of code may be hosted at the same location, revision-specific URIs are RECOMMENDED. |
The operating system description SHOULD include the following attributes:
- type (for example, Windows, macOS, Linux)
- distribution (if applicable, for example, Ubuntu, Debian, CentOS)
- the version number (for example, 18.04.5)
Examples:
- Windows 10, Version 2004
- macOS 10.15.6
- Linux Ubuntu 18.04.5
The amount of information supplied for the OperatingSystem
SHOULD be sufficient
to re-run the code under maximally similar conditions.
The information related to stimulus presentation might be described in the accompanying JSON sidecar as follows (based on the example of the previous section):
{
"trial_type": {
"LongName": "Emotion image type",
"Description": "Type of emotional face from Karolinska database that is displayed",
"Levels": {
"afraid": "A face showing fear is displayed",
"angry": "A face showing anger is displayed",
"sad": "A face showing sadness is displayed"
}
},
"identifier": {
"LongName": "Unique identifier from Karolinska (KDEF) database",
"Description": "ID from KDEF database used to identify the displayed image"
},
"StimulusPresentation": {
"OperatingSystem": "Linux Ubuntu 18.04.5",
"SoftwareName": "Psychtoolbox",
"SoftwareRRID": "SCR_002881",
"SoftwareVersion": "3.0.14",
"Code": "doi:10.5281/zenodo.3361717"
}
}