API Reference¶
This section provides detailed API documentation for the ndx-hed extension.
Core Classes¶
HedLabMetaData¶
HedValueVector¶
- class HedValueVector(*args, **kwargs)[source]¶
Bases:
VectorDataColumn 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.
- __init__(name, description, hed, data=[])[source]¶
- Parameters:
name (
str) – the name of this VectorDatadescription (
str) – a description for this columnhed (
str) – HED annotation template for all values in the columndata (
ndarrayorlistortupleorDatasetorStrDatasetorHDMFDatasetorAbstractDataChunkIteratororDataIO) – 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_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
HDMFIOobject 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
HDMFIOobject 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
HDMFIOobject 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:
- 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:
- 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:
- get_categorical_meanings(column_name: str, column_info: dict) MeaningsTable[source]¶
Converts a categorical column info dict to a MeaningsTable.