Release Notes

Release Notes#

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

None