Skip to content

Annotating Experiments with Hierarchical Event Descriptors (HED)

What is HED?

Hierarchical Event Descriptors (HED) is a standardized framework for describing events during a neuroscience or psychology experiment. It is integrated into BIDS (Brain Imaging Data Structure) and is used for EEG, MEG, fMRI, physiological recordings, and behavioral experiments.

Events in many datasets are stored as short codes like 1, stim_on, or resp. These labels are often ambiguous to anyone other than the original researcher — and sometimes to the researcher themselves months later.

HED provides:

  • A controlled vocabulary organized as a hierarchy (the HED schema)
  • Machine-readable annotations that tools can validate, search, and analyze
  • A shared vocabulary across labs, enabling data sharing, reuse, and cross-study comparison
  • Analysis-ready datasets where experimental meaning is preserved directly with the data

HED is also integrated into NWB (Neurodata Without Borders), making it useful across modern neuroscience data infrastructures.

What a HED annotation looks like

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

*_events.tsv

These record a timeline of events during the experiment. At minimum they contain onset and duration columns; additional columns describe the event type, condition, or response.

A simple events.tsv

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 not what they mean in a standardized way.

Adding HED in the events.json sidecar

HED annotations go in the companion JSON sidecar. A HED annotation is a comma-separated list of tags taken from the HED schema browser.

For example, a fixation cross event can be described as:

Tag Meaning
Sensory-event Something was presented to the participant
Visual-presentation The stimulus was visual
Cross The stimulus was a cross 
{
  "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, Cross",
      "stimulus": "Sensory-event, Visual-presentation, Experimental-stimulus",
      "button_press": "Agent-action, Press, (Experiment-participant, Human-agent)"
    }
  }
}

The resulting annotation

When a tool processes the dataset, the event trial_type = stimulus produces:

Sensory-event, Visual-presentation, Experimental-stimulus

Both humans and software tools can immediately understand what happened.

The HED Hierarchy

Why HED is hierarchical

The HED schema is a controlled vocabulary organized as a tree. Each tag belongs to a path, and each child tag is a more specific version of its parent.

Item/Object/Geometric-object/2D-shape/Rectangle/Square

This means a search for 2D-shape will also find events tagged with Square, Rectangle, Cross, or Triangle. HED tools support short-form tags — in annotation you usually write only the final node name (e.g. Square), and tools expand it to the long form when needed.

How to read the schema browser

When you open the schema browser, the top-level branches answer different annotation questions:

Top-level branch Main question it answers Typical use
Event What kind of event is this? Stimulus, response, recording marker, trial structure
Agent Who or what is involved? Participant, software, device, experimenter
Action What happened or what was done? Press, move, speak, read, track
Item What object, stimulus, or thing is involved? Face, image, sound, body part, text
Property What characteristics describe it? Color, label, ID, task role, environment
Relation How are things linked? Connected-to, part-of, above, equal-to

A recipe for choosing tags

When annotating an event, go through these questions in order:

Question HED branch to check Example answer
What kind of event is this? Event Sensory-event
Who is involved? Agent Human-agent, Experiment-participant
What happened? Action Press, Saccade, Speak
What item or stimulus is involved? Item Face, Cross, Tone, Word
Which properties matter? Property Target, Correct-action, Label, Condition-variable
Are relations important? Relation Performed-by, Above, Part-of

A good HED annotation often answers: what happened, who did it, what was involved, what properties matter, and how things are related.

1. Event: what kind of event happened?

The Event branch is usually the best place to start.

Event tag Meaning Typical example
Sensory-event Something was presented to or perceived by the participant A face image appears; a tone is played
Agent-action A person, device, or software agent does something Participant presses a button
Data-feature A meaningful feature appears in the recorded signal An EEG artifact marker
Experiment-control The system controls the run or recording process Start recording; stop task
Experiment-procedure A procedural step takes place Calibration, instruction phase
Experiment-structure The event marks the structure of the design Trial start, block start, rest period
Measurement-event Something related to measurement or acquisition MRI acquisition begins; impedance check

Practical rule — for each event row, ask:

  • A presented stimulus → start with Sensory-event
  • A response or behavior → start with Agent-action
  • A trial or block marker → start with Experiment-structure
  • A calibration or setup step → start with Experiment-procedure
  • Something in the signal itself → start with Data-feature

2. Agent: who or what is involved?

Agent tag Meaning Typical example
Animal-agent A non-human animal acts Rodent in a behavioral task
Avatar-agent A virtual or represented actor acts Avatar in VR or game-like task
Controller-agent A control mechanism is the acting entity Joystick controller
Human-agent A human is the acting entity Participant, clinician, experimenter
Robotic-agent A robot acts Robotic arm in an interaction task
Software-agent Software performs an action Presentation software logs a trigger

In neuroscience datasets, the difference between participant, software, and device action can be crucial:

  • Participant presses a key → Human-agent, Agent-action, Press
  • Presentation software displays an image → Software-agent, Sensory-event, Visual-presentation

3. Action: what was done?

Action family What it covers Example tags
Communicate Expressive or communicative behavior Speak, Laugh, Cry, Whisper, Wave, Smile
Move Whole-body or body-part movement Walk, Run, Jump, Blink, Saccade, Press, Touch
Perceive Acts of sensing Hear, See, Smell, Taste, Sense-by-touch
Perform Generic task performance actions Read, Write, Play, Open, Close, Rest
Track Following or tracking something Eye tracking, cursor tracking

Common actions in neuroscience / psychology:

Tag Meaning Useful in
Blink Eyelid closure EEG / eye tracking / artifact annotation
Saccade Fast eye movement Eye tracking, visual attention
Fixate Maintain gaze on a target Visual tasks
Press Pressing something Button press tasks
Speak Producing spoken language Speech tasks, interview paradigms
Touch Touching an object or surface Tactile tasks
Nod-head Nodding movement Nonverbal response annotation

4. Item: what object, stimulus, or thing is involved?

Item family What it covers Example tags
Biological-item Body parts, organisms Face, Eye, Brain, Hand, Human, Animal
Language-item Linguistic units Word, Sentence, Syllable, Phrase, Pseudoword, Phoneme
Object Physical or abstract objects Cross, Triangle, Arrow, Image, Movie, Questionnaire
Sound Acoustic stimuli Tone, Click, Buzz, Instrument-sound, Vocalized-sound, Crowd-sound

Common stimulus items:

Tag Common use
Face Face perception experiments
Eye Eye movement, gaze, facial stimulus annotation
Hand Motor tasks, gesture tasks
Word Lexical decision, reading
Pseudoword Psycholinguistic paradigms
Sentence Language comprehension
Cross Fixation cross
Arrow Cueing tasks
Image Generic image stimulus
Tone Auditory oddball, ERP tasks
Vocalized-sound Voice perception

5. Property: what characteristics matter?

Property family What it is for Example tags
Agent-property State, role, or traits of an agent Alert, Asleep, Happy, Experiment-participant, Experimenter, Handedness
Data-property Aspects of data Data-marker, Data-value, Data-source-type
Environmental-property The environment Indoors, Outdoors, Urban, Virtual-world, Real-world
Informational-property Labels, identifiers, metadata, parameters Label, Description, ID, Pathname, Parameter
Organizational-property Structure and experiment organization Condition-variable, Control-variable, Task, Experimental-trial, Time-block
Task-property Task roles and task meaning Appropriate-action, Correct-action, Target, Distractor, Instructional

Frequently used task and informational properties:

Tag Meaning Common use
Target Stimulus is task-relevant Oddball, visual search
Distractor Stimulus is a distractor Attention tasks
Correct-action Response is correct Behavioral outcome
Incorrect-action Response is wrong Error trials
Instructional Stimulus provides instruction Task instructions
Condition-variable Experimental condition descriptor Congruent vs incongruent
Label Human-readable label Label a condition or item
Pathname File path Stimulus file paths in sidecars
Experimental-trial Trial unit Trial onset/offset definitions
Time-block Block-level structure Rest block, task block

6. Relation: how are things connected?

Relation family What it expresses Example tags
Comparative-relation Comparison of values or qualities Equal-to, Greater-than, Less-than
Connective-relation General conceptual or structural relation Connected-to, Part-of, Performed-by, Performed-using
Logical-relation Logic-level linkage And, Or
Spatial-relation Position in space Above, Below, Adjacent-to, Around

The Relation branch is often underused by beginners but becomes powerful in richer annotations:

Tag Example use
Part-of Eye is part of Face
Performed-by Press performed by participant
Performed-using Response made using index finger
Above Stimulus above fixation point

What researchers should remember

You do not need to memorize the full schema. Instead, learn the logic:

  1. Start with an Event tag.
  2. Add the main Item, Action, or Agent tags.
  3. Add Property tags that make the scientific meaning clearer.
  4. Use Relation tags only when the relationship itself matters.
  5. Use the schema browser as a guided vocabulary, not a list to memorize.

Goal of this guide

This is a practical step-by-step guide for annotating events with HED in a BIDS dataset, designed for users who want to get the job done without needing deep HED knowledge first.

This guide covers the most common situation: you already have BIDS data with events.tsv files and want to add HED annotations.

If you don't have events.tsv files, the following hints may be helpful.

Plan your events.tsv files

Before setting up your task experiment, it is important to plan your events file. Your events file should capture everything that happens during the experiment — not only what is needed for analysis. A well-planned events file makes your data easier to understand, reuse, and analyze later.

Start with a simple table

Create a dummy events table as a reference. Every events file must contain onset and duration columns.

All other columns are optional in BIDS — but in practice, additional columns are necessary for meaningful analysis.

We recommend starting with an event_type column.

onset duration event_type
... ... ...

Create a timeline of your experiment

Think through your experiment from start to finish. Ask yourself:

  • What does the participant see or hear?
  • What actions can they perform?
  • What events occur during the task?

Typical events include: instruction screens, fixation crosses, stimulus presentation, responses, feedback.

Structure of a simple experiment
  1. instruction screen
  2. fixation cross
  3. stimulus presentation
  4. (optional) participant response
  5. feedback

Define event types

Group your events into general categories. The event_type should describe the event at a high level, not all details.

Example event_type column
onset duration event_type
... ... welcome_screen
... ... fixation
... ... stimulus
... ... response
... ... feedback

Rule: Keep event types simple and general. Details will be added in additional columns.

Add additional columns (event properties)

Describe how events differ from each other. Ask yourself:

  • Are stimuli different (e.g., image, sound)?
  • Are they shown at different positions?
  • Do they belong to different conditions?
  • Are responses correct or incorrect?

Each of these becomes a new column.

Example additional columns
onset duration event_type position image
... ... stimulus left image1.jpg
... ... stimulus right image2.jpg

Best practices for structuring your events table

Use multiple columns instead of encoding everything in one. Avoid putting too much meaning into event_type. This makes your data easier to analyze later.

Multiple columns instead of one

Instead of:

event_type
stimulus_left_happy

Use:

event_type position condition
stimulus left happy

Some information applies to multiple events. Use the same value across related events.

Conditions and trials

Multiple events belong to the same trial or multiple trials belong to the same condition.

Add columns, such as trial_nr and condition.

When implementing your experiment, check that your recorded events.tsv matches your plan. Keep the file of your planning for further reference.

A complete event planning example
onset duration event_type position image button accuracy feedback_type condition
... ... welcome_screen n/a n/a n/a n/a n/a n/a
... ... fixation n/a n/a n/a n/a n/a n/a
... ... stimulus left image1.jpg n/a n/a n/a happy
... ... stimulus right image2.jpg n/a n/a n/a sad
... ... response n/a n/a a 0 n/a happy
... ... response n/a n/a b 1 n/a sad
... ... feedback n/a n/a n/a n/a congruent happy
... ... feedback n/a n/a n/a n/a incongruent sad

Use n/a when a column does not apply to an event.

Some information cannot be written during data acquisition and post-processing may be needed, for example, response accuracy, trial-level information, derived variables. In these cases, post-processing is required. We recommend using the HED remodeler tool to process and enrich your event files.

Use BIDS-ready software

Various tools can be used to implement a task experiment. PsychoPy comes with a BIDS Plugin, which simplifies generating BIDS-ready events.tsv files.

Use the ANC PsychoPy Template to quickly start an example PsychoPy experiment. The template includes:

  • a working example experiment
  • predefined event types
  • BIDS-compatible logging via psychopy-bids
  • instructions for executing the experiment and adapting it to your own study
Convert non-BIDS event logs

Implementing experiments with software like NBS Presentation, Psychtoolbox, or o_ptb toolbox may not result in BIDS-ready events.tsv files, but rather software-specific log files.

For NBS Presentation, you can use a basic conversion script which will convert a log file into an event.tsv file.

More information on converting log files into BIDS event.tsv is available in Converting an example behavioral dataset for sharing in BIDS.

Note: Additional processing is usually required after conversion. We recommend using the HED Remodeler.

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

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

You will receive a JSON template to use as your starting point.

Step 3 — Place and open your events.json

After generating the JSON file using the HED tool:

  1. Rename the file to match your task:
task-<taskName>_events.json

  1. Place it in your BIDS dataset:

  2. either at dataset root

  3. or next to your events.tsv

  4. If an events.json already exists:

  5. keep existing descriptions

  6. add or merge the HED fields

Now open 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 and decide, for each column, whether it is categorical or value-based:

Column type What it means How to annotate
Categorical Fixed set of repeated labels (e.g. stimulus, button_press) Map each value to a HED string
Value-based Row-specific values (e.g. file paths, reaction times) Use a HED string with #

Typical columns: trial_type, event_type, stim_type, response, condition, stim_file

Step 5 — Find the correct HED tags

Use the HED schema browser to find tags. Do not invent tags — only use terms that exist in the schema.

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

You can use short form — write only the final node name:

Cross

instead of:

Item/Object/Geometric-object/2D-shape/Cross

Expand the HED Hierarchy section above for a guide to the main schema branches.

Step 6 — Write HED strings for categorical columns

Map each level to a HED string. Tags are comma-separated.

"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)"
  }
}

Use parentheses () to group related tags. Without grouping, meaning becomes ambiguous:

(Red, Triangle), (Blue, Square)   ← one red triangle and one blue square
Red, Triangle, Blue, Square       ← ambiguous

Step 7 — Write HED strings for value columns

For columns with row-specific values (file names, numbers), use # as a placeholder.

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

If events.tsv contains stim_file = faces/u032.bmp, the assembled annotation becomes:

(Image, Pathname/faces/u032.bmp)

Use exactly one # per value mapping.

Step 8 — Validate your dataset

Run the BIDS validator. Common warnings:

Warning Cause Fix
TAG_EXTENDED Non-standard tag used Replace with a schema tag
Syntax error Wrong commas or parentheses See Writing HED Correctly below

Step 9 — Final checklist

  • Tags are comma-separated
  • Parentheses are balanced
  • Tags come from the HED schema
  • # is used only in value-column mappings (exactly one per mapping)
  • Each level has exactly one HED string
  • No duplicate tags at the same level
  • Annotations describe scientific meaning, not just code labels

Complete minimal example

{
  "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/#)"
  }
}
Writing HED Correctly

HED is not just a vocabulary — it is a formal annotation syntax. Annotations that are scientifically meaningful but syntactically wrong may fail validation or behave unexpectedly in search and analysis tools.

1. A HED annotation is a comma-separated list of tags

Sensory-event, Visual-presentation, (Image, Face)

Correct:

Sensory-event, Visual-presentation, (Image, Face)

Wrong:

Sensory-event Visual-presentation (Image, Face)

2. HED strings are unordered at the same level

These mean the same thing:

Sensory-event, Visual-presentation, (Image, Face)
(Image, Face), Sensory-event, Visual-presentation

What matters is which tags are present and which are grouped together, not the order.

3. Parentheses show association

Parentheses show that tags belong together.

Without grouping — ambiguous:

Red, Triangle, Blue, Square

This does not tell us whether the stimulus contains a red triangle and a blue square, or a blue triangle and a red square.

Correct grouped version:

(Red, Triangle), (Blue, Square)

Use parentheses whenever tags should describe the same object, action, context, or event component.

4. Parentheses must be balanced and properly nested

Correct:

Sensory-event, (Visual-presentation, (Image, Face))

Wrong:

Sensory-event, (Visual-presentation, (Image, Face)
Sensory-event, Visual-presentation), (Image, Face)

5. Do not create empty tags or empty groups

These are invalid:

Sensory-event,, Visual-presentation
Sensory-event, ()
, Sensory-event, Visual-presentation
Sensory-event, Visual-presentation,

Avoid: double commas, empty parentheses, leading commas, trailing commas.

6. Do not repeat the same expression at the same level

Wrong:

Red, Blue, Red
(Image, Face), (Face, Image)

If the same tag or group appears twice at the same level, remove the duplicate.

7. Short-form and long-form tags

In normal annotation, short form is preferred:

Form Example
Short Square
Long Item/Object/Geometric-object/2D-shape/Rectangle/Square

Short form works only if the tag name is unique in the active schema set. If multiple schemas are used and a term is ambiguous, a fuller form may be needed.

8. Use tag extensions only when truly necessary

Beginners should avoid inventing new terms not in the schema. Most supposed extensions are spelling mistakes, unnecessary synonyms, or concepts already available elsewhere in the schema.

Before creating an extension:

  1. Search the schema browser carefully.
  2. Try broader or related terms.
  3. Use a more general tag plus additional properties if possible.

9. Some tags require values

Certain HED tags take a value written as a child using a slash:

Pathname/u032.bmp
Label/Face-image
ID/13

10. The # placeholder is for sidecars

The # symbol means "insert the actual value from the event table here":

{
  "stim_file": {
    "HED": "(Image, Pathname/#)"
  }
}

Rules:

  • Use # in sidecar entries for value columns only
  • A value-column HED string must contain exactly one #
  • Do not use # directly in row-wise event annotations

11. Categorical columns and value columns are handled differently

Categorical columns (fixed set of repeated values):

{
  "event_type": {
    "HED": {
      "show_face": "Sensory-event, Visual-presentation, Experimental-stimulus, (Image, Face)",
      "left_press": "Agent-action, Press, Left-side, (Experiment-participant, Human-agent)"
    }
  }
}

Value columns (row-specific values):

{
  "stim_file": {
    "HED": "(Image, Pathname/#)"
  }
}

12. Definitions let you reuse complex concepts

(Definition/Face-image, (Visual-presentation, Experimental-stimulus, (Image, Face)))

Refer to it later using:

Def/Face-image

Definitions are useful for: repeated event structures, trial structure, onset/offset pairs, cover stories, and keeping annotations readable.

13. Common HED writing mistakes

Mistake Example Why it is a problem
Missing comma Sensory-event Visual-presentation Tags must be comma-separated
Unmatched parentheses (Image, Face Groups must be balanced
Empty group () Empty groups are invalid
Duplicate tag Red, Blue, Red Repeated expressions are invalid
Multiple # in one value string Label/#, Pathname/# Only one placeholder allowed per value column
Placeholder with space Label/ # Placeholder must follow the slash directly
Unintended ambiguity Red, Square, Blue, Triangle Without grouping, associations are unclear

14. Checklist before saving an annotation

  • All tags are separated by commas
  • All parentheses are balanced and properly nested
  • Tags that belong together are grouped in parentheses
  • No duplicate tags at the same level
  • # is used only where a sidecar value should be inserted, and exactly once per value string
  • Tags come from the schema — not invented
  • The annotation describes the event in a way another lab could understand

15. A minimal writing pattern for beginners

For many neuroscience and psychology events, this template works well:

Event-tag, Presentation-or-action-tag, Task-role-tag, (Main-item, Important-properties)

Example stimulus:

Sensory-event, Visual-presentation, Experimental-stimulus, (Image, Face)

Example response:

Agent-action, Press, Correct-action, (Experiment-participant, Human-agent)

Practical BIDS Examples

In BIDS, the most maintainable way to annotate events is to place HED information in the JSON sidecar (events.json) rather than writing a custom HED string for every row. This approach is easier to read, maintain, validate, and reuse.

Example 1: fixation → face stimulus → button press

A beginner-friendly example similar to many EEG, MEG, and behavioral tasks.

events.tsv

onset   duration    trial_type  face_type   response    stim_file
1.2 0.5 fixation    n/a n/a cross.png
2.0 0.5 show_face   unfamiliar_face n/a faces/u032.bmp
2.7 n/a left_press  n/a correct
Column Meaning
trial_type Main event category
face_type Whether the shown face is familiar or unfamiliar
response Behavioral outcome
stim_file Path or file name of the visual stimulus

events.json

{
  "trial_type": {
    "Description": "Primary event type for each row",
    "Levels": {
      "fixation": "Fixation cross is displayed",
      "show_face": "A face image is shown",
      "left_press": "Participant presses the left response button"
    },
    "HED": {
      "fixation": "Sensory-event, Visual-presentation, Instructional, (Cross, White-color)",
      "show_face": "Sensory-event, Visual-presentation, Experimental-stimulus, (Image, Face)",
      "left_press": "Agent-action, Press, (Experiment-participant, Human-agent), Correct-action"
    }
  },
  "face_type": {
    "Description": "Type of face shown on face trials",
    "Levels": {
      "unfamiliar_face": "The face is unfamiliar to the participant"
    },
    "HED": {
      "unfamiliar_face": "(Condition-variable/Face-identity, Label/Unfamiliar-face)"
    }
  },
  "response": {
    "Description": "Behavioral classification of the participant response",
    "Levels": {
      "correct": "The response is correct"
    },
    "HED": {
      "correct": "Correct-action"
    }
  },
  "stim_file": {
    "Description": "Path to the stimulus file",
    "HED": "(Image, Pathname/#)"
  }
}

For the show_face row, the assembled annotation combines the main event type from trial_type, the condition detail from face_type, and the file path from stim_file — giving a much richer event description than the row alone.

Example 2: cover story / task context

Many experiments present stimuli within a task story or block context. HED can capture that context in a reusable way.

Scenario: Participants act as airport security screeners viewing baggage images to detect whether a target item is present. The cover story matters scientifically because it shapes attention, expectations, and decision strategy.

events.tsv

onset   duration    event_type  item_status response    stim_file
0.0 2.0 instruction_screen  n/a n/a instructions01.png
2.5 0.8 show_bag    no_target   n/a bags/bag001.png
3.4 n/a button_press    n/a hit
4.2 0.8 show_bag    target_present  n/a bags/bag002.png
5.0 n/a button_press    n/a miss

events.json

{
  "event_type": {
    "Description": "Main event type",
    "Levels": {
      "instruction_screen": "Instruction screen is shown",
      "show_bag": "Baggage image is shown",
      "button_press": "Participant button response"
    },
    "HED": {
      "instruction_screen": "Sensory-event, Visual-presentation, Instructional, (Image, Text)",
      "show_bag": "Sensory-event, Visual-presentation, Experimental-stimulus, (Image, Bag)",
      "button_press": "Agent-action, Press, (Experiment-participant, Human-agent)"
    }
  },
  "item_status": {
    "Description": "Whether the bag contains the target item",
    "Levels": {
      "no_target": "No target object is present",
      "target_present": "A target object is present"
    },
    "HED": {
      "no_target": "Distractor",
      "target_present": "Target"
    }
  },
  "response": {
    "Description": "Behavioral response category",
    "Levels": {
      "hit": "Participant correctly detects a target",
      "miss": "Participant fails to report a target"
    },
    "HED": {
      "hit": "Correct-action",
      "miss": "Incorrect-action"
    }
  },
  "stim_file": {
    "Description": "Stimulus file path",
    "HED": "(Image, Pathname/#)"
  }
}

Representing the cover story explicitly

If the cover story is central to the experiment, represent it using a reusable definition:

(Definition/Airport-security-task, (Task, Label/Airport-security-screening))

Then include it where needed:

Def/Airport-security-task

Example 3: oddball EEG experiment

events.tsv

onset   duration    event_type  stimulus_type   response    reaction_time
0.5 0.1 play_tone   standard    n/a n/a
1.7 0.1 play_tone   target  n/a n/a
2.1 n/a button_press    n/a correct 0.42
2.9 0.1 play_tone   standard    n/a n/a

events.json

{
  "event_type": {
    "Description": "Main type of event",
    "Levels": {
      "play_tone": "An auditory tone is presented",
      "button_press": "Participant presses the response button"
    },
    "HED": {
      "play_tone": "Sensory-event, Auditory-presentation, Experimental-stimulus, Tone",
      "button_press": "Agent-action, Press, (Experiment-participant, Human-agent)"
    }
  },
  "stimulus_type": {
    "Description": "Role of the tone in the oddball task",
    "Levels": {
      "standard": "Frequent non-target tone",
      "target": "Rare target tone"
    },
    "HED": {
      "standard": "Distractor",
      "target": "Target"
    }
  },
  "response": {
    "Description": "Outcome of the participant response",
    "Levels": {
      "correct": "Correct target response"
    },
    "HED": {
      "correct": "Correct-action"
    }
  },
  "reaction_time": {
    "Description": "Reaction time in seconds",
    "Units": "s",
    "HED": "(Agent-action, Label/Reaction-time, Duration/# s)"
  }
}

This structure clearly separates: the sensory event (play_tone), the task role (standard vs target), the participant response (button_press), the behavioral outcome (correct), and the reaction time value column.

Example 4: trial and block structure with reusable definitions

In many experiments, not every event is a stimulus or response — some define structure: block starts, trial starts, rest periods. HED is well suited for representing this.

Concept definitions:

(Definition/Task-block, (Time-block, Task))
(Definition/Trial-context, (Experimental-trial, Task))

events.tsv

onset   duration    event_type  block_type
0.0 30  block_start face_block
30.0    2   trial_start n/a
32.0    0.5 show_face   n/a
33.0    n/a button_press    n/a

events.json

{
  "event_type": {
    "HED": {
      "block_start": "Experiment-structure, Def/Task-block",
      "trial_start": "Experiment-structure, Def/Trial-context",
      "show_face": "Sensory-event, Visual-presentation, Experimental-stimulus, (Image, Face)",
      "button_press": "Agent-action, Press, (Experiment-participant, Human-agent)"
    }
  },
  "block_type": {
    "HED": {
      "face_block": "Label/Face-block"
    }
  }
}

How to think when writing events.json

Step What to do
1. Identify main columns trial_type, event_type, stim_type, response, condition, stim_file
2. Decide categorical vs value Map each category to a HED string; use # for row-wise values
3. Annotate meaning, not codes Describe what the event means scientifically, not just what the label says
4. Reuse via sidecar Put shared meaning in events.json once — not row by row

Common mistakes to avoid

Mistake Why it is a problem Better approach
Writing everything only in events.tsv Hard to maintain, hard to reuse Put shared meaning in events.json
Annotating only codes Other users cannot understand the experiment Annotate scientific meaning
Mixing categorical and value logic Validation becomes confusing Separate category maps from # value placeholders
Using overcomplicated tags too early Makes documentation harder to read Start simple, then refine
Ignoring task context Loses important experimental meaning Add context through properties or definitions

A compact template you can adapt

{
  "event_type": {
    "Description": "Main event type",
    "Levels": {
      "stimulus": "A stimulus is shown",
      "response": "Participant response"
    },
    "HED": {
      "stimulus": "Sensory-event, Visual-presentation, Experimental-stimulus, (Image, Face)",
      "response": "Agent-action, Press, (Experiment-participant, Human-agent)"
    }
  },
  "condition": {
    "Description": "Experimental condition",
    "Levels": {
      "target": "Target condition",
      "distractor": "Distractor condition"
    },
    "HED": {
      "target": "Target",
      "distractor": "Distractor"
    }
  },
  "stim_file": {
    "Description": "Stimulus file",
    "HED": "(Image, Pathname/#)"
  }
}