Skip to content

HED Quick Annotation Guide (How-To)

Goal of this page

This page is a practical step-by-step guide for annotating events with HED in a BIDS dataset.

It is designed for users who want to get the job done quickly, without needing deep knowledge of HED.

If something is unclear, you can refer to the detailed documentation pages in this handbook.

When should I use this guide?

This guide covers the most common situation:

You already have BIDS data with events.tsv files and want to add HED annotations.

Other situations:

  • Planning a new study → focus on creating good events.tsv first (will link to Experiment or Study Planning)
  • Only logfiles available → you first need to convert logs → events.tsv (Link to Data Onboarding?)

This page starts once you have an events.tsv file.

Step 1 — Review your events.tsv

Before using the HED tools, quickly check your events.tsv:

  • Are all relevant events included?
  • Are column names clear and consistent?
  • Are different aspects split into separate columns?

If your event file is unclear or incomplete, fix it first!

Step 2 — Generate your events.json

Use the HED tools to create a template:

-> https://hedtools.org/hed/events

Steps to events.json

  • Select "Generate JSON sidecar template"
  • Upload your events.tsv
  • Select all columns (except onset)
  • Mark categorical columns
  • Click Process

You will get a JSON template.

Step 3 — Place and open your events.json

In your BIDS dataset, locate the file:

*_events.json

This file defines the meaning of the columns in your events.tsv.

Step 4 — Identify your columns

Look at your events.tsv file.

Typical columns are:

  • trial_type
  • event_type
  • stim_type
  • response
  • condition
  • stim_file

For each column, decide:

Column type What it means
Categorical Fixed set of labels (e.g., stimulus, button_press)
Value-based Row-specific values (e.g., file paths, reaction times)

Step 5 — Find the correct HED tags

For categorical columns, define a mapping for each value.

Example of a full simple HED annotation

"trial_type": {
  "Description": "Type of event",
  "Levels": {
    "fixation": "Fixation cross",
    "stimulus": "Stimulus presentation",
    "button_press": "Participant response"
  },
  "HED": {
    "fixation": "Sensory-event, Visual-presentation, Cross",
    "stimulus": "Sensory-event, Visual-presentation, Experimental-stimulus",
    "button_press": "Agent-action, Press, (Experiment-participant, Human-agent)"
  }
}

Your events.json should look like this example in the end. Please find the steps to get there below.

Rule:

  • One HED string per level
  • Tags must be comma-separated

You do NOT invent tags.

Use the HED schema browser!

How to search

  1. Think about the meaning of your event
  2. Search for keywords (e.g., "face", "cross", "tone", "press")
  3. Select the closest matching tag

Example

You want to annotate a fixation cross:

  • Search: "cross"
  • Find: Item/Object/Geometric-object/2D-shape/Cross

You can use short form:

Cross
Important: you shouldn't invent tags!

You should only use terms that exist in the HED schema to ensure and improve searchability!

For example:

  • Cross valid (exists in the schema)
  • MyCustomCross invalid (not in the schema)

Always search in the schema browser before using a term!

Step 6 — Build a simple HED annotation

Use this simple pattern:

Event-type, modality, item, optional details

Example

Sensory-event, Visual-presentation, Cross

Agent-action, Press, Experiment-participant, Human-agent

Important: / vs ,

HED uses two different structures:

  • / = hierarchy (one tag)
  • , = separate tags

Example:

Cross
= short form of
Item/Object/Geometric-object/2D-shape/Cross

This is one single tag, not a list.

Example of multiple tags:

Sensory-event, Visual-presentation, Cross

Rule: - Use , to separate tags - Use / only inside a tag (do not split it)

Step 7 — Use parentheses when things belong together

Use parentheses to group related tags.

Example

(Red, Triangle), (Blue, Square)

Without parentheses, meaning becomes ambiguous!

Step 8 — Add HED for value columns using #

For columns with values (e.g., file names, numbers), use #.

Example

"stim_file": {
  "Description": "Path to stimulus file",
  "HED": "(Image, Pathname/#)"
}

If events.tsv contains:

stim_file = faces/u032.bmp

Result:

(Image, Pathname/faces/u032.bmp)

Rule:

  • Use # only for value columns
  • Use exactly one # per value mapping

Step 9 — Validate your dataset

Run the BIDS validator.

If you see warnings:

  • TAG_EXTENDED → you used a non-standard tag
  • Syntax errors → check commas and parentheses

Fix by:

  • using tags from the schema
  • correcting syntax

Step 10 — Minimal checklist

Before finishing, check:

  • Tags are comma-separated
  • Parentheses are balanced
  • Tags come from the schema
  • # is only used for value columns
  • Each level has one HED string

Example (complete minimal setup)

{
  "trial_type": {
    "HED": {
      "fixation": "Sensory-event, Visual-presentation, Cross",
      "stimulus": "Sensory-event, Visual-presentation, Experimental-stimulus",
      "response": "Agent-action, Press"
    }
  },
  "stim_file": {
    "HED": "(Image, Pathname/#)"
  }
}

Key takeaway

To annotate with HED:

  1. Open events.json
  2. Map each column value to a HED string
  3. Use tags from the schema browser
  4. Separate tags with commas
  5. Use # for value columns

You do not need to understand everything about HED to get started.

Follow these steps, and your dataset will already be much more usable and shareable.