Note This repository is primarily for managing the HED vocabulary. If you just want to annotate your data, please visit the HED organization website. The full HED specification is available at the HED specification website. A HED Documentation website is being developed to gather HED tools, case studies, and usage.
HED is an evolving framework for the description and formal annotation of events identified in time series data. The HED ecosystem includes a structured vocabulary (HED schema) together with tools for validation and for using HED annotations in data search, extraction, and analysis. While HED can be used to annotate any type of event, the current HED community focuses on annotation of events in human electrophysiological and behavioral data such as EEG, MEG, iEEG, eye-tracking, motion-capture, EKG, and audiovisual recording.
The HED schema vocabulary can be viewed at:
The following white papers give an overview of HED and how it is used.
Robbins, K., Truong, D., Jones, A., Callanan, I., & Makeig, S. (2021).
Building FAIR functionality: Annotating event-related imaging data using Hierarchical Event Descriptors (HED).
Neuroinformatics Special Issue Building the NeuroCommons. Neuroinformatics https://doi.org/10.1007/s12021-021-09537-4.
https://link.springer.com/article/10.1007/s12021-021-09537-4.
Robbins, K., Truong, D., Appelhoff, S., Delorme, A., & Makeig, S. (2021).
Capturing the nature of events and event context using Hierarchical Event Descriptors (HED).
NeuroImage Special Issue Practice in MEEG. NeuroImage 245 (2021) 118766.
https://www.sciencedirect.com/science/article/pii/S1053811921010387.
The HED system has gone through two major restructurings since the original system (HED-1G) was introduced. The following table shows the correspondence between HED schema version number and the design generation.
| schema version | release date | HED generation |
|---|---|---|
| 1.0 | 2011-01-01 | HED-1G |
| 4.0.0 | 2016-02-25 | HED-2G |
| 8.0.0 | 2021-08-07 | HED-3G |
HED-1G introduced the basic ideas of annotation using path strings and is still in use in the HEADIT archive.
A major redesign of HED, HED-2G released in 2016 (4.0.0 <= schema version < 8.0.0), orthongonalized the vocabularly terms and introduced parentheses for grouping modifiers with the terms they modify, resulting in much improved annotation.
The second majoring restructuring, HED-3G (7.x.x < schema version), has resulted in a dramatic improvement in capabilities, including the introduction of annotations of condition variables and experimental design within the data as well as the ability to handle event context and events with temporal extent.
Starting with version 8.0.0, HED has adopted the following rules for changing the semantic version major.minor.patch. These rules are based on the assumption that the short form will not require retagging for patch-level or minor-version changes. A validation error might occur during for patch-level or minor-version changes for changes or corrections in tag values or units.
| Change | Semantic-level |
|---|---|
| Major addition to HED functionality | Major |
| Tag deleted from schema. | Major |
| Unit or unit class removed from node. | Major |
| New attribute added to schema. | Minor |
| New unit class or unit added to schema. | Minor |
| New unit class added to node. | Minor |
| Node moved in schema without change in meaning. | Minor |
| Revision of description field in schema. | Patch |
| Correction of suggestedTag or relatedTag. | Patch |
| Correction of wiki syntax such as closing tags. | Patch |
HED schema is the structured vocabulary from which HED annotations base on. HED annotations consist of comma-separated path strings, selected from the schema. In the newest versions of HED, all individual nodes in the vocabulary are unique, so users can annotate by simply giving the last node in the path string rather than the entire path string: Red instead of Attribute/Sensory/Sensory-property/Visual/Color/CSS-color/Red-color/Red.
This repository contains the HED schema specification, where discussions on schema terms and syntax are held via Github issue mechanism and where HED-supporting tools can find machine-readable format of the schema. The HED schema is available in MediaWiki and XML.
The MediaWiki markdown format, stored in
hedwiki,
allows vocabulary developers to view and edit the vocabulary tree using a
human-readable markdown language available in Wikis and on GitHub repositories.
In addition, an expandable non-editable
HTML viewer is available
to help users explore the vocabulary.
All analysis and validation tools operate on an XML translation of the vocabulary
markdown document, stored in hedxml.
The documentation on this page refers specifically to the HED vocabulary and supporting tools. Additional documentataion is available on:
All of the HED software is open-source and organized into various repositories on the HED standards organization website:
The GUI tool CTagger is available to help users with the annotation process. CTagger can be used as a standalone application or can be called from EEGLAB via the hedtools plug-in to annotate an EEGLAB dataset/STUDY directly. Please refer to the linked repositories for more documentation on how to start HED-tagging using CTagger.
The current web-based HED tools include an online validator of spreadsheets (Excel or tsv)
containing HED tags. Schema tools are available for converting HED schema specifications between .mediawiki and
.xml formats.
Also available is a tool for checking for duplicate nodes in schema and for converting
HED annotations between short and long forms.
The current web-based HED tools are located at https://hedtags.ucsd.edu/hed.
The tools can be run locally using the runserver.py function the hedweb module
of the hed-python repository of
hed-standard.
Stable directory link for software requiring a HED schema for validation
HED-3G supports library schema, which are specialized vocabularies used in conjunction with the base vocabulary to support annotation of specialized datasets. Communities may develop and submit library schema. HED library schema are hosted on the repository: https://github.com/hed-standard/hed-schema-library
The following working document describes the origin of the descriptions associated with individual nodes in the HED-3G hierarchy. Many terms appear in the NCIT ontology (National Cancer Institute Thesaurus OBO edition).
Google doc with mapping of HED-3G term descriptions to existing ontology terms