ndx-hed

Extension Specification

Version 0.2.0 Oct 24, 2026

This section provides the technical specification of the ndx-hed extension data types.

Core Data Types

The ndx-hed extension defines four data types for integrating HED annotations into NWB files:

HedLabMetaData

Purpose: Required container for HED schema metadata and custom definitions.

Extends: LabMetaData

Key Properties: - hed_schema_version (required): the HED schema version(s), either one version string such as "8.5.0", a comma-joined string of versions in one namespace such as "8.5.0,score_2.2.0", or a list of version strings such as ["8.5.0", "sc:score_2.2.0"] (stored in the file as the JSON array string, the form hedtools itself uses for a schema group) - hed_definitions (optional): Custom HED definitions as string

Usage: Must be added to NWBFile before using any HED annotations.

HedTags

Purpose: Row-specific HED annotations for dynamic tables.

Extends: VectorData

Key Properties: - name: Must be “HED” (enforced by constructor); at most one HedTags column per DynamicTable - data: Array of HED tag strings, one per table row - description: Description of the HED annotations

Usage: Add as a column to any DynamicTable (trials, units, epochs, EventsTable, etc.).

HedValueVector

Purpose: Column-wide HED templates with value placeholders.

Extends: VectorData

Key Properties: - name: Custom column name - data: Array of numeric/categorical values - hed: HED template string with # placeholder for values - description: Description of the data and HED annotation

Usage: Creates parametric HED annotations where the template applies to all values in the column.

HedDurationVector

Purpose: The duration column of an EventsTable with a HED template.

Extends: DurationVectorData (PyNWB core: durations in seconds, optional resolution)

Key Properties: - name: duration in an EventsTable - data: Event durations in seconds; NaN for an event without a duration - hed (required): HED template string with one # placeholder, such as (Duration/# s, (Sensory-event)) - description: Description of the durations and HED annotation

Usage: The duration column of an EventsTable whose durations carry HED; validated as a HedValueVector is.

YAML Schema Files

The complete technical specification is defined in YAML files:

• Schema Definition: spec/ndx-hed.extensions.yaml - Complete type definitions

• Namespace: spec/ndx-hed.namespace.yaml - Extension namespace configuration

View the complete specification: - Schema on GitHub - Namespace on GitHub

Example Usage Patterns

Basic Setup (required for all HED usage):

from ndx_hed import HedLabMetaData

# Add HED metadata to NWB file
hed_metadata = HedLabMetaData(hed_schema_version="8.5.0")
nwbfile.add_lab_meta_data(hed_metadata)

Row-specific annotations:

from ndx_hed import HedTags

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

Template-based annotations:

from ndx_hed import HedValueVector

# Create column with HED template
duration_col = HedValueVector(
    name="duration", data=[1.0, 1.5, 2.0],
    hed="(Duration/# s, (Sensory-event))",
    description="Trial durations with HED annotation"
)

For complete examples, see the examples directory.

Extension Dependencies

Required: - pynwb >= 4.2.0 (provides the core EventsTable and MeaningsTable from NWBEP001) - hdmf >= 6.2.0 - hedtools >= 1.3.0

Development and Contribution

The extension source code and issue tracking is available on GitHub.

For questions about HED itself, see the HED Standards Organization.