API Reference

None

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)[source]#

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)[source]#
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)[source]#

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[source]#

Get the internal DefinitionDict object.

Returns:

The internal DefinitionDict containing all definitions.

Return type:

DefinitionDict

get_hed_schema_version()[source]#

Get the HED schema version string.

Returns:

The HED schema version used by this metadata object.

Return type:

str

get_hed_schema() → HedSchema | HedSchemaGroup[source]#

Get the loaded HED schema object.

Returns:

The loaded HED schema object.

Return type:

HedSchema or HedSchemaGroup

extract_definitions() → str[source]#

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 = None, data_chunk_iterator_class: Type[AbstractDataChunkIterator] | None = None, data_chunk_iterator_kwargs: dict = None, **kwargs)#

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.

  • **kwargs – DEPRECATED. Use data_io_kwargs instead. kwargs are passed to the constructor of the DataIO 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=[])[source]#

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.

Parameters:
__init__(name='HED', description='Column that stores HED tags as text annotating their respective row.', data=[])[source]#
Parameters:
add_row(val)[source]#

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_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=[])[source]#

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.

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 StrDataset or HDMFDataset or AbstractDataChunkIterator or DataIO) – a dataset where the first dimension is a concatenation of multiple vectors

__init__(name, description, hed, data=[])[source]#
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 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_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)[source]#

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.

__init__(hed_metadata: HedLabMetaData)[source]#

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]][source]#

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]][source]#

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]][source]#

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]][source]#

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_events(), 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_events() 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]][source]#

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

This method first checks if HedLabMetaData is defined in the NWB file. If not found, it returns an issue about invalid schema. Then it iterates through all DynamicTable objects in the file, calling validate_events for EventsTable objects and validate_table for other DynamicTable objects.

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

  • 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[source]#

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[source]#

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 a dict of {category: (description, HED string)}

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

Return type:

dict

ndx_hed.utils.bids2nwb.get_categorical_meanings(column_name: str, column_info: dict) → MeaningsTable[source]#

Converts a categorical column info dict to a MeaningsTable.

Parameters:

  • column_name (str) – The name of the column.

  • column_info (dict) – The column info dictionary from the sidecar.

Returns:

The constructed MeaningsTable object.

Return type:

MeaningsTable

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

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”.

Returns:

The constructed EventsTable object.

Return type:

EventsTable

ndx_hed.utils.bids2nwb.get_bids_events(events_table: EventsTable) → tuple[source]#

Converts an EventsTable back to BIDS format (DataFrame and JSON sidecar).

Parameters:

events_table (EventsTable) – The EventsTable to convert.

Returns:

A tuple containing:

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

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

Return type:

tuple

None