ndx-hed: HED Integration for NWB

None

ndx-hed: HED Integration for NWB#

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/VisLab/ndx-hed/tree/main/examples

📋 Extension Spec

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

ndx-hed

Installation#

Python

pip install -U ndx-hed

Development

git clone https://github.com/VisLab/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#

HED Standards Organization - Official HED specification and resources
HED Annotation in NWB Guide - Detailed usage guide
NWB Documentation - PyNWB library documentation
ndx-events Extension - Complementary events extension