Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[ENH] Define channel column for events and Delimiter field for column descriptions #1483

Merged
merged 7 commits into from
Nov 13, 2023
48 changes: 36 additions & 12 deletions src/modality-specific-files/task-events.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "sweat" was "musc" in a later example and the "artifact" column was called "annot". I think the same example should be continued along.

```

In the accompanying JSON sidecar, the `trial_type` column might look as follows:
Expand All @@ -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": {
sappelhoff marked this conversation as resolved.
Show resolved Hide resolved
"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
VisLab marked this conversation as resolved.
Show resolved Hide resolved
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`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that the two examples that relate to this should have this column either called "artifact" or "annot".

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,
sappelhoff marked this conversation as resolved.
Show resolved Hide resolved
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:
Expand All @@ -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`
Expand Down