ndx-hed: HED Integration for NWB

DOI PyPI version codecov

ndx-hed is a Neurodata Without Borders (NWB) extension that integrates HED (Hierarchical Event Descriptors) annotations into neurophysiology data files. HED provides a standardized vocabulary for annotating events and experimental metadata with precise, machine-readable semantic tags.

🚀 Quick Start

Get started with HED annotations in NWB files. Learn the basic concepts and see simple examples.

Getting Started
📚 API Reference

Complete API documentation for all classes and functions in the ndx-hed extension.

API Reference
🔧 Examples

Comprehensive runnable examples showing real-world usage patterns and best practices.

https://github.com/hed-standard/ndx-hed/tree/main/examples
📋 Extension Spec

Technical specification of the NWB extension data types and their structure.

ndx-hed

Installation

pip install -U ndx-hed

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

Quick Example

from pynwb import NWBFile
from ndx_hed import HedLabMetaData, HedTags
from datetime import datetime

# Create NWB file with HED metadata
nwbfile = NWBFile(
    session_description="Example session with HED annotations",
    identifier="example_session_001",
    session_start_time=datetime.now()
)

# Add HED schema metadata (required)
hed_metadata = HedLabMetaData(hed_schema_version="8.4.0")
nwbfile.add_lab_meta_data(hed_metadata)

# Add HED column to trials table
nwbfile.add_trial_column(
    name="HED",
    col_cls=HedTags,
    data=[],
    description="HED annotations for trials"
)

# Add trials with HED annotations
nwbfile.add_trial(
    start_time=0.0,
    stop_time=1.0,
    HED="Experimental-trial, (Sensory-event, Visual-presentation)"
)

Main Classes

Class

Purpose

Use Cases

HedLabMetaData

HED schema specification and lab-specific definitions

Required for all HED validation

HedTags

Row-specific HED annotations

Row-specific tags in any DynamicTable

HedValueVector

Column-wide HED templates

Shared annotations with value placeholders (#)

Key Features

🏷️ Standardized Annotations

Use HED’s hierarchical vocabulary to create precise, machine-readable annotations for events, stimuli, and behaviors.

✅ Built-in Validation

Comprehensive validation system ensures HED annotations conform to schema specifications.

🔄 BIDS Integration

Seamless conversion between BIDS events files and NWB EventsTable format with HED preservation.

🧩 NWB Integration

Works with any NWB DynamicTable and integrates with ndx-events EventsTable for comprehensive event annotation.

Resources