Skip to content

What does a HED annotation look like?

Understanding HED becomes much easier when looking at a concrete example. In practice, HED annotations are used to describe events that occur during an experiment and are typically attached to the events of a BIDS dataset.

In BIDS datasets, experimental events are stored in tab-separated files called:

*_events.tsv

These files contain a timeline of events during the experiment, including when they occur and what type of event they represent. At minimum, they contain the columns:

onset
duration

Additional columns usually describe properties of the event such as the stimulus type, response type, or experimental condition.

A simple events.tsv example

Below is a simplified example of an events file from a behavioral experiment.

onset    duration    trial_type
1.2      0.5         fixation
2.0      0.5         stimulus
2.7      n/a         button_press

This file tells us when events occur, but it does not yet describe what these events actually mean in a standardized way.

For example:

  • What type of stimulus was shown?
  • What kind of response was made?
  • Was this part of a task or condition?

This is where HED annotations come in.

Adding HED annotations

HED annotations describe events using standardized tags taken from the HED schema browser.

A HED annotation is simply a comma-separated list of tags that describe the event.

Example:

Sensory-event, Visual-presentation, Item/Object/2D shape/Cross

Each tag adds more meaning:

Tag Meaning
Sensory-event Something was presented to the participant
Visual-presentation The stimulus was visual
Item/Object/2D shape/Cross The stimulus was a cross

Together they describe the event in a machine-readable and human-readable way.

Example: Annotating events with HED

Instead of leaving the event type ambiguous, we can define HED annotations for each event category.

events.tsv

onset   duration   trial_type
1.2     0.5        fixation
2.0     0.5        stimulus
2.7     n/a        button_press

events.json (sidecar)

{
  "trial_type": {
    "Description": "Type of event occurring in the experiment",
    "Levels": {
      "fixation": "Fixation cross presented",
      "stimulus": "Visual stimulus presented",
      "button_press": "Participant response"
    },
    "HED": {
      "fixation": "Sensory-event, Visual-presentation, Item/Object/Cross",
      "stimulus": "Sensory-event, Visual-presentation, Experimental-stimulus",
      "button_press": "Agent-action, Participant-response, Action/Button-press"
    }
  }
}

Here, each event category is mapped to a HED annotation. Analysis tools combine the information from events.tsv with the annotations defined in events.json to generate the final event descriptions.

The resulting HED annotation

When a tool processes the dataset, the event

trial_type = stimulus

produces the HED annotation

Sensory-event, Visual-presentation, Experimental-stimulus

This means that both humans and software tools can immediately understand the meaning of the event.