Introduction to HEDTools

What is HED?

HED (Hierarchical Event Descriptors) is a framework for systematically describing events and experimental metadata in machine-actionable form. HED provides:

  • Controlled vocabulary for annotating experimental data and events

  • Standardized infrastructure enabling automated analysis and interpretation

  • Integration with major neuroimaging standards (BIDS and NWB)

For more information, visit the HED project homepage and the resources page. The table-remodeler tools are now in a separate repository.

What is HEDTools?

The hedtools Python package (hed-python repository) provides:

  • Core validation of HED annotations against schema specifications

  • BIDS integration for neuroimaging dataset processing

  • Analysis tools for event summarization, temporal processing, and tag analysis

  • HED schema tools for validating, comparing and converting HED schemas

  • Command-line interface for scripting and automation

  • Jupyter notebooks for interactive analysis workflows

Installation

For Jupyter notebook examples

The example notebooks are only available in the GitHub repository. Choose one of these options:

Option 1: Clone the full repository

git clone https://github.com/hed-standard/hed-python.git
cd hed-python
pip install -r requirements.txt
pip install jupyter notebook
# Notebooks are in: examples/

Option 2: Download just the examples directory

svn export https://github.com/hed-standard/hed-python/trunk/examples
cd examples
pip install hedtools jupyter notebook

See examples/README.md for detailed notebook documentation.

From GitHub (latest development version)

pip install git+https://github.com/hed-standard/hed-python/@main

For development

Clone the repository and install in editable mode:

git clone https://github.com/hed-standard/hed-python.git
cd hed-python
pip install -e .

Python requirements

  • Python 3.10 or later is required

  • Core dependencies: pandas, numpy, defusedxml, openpyxl

  • Jupyter support: Install with pip install jupyter notebook

Getting help

Documentation resources

Support

Quick start

Basic validation example

from hed import HedString, load_schema, get_printable_issue_string

# Load the latest HED schema
schema = load_schema('8.4.0')

# Create and validate a HED string
hed_string = HedString("Sensory-event, Visual-presentation, (Onset, (Red, Square))", schema)
issues = hed_string.validate()

if issues:
    print(get_printable_issue_string(issues, "Validation issues found:"))
else:
    print("✓ HED string is valid!")

BIDS dataset validation

from hed.tools import BidsDataset

# Load and validate a BIDS dataset
dataset = BidsDataset("path/to/bids/dataset")  # the description has schema version
issues = dataset.validate()

if issues:
    print(get_printable_issue_string(issues, "Validation issues found:"))
else:
    print("✓ Dataset HED annotations are valid!")

Working with sidecars

from hed import Sidecar, load_schema_version

# Load and validate a BIDS JSON sidecar
schema = load_schema_version("8.4.0")
sidecar = Sidecar("task-rest_events.json")
issues = sidecar.validate(schema)

Next steps