Hierarchical Event Descriptors (HED) are a controlled vocabulary of terms describing events in a machine-actionable form so that algorithms can use the information without manual recoding. HED was originally developed with EEG in mind, but is applicable to all behavioral experiments.
Each level of a hierarchical tag is delimited with a forward slash (/).
A HED string contains one or more HED tags separated by commas (,).
Parentheses (brackets, ()) group tags and enable specification of multiple items
and their attributes in a single HED string (see section 2.4 in
HED Tagging Strategy Guide).
For more information about HED and tools available to validate and match HED
strings, please visit www.hedtags.org.
Since dedicated fields already exist for the overall task classification in the
sidecar JSON files (CogAtlasID and CogPOID), HED tags from the Paradigm
HED subcategory should not be used to annotate events.
There are several ways to associate HED annotations with events within the BIDS
framework.
The most direct way is to use the HED column of the *_events.tsv
file to annotate events.
Example: An *_events.tsv annotated using HED tags for individual events.
onset duration HED
1.1 n/a Event/Category/Experimental stimulus, Event/Label/CrossFix, Sensory presentation/Visual, Item/Object/2D Shape/Cross
1.3 n/a Event/Category/Participant response, Event/Label/ButtonPress, Action/Button press
...
The direct approach requires that each line in the events file be annotated.
Since there are typically thousands of events in each experiment,
this method of annotation is not convenient unless the annotations are
automatically generated.
Usually annotations that appear in the HED column are specific to each individual event.
Information that is common to groups of events can be annotated by category.
Numerical values associated with each event can be annotated by value type.
Annotating by category and by valuegreatly reduces the effort required to HED tag
data and improves the clarity for data users.
In many experiments, the event instances fall into a much smaller number of
categories, and often these categories are labeled with numerical codes or short names.
This categorical information usually corresponds to one or more columns in *_events.tsv
representing categorical values.
Instead of tagging this information for each individual event,
you can assign HED tags for each distinct categorical value
in an accompanying *_events.json sidecar and allow the analysis tools to make
the association with individual event instances during analysis.
The column name in the *_events.tsv identifies the type of categorical variable.
The following *_events.tsv file has one categorical variable called mycodes that
takes on three possible values: Fixation, Button, and Target.
Example: An *_events.tsv containing the mycodes categorical column.
onset duration mycodes
1.1 n/a Fixation
1.3 n/a Button
1.8 n/a Target
...
Example: An accompanying *_events.json sidecar describing the mycodes categorical variable.
{
"mycodes": {
"LongName": "Local event type names",
"Description": "Main types of events that comprise a trial",
"Levels": {
"Fixation": "Fixation cross is displayed",
"Target": "Target image appears",
"Button": "Subject presses a button"
},
"HED": {
"Fixation": "Event/Category/Experimental stimulus, Event/Label/CrossFix,
Event/Description/A cross appears at screen center to serve as a fixation point,
Sensory presentation/Visual, Item/Object/2D Shape/Cross,
Attribute/Visual/Fixation point, Attribute/Visual/Rendering type/Screen,
Attribute/Location/Screen/Center",
"Target": "Event/Label/TargetImage, Event/Category/Experimental stimulus,
Event/Description/A white airplane as the RSVP target superimposed on a satellite image is displayed.,
Item/Object/Vehicle/Aircraft/Airplane, Participant/Effect/Cognitive/Target,
Sensory presentation/Visual/Rendering type/Screen/2D),
(Item/Natural scene/Aerial/Satellite,
Sensory presentation/Visual/Rendering type/Screen/2D)",
"Button": "Event/Category/Participant response, Event/Label/PressButton,
Event/Description/The participant presses the button as soon as the target is visible,
Action/Button press"
}
}
}Each column of *_events.tsv containing non-categorical values usually represents a
particular type of data, for example the speed of a stimulus object across the
screen or the file name of the stimulus image.
These variables could be annotated in the HED column of *_events.tsv.
However, that approach requires repeating the values appearing in the individual
columns in the HED column.
A better approach is to annotate the type of value contained in each of these
columns in the *_events.json sidecar.
Value variables are annotated in a manner similar to categorical values,
except that the HED string must contain exactly one # specifying a placeholder
for the actual column values.
Tools are responsible for substituting the actual column values for the # during analysis.
Example: An *_events.tsv containing a categorical column (trial_type) and two value
columns (response_time and stim_file).
onset duration trial_type response_time stim_file
1.2 0.6 go 1.435 images/red_square.jpg
5.6 0.6 stop 1.739 images/blue_square.jpg
Example: An accompanying *_events.json sidecar describing both categorical and value columns.
{
"trial_type": {
"LongName": "Event category",
"Description": "Indicator of type of action that is expected",
"Levels": {
"go": "A red square is displayed to indicate starting",
"stop": "A blue square is displayed to indicate stopping",
},
"HED": {
"go": "Event/Category/Experimental stimulus, Event/Label/RedSquare,
Event/Description/A red square is displayed to indicate starting,
Sensory presentation/Visual, Item/Object/2D Shape/Square,
Attribute/Visual/Color/Red, Attribute/Visual/Rendering type/Screen,
Attribute/Location/Screen/Center",
"stop": "Event/Category/Experimental stimulus, Event/Label/BlueSquare,
Event/Description/A blue square is displayed to indicate stopping,
Sensory presentation/Visual, Item/Object/2D Shape/Square,
Attribute/Visual/Color/Blue, Attribute/Visual/Rendering type/Screen,
Attribute/Location/Screen/Center",
}
},
"response_time": {
"LongName": "Response time after stimulus",
"Description": "Time from stimulus presentation until subject presses button",
"Units": "ms",
"HED": "Attribute/Response start delay/# ms, Action/Button press"
},
"stim_file": {
"LongName": "Stimulus file name",
"Description": "Relative path of the stimulus image file",
"HED": "Attribute/File/#"
}
}Most studies will have event categorical variables and value variables that
are common across many of the datasets in the study.
You should try to annotate these columns in a *_events.json sidecar
as high in the study hierarchy as possible to avoid duplicate annotations.
Annotations that can be placed in sidecars are preferred to those placed
directly in the HED column, because they are simpler, more compact, and
less prone to inconsistent annotation.
Downstream tools should not distinguish between tags specified using
the explicit HED column and the categorical specifications, but should
form the union before analysis.
Further, the inheritance principle
applies, so the data dictionaries can appear higher in the BIDS hierarchy.
You should try to annotate in as much detail as possible. The HED path structure makes it easy for analysis tools to extract tags at different levels of detail: For example a user can consider extracting events associated with 2D shapes for stimuli, ignoring the particular color or shape details for the stimuli.
The HED vocabulary is specified by a HED schema, which delineates the allowed HED path strings. By default, BIDS uses the latest HED schema available in the hed-specification repository maintained by the hed-standard group.
You can override the default by providing a specific HED version number in the
dataset_description.json file using the HEDVersion field.
The preferred approach is to validate with the latest version (the default),
but to use the HEDVersion field to specify which version was used for later reference.
Example: The following dataset_description.json file specifies that
HED7.1.1.xml from the hed-specification repository
should be used to validate the study event annotations.
{
"Name": "The mother of all experiments",
"BIDSVersion": "1.4.0",
"HEDVersion": "7.1.1"
}