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 or list or tuple) – The HED schema version(s) used by this data: 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’, a JSON array string such as ‘[“8.5.0”, “sc:score_2.2.0”]’, or a list of version strings. Each version is ‘[namespace:]X.Y.Z’ for the standard schema or ‘[namespace:]library_X.Y.Z’ for a library schema. A list is stored as the JSON array string.
definitions (str) – A string containing one or more HED definitions.

__init__(hed_schema_version, definitions=None)[source]#

Parameters:

hed_schema_version (str or list or tuple) – The HED schema version(s) used by this data: 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’, a JSON array string such as ‘[“8.5.0”, “sc:score_2.2.0”]’, or a list of version strings. Each version is ‘[namespace:]X.Y.Z’ for the standard schema or ‘[namespace:]library_X.Y.Z’ for a library schema. A list is stored as the JSON array string.
definitions (str) – A string containing one or more HED definitions.

property hed_schema_version#

score_2.2.0”]’, or a list of version strings. Each version is ‘[namespace:]X.Y.Z’ for the standard schema or ‘[namespace:]library_X.Y.Z’ for a library schema. A list is stored as the JSON array string.

Type:: The HED schema version(s) used by this data
Type:: 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’, a JSON array string such as ‘[“8.5.0”, “sc

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 string as stored: the string given to the constructor, or the JSON array string when the constructor was given a list.
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, 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=[])[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.

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

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

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

HedDurationVector#

class ndx_hed.HedDurationVector(name, description, hed, data=[], resolution=None)[source]#

Bases: DurationVectorData

The duration column of an EventsTable (durations in seconds) with a single HED annotation template that applies to all values in the column, as a HedValueVector does. It is a DurationVectorData, so code that reads event durations sees an ordinary duration column.

HED-aware code treats it as a HedValueVector: the same rules apply (it may not appear in a MeaningsTable, and its values must satisfy the value class of the template’s # tag). HED_TEMPLATE_TYPES holds both.

Parameters:

name (str) – Name of this DurationVectorData
description (str) – Description of this DurationVectorData
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
resolution (float) – The temporal resolution of the durations, in seconds. This is typically the sampling period (1 / sampling_rate), also known as the clock period, of the data acquisition system from which the durations were recorded or derived.

__init__(name, description, hed, data=[], resolution=None)[source]#

Parameters:

name (str) – Name of this DurationVectorData
description (str) – Description of this DurationVectorData
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
resolution (float) – The temporal resolution of the durations, in seconds. This is typically the sampling period (1 / sampling_rate), also known as the clock period, of the data acquisition system from which the durations were recorded or derived.

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 = 'HedDurationVector'#

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()#

property unit#: The unit of measurement for the durations, fixed to ‘seconds’.

Validation Utilities#

HedNWBValidator#

class ndx_hed.utils.hed_nwb_validator.HedNWBValidator(hed_metadata: HedLabMetaData)[source]#

Bases: object

Validates the HED annotations in NWB DynamicTable objects against the HED schema of a HedLabMetaData.

validate_table is the table validator and validate_file calls it for every table in a file. validate_vector and validate_value_vector validate one column in isolation.

Initialize the HedNWBValidator with HED metadata.

Parameters:: hed_metadata (HedLabMetaData) – The HED lab metadata holding the schema and the definitions. A constructed HedLabMetaData has already loaded and checked both, so nothing is validated here.
Raises:: ValueError – If hed_metadata is not an instance of HedLabMetaData

__init__(hed_metadata: HedLabMetaData)[source]#

Initialize the HedNWBValidator with HED metadata.

Parameters:: hed_metadata (HedLabMetaData) – The HED lab metadata holding the schema and the definitions. A constructed HedLabMetaData has already loaded and checked both, so nothing is validated here.
Raises:: ValueError – If hed_metadata is not an instance of HedLabMetaData

validate_table(table: DynamicTable, error_handler: ErrorHandler | None = None, assemble: bool = True) → list[dict[str, Any]][source]#

Validates the HED annotations of a DynamicTable.

The steps, in order. “Stops” means the issues found so far for this table are returned and the later steps do not run for it.

Structural rules (docs/source/hed_validation.md): a column named HED, in the table or in any of its MeaningsTables, must be a HedTags (HED_COLUMN_TYPE_INVALID); a MeaningsTable must not contain a HedValueVector or HedDurationVector (MEANINGS_VALUE_VECTOR_INVALID). An issue stops.
A table with no HedTags column, no HedValueVector or HedDurationVector column (the template columns, HED_TEMPLATE_TYPES; everything below said of a HedValueVector holds for both), no MeaningsTable with a HED column, and no column named HED apart from leading or trailing whitespace has nothing to validate and returns [] without being read. (A padded HED name counts, so that hedtools reports it rather than the table being skipped.)
The table’s column metadata is converted to a BIDS sidecar dict with get_json_hed_dict, which reads no table data. The definitions of the HedLabMetaData travel in the sidecar, as BIDS carries them.
hedtools’ staged tabular validation (SpreadsheetValidator.validate) runs on the table through a column source that reads one column at a time, each stage stopping on an error: the sidecar (HedValueVector templates, MeaningsTable HED, definitions, {column} references); the column values, that is each HedValueVector’s distinct values against the units and value class of its template’s # tag (rule R7, with the value in place, then the basic syntax checks on the substituted tag) and each categorical column’s distinct values against its levels (SIDECAR_KEY_MISSING, a warning); the HED column, each distinct string once with the basic checks; then the assembly gate. With assemble=True (the default) the whole table is read into a BIDS dataframe with get_bids_dataframe and each row’s HED is assembled from its HED cell, its categorical HED, and its value templates and validated as a whole, with the temporal checks over the rows when the table has a TimestampVectorData column (exported as onset). With assemble=False the table is never converted to a dataframe: the group-level checks run on each distinct HED string instead, and nothing that needs the other tags of a row or the other rows is checked.

A HedValueVector whose dtype settles the value class is not read at all: a numeric column passes textClass, an integer column passes numericClass and nameClass, and a float column under numericClass is scanned once for infinities, which are not numeric values.

Every issue carries the table name in ec_table_name. A sidecar issue carries the column in ec_sidecarColumnName and, for categorical HED, the value in ec_sidecarKeyName, and has no row. A row issue carries ec_column and ec_row, the table row index (the first data row is 0) in both modes. The values of a HedValueVector and the strings of the HED column are validated by distinct value in both modes: each is validated once, reported at the first row holding it, with the number of rows that hold it in row_count.

Parameters:

table (DynamicTable) – The table to validate. Not a MeaningsTable: its HED is validated as part of the table whose column it annotates.
error_handler (ErrorHandler, optional) – Collects the issues. A new one that drops warnings is created if None.
assemble (bool) – Whether to run the assembled (row and temporal) validation. Default True.

Returns:

The validation issues for the table.

Return type:

list[dict[str, Any]]

Raises:

ValueError – If table is not a DynamicTable, or is a MeaningsTable.

validate_file(nwbfile: NWBFile, error_handler: ErrorHandler | None = None, assemble: bool = True) → list[dict[str, Any]][source]#

Validates the HED annotations of every DynamicTable in an NWB file.

The file must hold a HedLabMetaData named hed_schema whose schema version matches the validator’s. Every DynamicTable except a MeaningsTable is then passed to validate_table; a MeaningsTable is covered by the table whose column it annotates. Every issue carries the file identifier in ec_filename and its table in ec_table_name.

Parameters:

nwbfile (NWBFile) – The NWB file to validate
error_handler (ErrorHandler, optional) – Collects the issues. A new one that drops warnings is created if None.
assemble (bool) – Passed to validate_table. Default True.

Returns:

The validation issues of 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

validate_vector(hed_tags: HedTags, error_handler: ErrorHandler | None = None) → list[dict[str, Any]][source]#

Validates the annotations of a HedTags column in isolation, each distinct string once.

Each distinct HED string of the column is checked on its own: the basic checks and the group-level checks (hedtools validate_hed_column with full_string=True). The required-tag check needs the assembled row and does not run. The helper does not see the other columns of the row, the categorical HED of a MeaningsTable, or the other rows, so use validate_table for a table. An issue is reported at the first row holding the string, with the number of rows that hold it in row_count.

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 | HedDurationVector, error_handler: ErrorHandler | None = None) → list[dict[str, Any]][source]#

Validates a HedValueVector (or HedDurationVector) column in isolation: the template on its own, then the values.

The template is validated with placeholders allowed and with any {column} references removed first: a reference is resolved against the table’s other columns by validate_table (hedtools’ sidecar validation), which this single-column helper cannot do. If the template has an error the values are not checked. Otherwise each distinct non-missing value is checked as the # tag alone with the value in place, for its units and value class and then the basic syntax checks on the substituted tag, exactly as validate_table does (rule R7, hedtools validate_value_column); an issue is reported at the first row holding the value with the number of rows in row_count. A column whose dtype settles the value class is not read.

Parameters:

hed_values (HedValueVector | HedDurationVector) – The template 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]]

BIDS Conversion Utilities#

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

ndx_hed.utils.bids2nwb.read_bids_tsv(path) → DataFrame[source]#

Reads a BIDS TSV file into a DataFrame the way hedtools reads it for validation.

Every cell is kept as text exactly as written: a double quote is an ordinary character, a line is split on every tab, and only an empty cell and n/a are missing (NaN); NA, null, or nan are values. Column names are the header cells exactly as written too: the header line is read as a data row, so pandas does not rename a repeated name (HED, HED.1) or a blank one (Unnamed: 1), and a padded, repeated, or blank name reaches get_events_table and validation as it is in the file (HED specification 3.2.10). pd.read_csv(path, sep="\t") with its defaults removes quotes, reads NA as missing, and renames repeated and blank names, so a file converted with it is not the file hedtools validates.

Parameters:: path (str or path-like or file-like) – The TSV file, UTF-8 (a byte order mark is removed).
Returns:: The file’s columns, labeled by the header cells, every value a string or NaN.
Return type:: pd.DataFrame
Raises:: pandas.errors.EmptyDataError – If the file has no header line.

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

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[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”. 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. The onset column becomes the TimestampVectorData “timestamp”; the duration column becomes a HedDurationVector when meanings gives it a value template, a DurationVectorData otherwise.

Return type:

EventsTable

Raises:

ValueError – If the DataFrame repeats a column name, if meanings gives the onset column any HED or Levels, or if meanings makes the duration column categorical.

ndx_hed.utils.bids2nwb.get_levels_and_hed(meanings_table: MeaningsTable) → tuple[source]#

Extracts the BIDS “Levels” and “HED” dictionaries from a MeaningsTable without using pandas.

Parameters:

meanings_table (MeaningsTable) – The MeaningsTable annotating a categorical column. Its “value” and “meaning” columns supply the levels; an optional HedTags column named “HED” supplies the per-value HED annotations.

Returns:

A tuple containing:

dict: Levels – maps each value to its meaning (empty string if there is no meaning).
dict: HED – maps each value to its HED string, omitting missing (None, NaN, or empty) annotations. Empty if the MeaningsTable has no HED column. An explicit n/a is kept (the sidecar annotates the value as having no HED); a value with an empty cell, which get_categorical_meanings writes for a value only Levels lists, is not a key under HED, so the rule for keys under HED (specification 3.2.9.2) does not apply to it.

Return type:

tuple

ndx_hed.utils.bids2nwb.get_json_hed_dict(table: DynamicTable, hed_metadata: HedLabMetaData = None) → dict[source]#

Builds the BIDS-style JSON sidecar dictionary of a DynamicTable directly from its columns.

This is the metadata half of get_bids_tabular(). It reads the column objects and the MeaningsTable annotating each categorical column, so it needs neither a dataframe nor pandas.

Each entry maps a column name to a BIDS sidecar column-info dict, which may contain:

“Description”: the column’s description, if it has one.
“HED”: for a HedValueVector or HedDurationVector, its value template (a string containing a single “#”); for a categorical column, a dict mapping each value to its HED string.
“Levels”: for a categorical column, a dict mapping each value to its meaning.

Columns contribute as follows:

HedTags (the “HED” column): omitted entirely. Its cells are HED strings, so the column is self-describing, and “HED” is a reserved sidecar key that must not name an entry.
HedValueVector and HedDurationVector: the HED template, unless the template is empty or “n/a”.
A plain TimestampVectorData/DurationVectorData: description only. The entry keeps the column’s own name, so an EventsTable “timestamp” column is keyed “timestamp” even though get_bids_tabular() renames it to “onset” in the dataframe.
Any other column: the Levels and HED of the MeaningsTable annotating it, if any.

Columns with no metadata are omitted, so the result is empty for a table with no descriptions, no MeaningsTables, and no HED template columns.

In NWB, HED definitions live in a HedLabMetaData object, which is the only place extra definitions may come from. When one is given, its definitions are exported under the “definitions” key as {"HED": {"defList": <definitions>}} – a sidecar entry that names no column, which is how BIDS carries definitions. The resulting sidecar is then self-contained: the Def/ references in the table can be resolved without supplying the definitions separately. If the HedLabMetaData holds no definitions, no entry is added.

Parameters:

table (DynamicTable) – The table to extract the sidecar metadata from. As with get_bids_tabular(), this is not meant for a MeaningsTable, whose HED is consumed while assembling the table whose column it annotates.
hed_metadata (HedLabMetaData, optional) – The HED lab metadata supplying the definitions. If None (the default), the sidecar carries no definitions.

Returns:

The JSON sidecar data with column metadata, levels, HED annotations, and definitions.

Return type:

dict

Raises:

ValueError – If hed_metadata is given but is not a HedLabMetaData instance.
ValueError – If the definitions would overwrite the entry of a column named “definitions”.

ndx_hed.utils.bids2nwb.get_bids_dataframe(table: DynamicTable) → DataFrame[source]#

Converts the data of a DynamicTable to a BIDS-style dataframe, the TSV half of get_bids_tabular().

This reads every column of the table. A TimestampVectorData column is renamed to onset so that downstream BIDS-HED validation treats the table as a timeline (temporal) file. Missing cells (NaN, None, the empty string) become the text n/a, as in a BIDS TSV file, so every column of the returned dataframe has dtype object.

Parameters:: table (DynamicTable) – The table to convert.
Returns:: The table data with BIDS column names (onset, duration, etc.)
Return type:: pd.DataFrame
Raises:: ValueError – If a BIDS column name would occur twice, that is the table has a column named onset as well as a TimestampVectorData named timestamp (TABULAR_INVALID, HED specification 3.2.10).

ndx_hed.utils.bids2nwb.get_bids_tabular(table: DynamicTable, hed_metadata: HedLabMetaData = None) → tuple[source]#

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. The dataframe is get_bids_dataframe(table) and the sidecar is get_json_hed_dict(table, hed_metadata); call those directly to get only one half (the sidecar half does not read the table’s data).

Parameters:

table (DynamicTable) – The table to convert.
hed_metadata (HedLabMetaData, optional) – The HED lab metadata supplying the definitions, passed through to get_json_hed_dict(). If None (the default), the sidecar carries no definitions and any Def/ references in the table cannot be resolved from it alone.

Returns:

A tuple containing:

pd.DataFrame: The table data with BIDS column names (onset, duration, etc.)
dict: The JSON sidecar data as returned by get_json_hed_dict().

Return type:

tuple