API Reference

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

Core Classes

HedLabMetaData

class HedLabMetaData(*args: Any, **kwargs: Any)[source]

Bases:

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

HedTags

class HedTags(*args, **kwargs)[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)).

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

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 HedValueVector(*args, **kwargs)[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.

__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

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 hed

Return the HED annotation template for this column.

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 HedNWBValidator(*args: Any, **kwargs: Any)[source]

Bases:

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

BIDS Conversion Utilities

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

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

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

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

  • 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

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

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.

Return type:

EventsTable

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

  • TimestampVectorData/DurationVectorData: description only, since the BIDS onset and duration columns carry no HED metadata. 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.

  • HedValueVector: its HED template, unless the template is empty or “n/a”.

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

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.

Return type:

tuple