Release Notes

Release Notes#

Version 1.0.0#

Migration to PyNWB 4.0.0. NWBEP001 (EventsTable, MeaningsTable, TimestampVectorData, DurationVectorData, etc.) has been merged into PyNWB core, so ndx-hed no longer depends on the standalone ndx-events extension.

Breaking Changes

  • Requires pynwb>=4.0.0 and hdmf>=6.1.0; the ndx-events dependency has been removed. Import EventsTable, TimestampVectorData, and DurationVectorData from pynwb.event, and MeaningsTable from hdmf.common. Use the standard pynwb.NWBFile.

  • There is no CategoricalVectorData type (the categorical column type formerly provided by the ndx-events extension); any DynamicTable column can be annotated by a MeaningsTable.

  • A MeaningsTable is now bound to the column it annotates via a required target argument and is named "{column_name}_meanings" automatically. Attach it with table.add_meanings_table() and retrieve it with table.get_meanings_for_column(col_name).

  • HED column rules: a HedTags column must be named "HED" (so at most one per DynamicTable); inside a MeaningsTable it provides categorical HED, elsewhere per-row HED. A HedValueVector must not appear in a MeaningsTable. The HedValueVector schema doc was corrected (it previously stated “Always has the name HED”).

Changes

  • bids2nwb utilities updated for the new API (categorical columns are plain VectorData annotated by an attached MeaningsTable).

  • HedNWBValidator.validate_file() runs assembled (BIDS-style) validation on every DynamicTable except MeaningsTable. Categorical HED is validated as part of the target table it annotates (its levels are folded into that table’s sidecar), so a MeaningsTable is not validated on its own; it is only checked against the structural rule that it must not contain a HedValueVector column (which raises ValueError). Validation is temporal (timeline) when the table has an onset column and non-temporal otherwise.

  • HedLabMetaData is unchanged (still named “hed_schema”).

Version 0.2.0 (October 18, 2025)#

Major rewrite and expansion of the ndx-hed extension with three core classes and comprehensive tooling.

New Features

Core Classes#

  • HedLabMetaData: Required metadata container for storing HED schema version and optional custom definitions

    • Must be added to NWBFile before using any HED annotations

    • Supports both standard and library schemas

    • Includes DefinitionDict for custom HED definitions

    • Methods: get_hed_schema(), get_definition_dict(), add_definitions(), extract_definitions()

  • HedTags: VectorData subclass for row-specific HED annotations in DynamicTables

    • Must be named “HED” (enforced by constructor)

    • Stores one HED string per row

    • Works with any NWB DynamicTable (trials, units, epochs, etc.)

  • HedValueVector: VectorData subclass for column-wide HED templates with value placeholders

    • Stores numerical/categorical data with associated HED annotation template

    • Uses # placeholder for values (e.g., “Duration/# s”)

    • HED annotation applies to entire column

Validation System#

  • HedNWBValidator: Comprehensive validation class for HED annotations in NWB files

    • validate_file(): Validates entire NWBFile

    • validate_dynamic_table(): Validates specific DynamicTable

    • validate_hed_tags(): Validates individual HedTags column

    • validate_hed_value_vector(): Validates HedValueVector columns

    • Supports both in-memory and file-based validation

BIDS Integration#

  • Bidirectional BIDS ↔ NWB conversion utilities in utils/bids2nwb.py:

    • extract_meanings(): Converts BIDS JSON sidecars to meanings dictionary

    • get_categorical_meanings(): Creates MeaningsTable from BIDS categorical columns

    • get_events_table(): Converts BIDS events.tsv + sidecar to NWB EventsTable

    • get_bids_events(): Converts EventsTable back to BIDS format (DataFrame + sidecar)

    • extract_definitions(): Extracts HED definitions from BIDS sidecars

ndx-events Integration#

  • Full support for EventsTable, MeaningsTable, CategoricalVectorData

  • Three integration patterns:

    1. Direct HED column for event-specific annotations

    2. HedValueVector columns for shared annotations with values

    3. Categorical columns with HED in MeaningsTable

Examples

Seven comprehensive runnable examples demonstrating all features:

  • 01_basic_hed_classes.py: Introduction to HedLabMetaData, HedTags, and HedValueVector

  • 02_trials_with_hed.py: Adding HED annotations to NWB trials table

  • 03_events_table_integration.py: Three patterns for EventsTable integration

  • 04_bids_conversion.py: Bidirectional BIDS ↔ NWB conversion workflows

  • 05_hed_validation.py: Comprehensive validation examples

  • 06_complete_workflow.py: End-to-end workflow with file I/O

  • 07_hed_definitions.py: Custom HED definitions and expansion

Dependencies

  • Updated to hedtools>=0.7.1 (released to PyPI)

  • pynwb>=2.8.2

  • hdmf>=3.14.1

  • Optional: ndx-events>=0.4.0 for EventsTable support

Testing

  • 116+ comprehensive test cases

  • Full coverage of all core classes and utilities

  • File I/O roundtrip testing

  • Validation testing with valid and invalid HED

  • BIDS conversion roundtrip testing

  • Definition handling and persistence testing

Breaking Changes from 0.1.0

  • HedTags constructor changes: Removed hed_version parameter (now uses HedLabMetaData)

  • New requirement: HedLabMetaData must be added to NWBFile before using HED annotations

  • Name enforcement: HedTags must be named “HED”, HedLabMetaData must be named “hed_schema”

Documentation

  • Updated user guide for 0.2.0 architecture

  • Comprehensive example suite with runnable code

  • Updated README with Quick Start guide

Version 0.1.0 (July 25, 2024)#

Initial Release

  • Implements a HedTags class that extends NWB VectorData

  • Validates tags in the constructor and as they are added

  • The HedTags class can be used alone or added to any DynamicTable

  • Initial release only supports string HED version specifications, not tuples or lists

Features

  • Basic HED tag validation

  • Integration with NWB DynamicTables

  • Support for standard HED schemas

Limitations

  • No centralized schema management

  • No support for custom definitions

  • No validation utilities

  • No BIDS integration