API Reference

This section provides detailed API documentation for the ndx-hed extension.

Core Classes

HedLabMetaData

class ndx_hed.HedLabMetaData(hed_schema_version, definitions=None)

Bases: LabMetaData

Stores the HED schema version for the NWBFile. The object name is fixed to “hed_schema”.

Parameters:

• hed_schema_version (str) – The version of HED used by this data.

• definitions (str) – A string containing one or more HED definitions.

__init__(hed_schema_version, definitions=None)

Parameters:

• hed_schema_version (str) – The version of HED used by this data.

• definitions (str) – A string containing one or more HED definitions.

property hed_schema_version

The version of HED used by this data.

property definitions

Get the definitions as a string.

add_definitions(defs: str | list | dict | None)

Add new definitions to the existing definition dictionary.

Parameters:

defs (str or list or dict or None) – A string containing one or more HED definitions, a list of such strings, a dict of DefinitionEntry objects, or None. If None or empty, no action is taken.

get_definition_dict() → DefinitionDict

Get the internal DefinitionDict object.

Returns:

The internal DefinitionDict containing all definitions.

Return type:

DefinitionDict

get_hed_schema_version()

Get the HED schema version string.

Returns:

The HED schema version used by this metadata object.

Return type:

str

get_hed_schema() → HedSchema | HedSchemaGroup

Get the loaded HED schema object.

Returns:

The loaded HED schema object.

Return type:

HedSchema or HedSchemaGroup

extract_definitions() → str

Extract definitions as string (for serialization).

Returns:

A string representation of the definitions.

Return type:

str

static __new__(cls, *args, **kwargs)

Static method of the object class called by Python to create the object first and then

__init__() is called to initialize the object’s attributes.

NOTE: this method is called directly from ObjectMapper.__new_container__ during the process of constructing the object from builders that are read from a file.

all_children()

Get a list of all child objects and their child objects recursively.

If the object has an object_id, the object will be added to “ret” to be returned. If that object has children, they will be added to the “stack” in order to be: 1) Checked to see if has an object_id, if so then add to “ret” 2) Have children that will also be checked

property all_objects

Get a LabelledDict that indexed all child objects and their children by object ID.

property children

property container_source

The source of this Container

property css_style: str

CSS styles for the HTML representation.

property data_type

Return the spec data type associated with this container, i.e., the neurodata_type.

property fields

Subclasses use this class attribute to add properties to autogenerate. fields allows for lists and for dicts with the keys {‘name’, ‘child’, ‘required_name’, ‘doc’, ‘settable’}. 1. name: The name of the field property 2. child: A boolean value to set the parent/child relationship between the field property and the container. 3. required_name: The name the field property must have such that name matches required_name. 4. doc: Documentation of the field property 5. settable: If true, a setter function is created so that the field can be changed after creation.

generate_new_id(recurse=True)

Changes the object ID of this Container and all of its children to a new UUID string.

Parameters:

recurse (bool) – whether or not to change the object ID of this container’s children

get_ancestor(neurodata_type=None)

Traverse parent hierarchy and return first instance of the specified data_type

Parameters:

neurodata_type (str) – the data_type to search for

get_ancestors()

classmethod get_fields_conf()

get_read_io()

Get the io object used to read this container.

If self.read_io is None, this function will iterate through the parents and return the first io object found on a parent container

Returns:

The HDMFIO object used to read this container. Returns None in case no io object is found, e.g., in case this container has not been read from file.

property js_script: str

JavaScript for the HTML representation.

property modified

property name

The name of this Container

namespace = 'ndx-hed'

neurodata_type = 'HedLabMetaData'

property object_id

property parent

The parent Container of this Container

property read_io

The HDMFIO object used for reading the container.

This property will typically be None if this Container is not a root Container (i.e., if parent is not None). Use get_read_io instead if you want to retrieve the HDMFIO object used for reading from the parent container.

reset_parent()

Reset the parent of this Container to None and remove the Container from the children of its parent.

Use with caution. This can result in orphaned containers and broken links.

set_data_io(dataset_name: str, data_io_class: type[DataIO], data_io_kwargs: dict, data_chunk_iterator_class: type[AbstractDataChunkIterator] | None = None, data_chunk_iterator_kwargs: dict | None = None)

Apply DataIO object to a dataset field of the Container.

Parameters:

• dataset_name (str) – Name of dataset to wrap in DataIO

• data_io_class (type[DataIO]) – Class to use for DataIO, e.g. H5DataIO or ZarrDataIO

• data_io_kwargs (dict) – keyword arguments passed to the constructor of the DataIO class.

• data_chunk_iterator_class (type[AbstractDataChunkIterator]) – Class to use for DataChunkIterator. If None, no DataChunkIterator is used.

• data_chunk_iterator_kwargs (dict) – keyword arguments passed to the constructor of the DataChunkIterator class.

Notes

If data_chunk_iterator_class is not None, the data is wrapped in the DataChunkIterator before being wrapped in the DataIO. This allows for rewriting the backend configuration of hdf5 datasets.

set_modified(modified=True)

Parameters:

modified (bool) – whether or not this Container has been modified

classmethod type_hierarchy()

HedTags

class ndx_hed.HedTags(name='HED', description='Column that stores HED tags as text annotating their respective row.', data=[])

Bases: VectorData

Column storing HED (Hierarchical Event Descriptors) annotations for a row. A HED string is a comma-separated, and possibly parenthesized list of HED tags selected from a valid HED vocabulary as specified by the NWBFile field HedVersion.

A HedTags column must be named “HED” (enforced by the constructor). There is at most one HedTags column per DynamicTable (a consequence of the fixed name). HED-aware code also identifies HED columns by their neurodata type (isinstance(col, HedTags)).

Parameters:

• name (str) – The name of this column. Must be ‘HED’ (the default).

• description (str) – a description for this column

• data (ndarray or list or tuple or Dataset or Series or ExtensionArray or StrDataset or HDMFDataset or AbstractDataChunkIterator or DataIO) – a dataset where the first dimension is a concatenation of multiple vectors

__init__(name='HED', description='Column that stores HED tags as text annotating their respective row.', data=[])

Parameters:

• name (str) – The name of this column. Must be ‘HED’ (the default).

• description (str) – a description for this column

• data (ndarray or list or tuple or Dataset or Series or ExtensionArray or StrDataset or HDMFDataset or AbstractDataChunkIterator or DataIO) – a dataset where the first dimension is a concatenation of multiple vectors

add_row(val)

Append a data value to this column.

Parameters:

val (str) – the value to add to this column. Should be a valid HED string – just forces string.

static __new__(cls, *args, **kwargs)

Static method of the object class called by Python to create the object first and then

__init__() is called to initialize the object’s attributes.

NOTE: this method is called directly from ObjectMapper.__new_container__ during the process of constructing the object from builders that are read from a file.

all_children()

Get a list of all child objects and their child objects recursively.

If the object has an object_id, the object will be added to “ret” to be returned. If that object has children, they will be added to the “stack” in order to be: 1) Checked to see if has an object_id, if so then add to “ret” 2) Have children that will also be checked

property all_objects

Get a LabelledDict that indexed all child objects and their children by object ID.

append(arg)

property children

property container_source

The source of this Container

property data

data_type = 'VectorData'

property description

a description for this column

extend(ar, **kwargs)

Add all elements of the iterable arg to the end of this VectorData.

Each subclass of VectorData should have its own extend method to ensure functionality and efficiency.

Parameters:

arg – The iterable to add to the end of this VectorData

property fields

Subclasses use this class attribute to add properties to autogenerate. fields allows for lists and for dicts with the keys {‘name’, ‘child’, ‘required_name’, ‘doc’, ‘settable’}. 1. name: The name of the field property 2. child: A boolean value to set the parent/child relationship between the field property and the container. 3. required_name: The name the field property must have such that name matches required_name. 4. doc: Documentation of the field property 5. settable: If true, a setter function is created so that the field can be changed after creation.

generate_new_id(recurse=True)

Changes the object ID of this Container and all of its children to a new UUID string.

Parameters:

recurse (bool) – whether or not to change the object ID of this container’s children

get(key, **kwargs)

Retrieve elements from this VectorData

Parameters:

• key – Selection of the elements

• kwargs – Ignored

get_ancestor(data_type=None)

Traverse parent hierarchy and return first instance of the specified data_type

Parameters:

data_type (str) – the data_type to search for

get_ancestors()

classmethod get_fields_conf()

get_meanings()

Get the MeaningsTable associated with this VectorData column, if one exists.

Returns:

The MeaningsTable for this column, or None if this column

is not part of a DynamicTable or has no associated MeaningsTable.

Return type:

MeaningsTable

get_read_io()

Get the io object used to read this container.

If self.read_io is None, this function will iterate through the parents and return the first io object found on a parent container

Returns:

The HDMFIO object used to read this container. Returns None in case no io object is found, e.g., in case this container has not been read from file.

property modified

property name

The name of this Container

namespace = 'ndx-hed'

neurodata_type = 'HedTags'

property object_id

property parent

The parent Container of this Container

property read_io

The HDMFIO object used for reading the container.

This property will typically be None if this Container is not a root Container (i.e., if parent is not None). Use get_read_io instead if you want to retrieve the HDMFIO object used for reading from the parent container.

reset_parent()

Reset the parent of this Container to None and remove the Container from the children of its parent.

Use with caution. This can result in orphaned containers and broken links.

set_data_io(data_io_class: type[DataIO], data_io_kwargs: dict, data_chunk_iterator_class: type[AbstractDataChunkIterator] | None = None, data_chunk_iterator_kwargs: dict = None) → None

Apply DataIO object to the data held by this Data object.

Parameters:

• data_io_class (type[DataIO]) – The DataIO to apply to the data held by this Data.

• data_io_kwargs (dict) – The keyword arguments to pass to the DataIO.

• data_chunk_iterator_class (type[AbstractDataChunkIterator]) – The DataChunkIterator to use for the DataIO. If None, no DataChunkIterator is used.

• data_chunk_iterator_kwargs (dict) – The keyword arguments to pass to the DataChunkIterator.

Notes

If data_chunk_iterator_class is not None, the data is wrapped in the DataChunkIterator before being wrapped in the DataIO. This allows for rewriting the backend configuration of hdf5 datasets.

set_modified(modified=True)

Parameters:

modified (bool) – whether or not this Container has been modified

property shape

Get the shape of the data represented by this container :return: Shape tuple :rtype: tuple of ints

transform(func)

Transform data from the current underlying state.

This function can be used to permanently load data from disk, or convert to a different representation, such as a torch.Tensor

Parameters:

func (function) – a function to transform data

classmethod type_hierarchy()

HedValueVector

class ndx_hed.HedValueVector(name, description, hed, data=[])

Bases: VectorData

Column storing values and a single HED annotation that applies to all values in the column. A HED string is a comma-separated, and possibly parenthesized list of HED tags selected from a valid HED vocabulary as specified by the NWBFile field HedVersion.

A HedValueVector column may have any name. HED-aware code identifies these columns by their neurodata type (isinstance(col, HedValueVector)), not by the column name.

Parameters:

• name (str) – the name of this VectorData

• description (str) – a description for this column

• hed (str) – HED annotation template for all values in the column

• data (ndarray or list or tuple or Dataset or Series or ExtensionArray or StrDataset or HDMFDataset or AbstractDataChunkIterator or DataIO) – a dataset where the first dimension is a concatenation of multiple vectors

__init__(name, description, hed, data=[])

Parameters:

• name (str) – the name of this VectorData

• description (str) – a description for this column

• hed (str) – HED annotation template for all values in the column

• data (ndarray or list or tuple or Dataset or Series or ExtensionArray or StrDataset or HDMFDataset or AbstractDataChunkIterator or DataIO) – a dataset where the first dimension is a concatenation of multiple vectors

property hed

Return the HED annotation template for this column.

static __new__(cls, *args, **kwargs)

Static method of the object class called by Python to create the object first and then

__init__() is called to initialize the object’s attributes.

NOTE: this method is called directly from ObjectMapper.__new_container__ during the process of constructing the object from builders that are read from a file.

add_row(val)

Append a data value to this VectorData column

Parameters:

val (None) – the value to add to this column

all_children()

Get a list of all child objects and their child objects recursively.

If the object has an object_id, the object will be added to “ret” to be returned. If that object has children, they will be added to the “stack” in order to be: 1) Checked to see if has an object_id, if so then add to “ret” 2) Have children that will also be checked

property all_objects

Get a LabelledDict that indexed all child objects and their children by object ID.

append(arg)

property children

property container_source

The source of this Container

property data

data_type = 'VectorData'

property description

a description for this column

extend(ar, **kwargs)

Add all elements of the iterable arg to the end of this VectorData.

Each subclass of VectorData should have its own extend method to ensure functionality and efficiency.

Parameters:

arg – The iterable to add to the end of this VectorData

property fields

Subclasses use this class attribute to add properties to autogenerate. fields allows for lists and for dicts with the keys {‘name’, ‘child’, ‘required_name’, ‘doc’, ‘settable’}. 1. name: The name of the field property 2. child: A boolean value to set the parent/child relationship between the field property and the container. 3. required_name: The name the field property must have such that name matches required_name. 4. doc: Documentation of the field property 5. settable: If true, a setter function is created so that the field can be changed after creation.

generate_new_id(recurse=True)

Changes the object ID of this Container and all of its children to a new UUID string.

Parameters:

recurse (bool) – whether or not to change the object ID of this container’s children

get(key, **kwargs)

Retrieve elements from this VectorData

Parameters:

• key – Selection of the elements

• kwargs – Ignored

get_ancestor(data_type=None)

Traverse parent hierarchy and return first instance of the specified data_type

Parameters:

data_type (str) – the data_type to search for

get_ancestors()

classmethod get_fields_conf()

get_meanings()

Get the MeaningsTable associated with this VectorData column, if one exists.

Returns:

The MeaningsTable for this column, or None if this column

is not part of a DynamicTable or has no associated MeaningsTable.

Return type:

MeaningsTable

get_read_io()

Get the io object used to read this container.

If self.read_io is None, this function will iterate through the parents and return the first io object found on a parent container

Returns:

The HDMFIO object used to read this container. Returns None in case no io object is found, e.g., in case this container has not been read from file.

property modified

property name

The name of this Container

namespace = 'ndx-hed'

neurodata_type = 'HedValueVector'

property object_id

property parent

The parent Container of this Container

property read_io

The HDMFIO object used for reading the container.

This property will typically be None if this Container is not a root Container (i.e., if parent is not None). Use get_read_io instead if you want to retrieve the HDMFIO object used for reading from the parent container.

reset_parent()

Reset the parent of this Container to None and remove the Container from the children of its parent.

Use with caution. This can result in orphaned containers and broken links.

set_data_io(data_io_class: type[DataIO], data_io_kwargs: dict, data_chunk_iterator_class: type[AbstractDataChunkIterator] | None = None, data_chunk_iterator_kwargs: dict = None) → None

Apply DataIO object to the data held by this Data object.

Parameters:

• data_io_class (type[DataIO]) – The DataIO to apply to the data held by this Data.

• data_io_kwargs (dict) – The keyword arguments to pass to the DataIO.

• data_chunk_iterator_class (type[AbstractDataChunkIterator]) – The DataChunkIterator to use for the DataIO. If None, no DataChunkIterator is used.

• data_chunk_iterator_kwargs (dict) – The keyword arguments to pass to the DataChunkIterator.

Notes

If data_chunk_iterator_class is not None, the data is wrapped in the DataChunkIterator before being wrapped in the DataIO. This allows for rewriting the backend configuration of hdf5 datasets.

set_modified(modified=True)

Parameters:

modified (bool) – whether or not this Container has been modified

property shape

Get the shape of the data represented by this container :return: Shape tuple :rtype: tuple of ints

transform(func)

Transform data from the current underlying state.

This function can be used to permanently load data from disk, or convert to a different representation, such as a torch.Tensor

Parameters:

func (function) – a function to transform data

classmethod type_hierarchy()

Validation Utilities

HedNWBValidator

class ndx_hed.utils.hed_nwb_validator.HedNWBValidator(hed_metadata: HedLabMetaData)

Bases: object

A validator class for HED tags in NWB DynamicTable objects.

This class provides methods to validate HED tags in various NWB data structures using HED schema information stored in HedLabMetaData.

Initialize the HedNWBValidator with HED metadata.

Parameters:

hed_metadata (HedLabMetaData) – The HED lab metadata containing schema information. Must be a valid HedLabMetaData instance with a loaded HED schema. If the HedLabMetaData was constructed successfully, it is guaranteed to have a valid schema.

Raises:

ValueError – If hed_metadata is not an instance of HedLabMetaData

Notes

HedLabMetaData validates the schema during its own construction, so if a HedLabMetaData instance exists, it is guaranteed to have a valid HED schema and version. No additional validation is needed here.

STRUCTURAL_SIDECAR_CODES = frozenset({'SIDECAR_BRACES_INVALID', 'SIDECAR_INVALID'})

__init__(hed_metadata: HedLabMetaData)

Initialize the HedNWBValidator with HED metadata.

Parameters:

hed_metadata (HedLabMetaData) – The HED lab metadata containing schema information. Must be a valid HedLabMetaData instance with a loaded HED schema. If the HedLabMetaData was constructed successfully, it is guaranteed to have a valid schema.

Raises:

ValueError – If hed_metadata is not an instance of HedLabMetaData

Notes

HedLabMetaData validates the schema during its own construction, so if a HedLabMetaData instance exists, it is guaranteed to have a valid HED schema and version. No additional validation is needed here.

validate_table(table: DynamicTable, error_handler: ErrorHandler | None = None) → List[Dict[str, Any]]

Validates all HedTags columns in a DynamicTable using the provided HED schema metadata.

Parameters:

• table (DynamicTable) – The dynamic table to validate

• error_handler (ErrorHandler, optional) – An ErrorHandler instance for collecting errors. If None, a new instance will be created.

Returns:

A consolidated list of validation issues from all HedTags columns

Return type:

List[Dict[str, Any]]

validate_vector(hed_tags: HedTags, error_handler: ErrorHandler | None = None) → List[Dict[str, Any]]

Validates a HedTags column using the provided HED schema metadata.

Parameters:

• hed_tags (HedTags) – The HedTags column to validate

• error_handler (ErrorHandler, optional) – An ErrorHandler instance for collecting errors. If None, a new instance will be created.

Returns:

A list of validation issues found in the HedTags column

Return type:

List[Dict[str, Any]]

validate_value_vector(hed_values: HedValueVector, error_handler: ErrorHandler | None = None) → List[Dict[str, Any]]

Validates a HedValueVector column using the provided HED schema metadata.

Parameters:

• hed_values (HedValueVector) – The HedValueVector column to validate

• error_handler (ErrorHandler, optional) – An ErrorHandler instance for collecting errors. If None, a new instance will be created.

Returns:

A list of validation issues found in the HedValueVector column

Return type:

List[Dict[str, Any]]

validate_events(events: EventsTable, error_handler: ErrorHandler | None = None) → List[Dict[str, Any]]

Validates HED tags in an EventsTable by converting it to BIDS format and validating the events.

This function extracts the BIDS-formatted DataFrame and JSON sidecar from the EventsTable using get_bids_tabular(), then validates the HED tags contained within using the provided HED schema metadata.

Parameters:

• events (EventsTable) – The EventsTable to validate containing HED tags

• error_handler (ErrorHandler, optional) – An ErrorHandler instance for collecting errors. If None, a new instance will be created.

Returns:

A list of validation issues found in the EventsTable HED tags

Return type:

List[Dict[str, Any]]

Raises:

ValueError – If the EventsTable is invalid or cannot be converted to BIDS format

Notes

This function uses get_bids_tabular() to extract BIDS-formatted data from the EventsTable, then applies HED validation to the extracted event annotations. The validation follows BIDS-HED standards for event annotation validation.

validate_file(nwbfile: NWBFile, error_handler: ErrorHandler | None = None) → List[Dict[str, Any]]

Validates all HED tags in an NWB file by iterating through all DynamicTable objects.

This method first checks that HedLabMetaData is defined in the NWB file and that its schema version matches the validator’s. Then it validates every DynamicTable except MeaningsTable using assembled (BIDS-style) validation (see _validate_assembled): the table is converted to a dataframe + sidecar and validated with TabularInput, which performs temporal (timeline) validation when the table has an onset column and non-temporal validation otherwise. A MeaningsTable is not validated on its own – its categorical HED is validated as part of the table whose column it annotates – but it is checked against the structural rule that it must not contain a HedValueVector column (a violation raises ValueError).

Parameters:

• nwbfile (NWBFile) – The NWB file to validate

• error_handler (ErrorHandler, optional) – An ErrorHandler instance for collecting errors. If None, a new instance will be created.

Returns:

A consolidated list of validation issues from all tables in the file

Return type:

List[Dict[str, Any]]

Raises:

• ValueError – If nwbfile is not a valid NWBFile instance

• ValueError – If a MeaningsTable contains a HedValueVector column

• HedFileError – If HedLabMetaData is missing or invalid in the NWB file

• HedFileError – If the HED schema version in the NWB file does not match the validator’s schema version

BIDS Conversion Utilities

These utilities support bidirectional conversion between BIDS events and NWB EventsTable format.

ndx_hed.utils.bids2nwb.extract_definitions(sidecar_data: dict, hed_schema: HedSchema | HedSchemaGroup) → tuple

Extracts definitions from a HED sidecar JSON data using the provided HED schema.

Parameters:

• sidecar_data (dict) – A dictionary representing the loaded HED Sidecar JSON data.

• hed_schema (HedSchema or HedSchemaGroup) – The HED schema object for validation and processing.

Returns:

A tuple containing:

• DefinitionDict: A dictionary of definitions extracted from the sidecar.

• list: A list of validation issues found during extraction.

Return type:

tuple

ndx_hed.utils.bids2nwb.extract_meanings(sidecar_data: dict) → dict

Converts a HED sidecar JSON data to a meanings dictionary.

Parameters:

sidecar_data (dict) – A dictionary representing the loaded HED Sidecar JSON data.

Returns:

A meanings dictionary with keys “categorical” and “value”

• ”categorical”: dict mapping column names to their raw sidecar column-info dict (Levels and/or HED). A MeaningsTable cannot be built here because, as of PyNWB 4.0.0, a MeaningsTable requires the target VectorData column object; the MeaningsTable is created later in get_events_table once the column exists.

• ”value”: dict mapping column names to HED strings

Return type:

dict

ndx_hed.utils.bids2nwb.get_categorical_meanings(target_column: VectorData, column_info: dict) → MeaningsTable

Converts a categorical column info dict to a MeaningsTable annotating a target column.

As of PyNWB 4.0.0, a MeaningsTable is bound to the VectorData column it annotates and its name is derived automatically as “{target_column.name}_meanings”.

Parameters:

• target_column (VectorData) – The column object this MeaningsTable annotates. Must already be a column of the DynamicTable that the MeaningsTable will be added to.

• column_info (dict) – The column info dictionary from the sidecar (Levels and/or HED).

Returns:

The constructed MeaningsTable object (name “{target_column.name}_meanings”).

Return type:

MeaningsTable

ndx_hed.utils.bids2nwb.get_events_table(name: str, description: str, df: DataFrame, meanings: dict) → EventsTable

Converts a pandas DataFrame and meanings dictionary to an EventsTable.

Parameters:

• name (str) – The name of the EventsTable.

• description (str) – The description of the EventsTable.

• df (pd.DataFrame) – The DataFrame containing event data.

• meanings (dict) – The meanings dictionary with keys “categorical” and “value”. The “categorical” values are raw sidecar column-info dicts (see extract_meanings).

Returns:

The constructed EventsTable object. Categorical columns are stored as plain VectorData columns, each annotated by a MeaningsTable attached to the table.

Return type:

EventsTable

ndx_hed.utils.bids2nwb.get_bids_tabular(table: DynamicTable) → tuple

Converts a DynamicTable to a BIDS-style tabular representation (DataFrame and JSON sidecar).

Works for any DynamicTable (an EventsTable or a plain DynamicTable). It is not meant for a MeaningsTable, whose HED is consumed while assembling the table whose column it annotates. A TimestampVectorData column is renamed to onset so that downstream BIDS-HED validation treats the table as a timeline (temporal) file.

Parameters:

table (DynamicTable) – The table to convert.

Returns:

A tuple containing:

• pd.DataFrame: The table data with BIDS column names (onset, duration, etc.)

• dict: The JSON sidecar data with column metadata, levels, and HED annotations

Return type:

tuple