Base Data Interface#

class BaseDataInterface(verbose: bool = False, **source_data)[source]#

Bases: ABC

Abstract class defining the structure of all DataInterfaces.

display_name: str | None = None#
keywords: tuple[str] = ()#
associated_suffixes: tuple[str] = ()#
info: str | None = None#
classmethod get_source_schema() → dict[source]#

Infer the JSON schema for the source_data from the method signature (annotation typing).

Returns:

The JSON schema for the source_data.

Return type:

dict

classmethod validate_source(source_data: dict, verbose: bool = False)[source]#

Validate source_data against Converter source_schema.

get_metadata_schema() → dict[source]#

Retrieve JSON schema for metadata.

Returns:

The JSON schema defining the metadata structure.

Return type:

dict

get_metadata() → DeepDict[source]#

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

validate_metadata(metadata: dict, append_mode: bool = False) → None[source]#

Validate the metadata against the schema.

get_conversion_options_schema() → dict[source]#

Infer the JSON schema for the conversion options from the method signature (annotation typing).

Returns:

The JSON schema for the conversion options.

Return type:

dict

create_nwbfile(metadata: dict | None = None, **conversion_options) → NWBFile[source]#

Create and return an in-memory pynwb.NWBFile object with this interface’s data added to it.

Parameters:

  • metadata (dict, optional) – Metadata dictionary with information used to create the NWBFile.

  • **conversion_options – Additional keyword arguments to pass to the .add_to_nwbfile method.

Returns:

nwbfile – The in-memory object with this interface’s data added to it.

Return type:

pynwb.NWBFile

abstractmethod add_to_nwbfile(nwbfile: NWBFile, metadata: dict | None, **conversion_options) → None[source]#

Define a protocol for mapping the data from this interface to NWB neurodata objects.

These neurodata objects should also be added to the in-memory pynwb.NWBFile object in this step.

Parameters:

  • nwbfile (pynwb.NWBFile) – The in-memory object to add the data to.

  • metadata (dict) – Metadata dictionary with information used to create the NWBFile.

  • **conversion_options – Additional keyword arguments to pass to the .add_to_nwbfile method.

run_conversion(nwbfile_path: Annotated[Path, PathType(path_type=file)], nwbfile: NWBFile | None = None, metadata: dict | None = None, overwrite: bool = False, backend: Literal['hdf5', 'zarr'] | None = None, backend_configuration: HDF5BackendConfiguration | ZarrBackendConfiguration | None = None, append_on_disk_nwbfile: bool = False, **conversion_options)[source]#

Run the NWB conversion for the instantiated data interface.

Parameters:

  • nwbfile_path (FilePath) – Path for where to write or load (if overwrite=False) the NWBFile.

  • nwbfile (NWBFile, optional) – An in-memory NWBFile object to write to the location.

  • metadata (dict, optional) – Metadata dictionary with information used to create the NWBFile when one does not exist or overwrite=True.

  • overwrite (bool, default: False) – Whether to overwrite the NWBFile if one exists at the nwbfile_path. The default is False (append mode).

  • backend ({“hdf5”, “zarr”}, optional) – The type of backend to use when writing the file. If a backend_configuration is not specified, the default type will be “hdf5”. If a backend_configuration is specified, then the type will be auto-detected.

  • backend_configuration (HDF5BackendConfiguration or ZarrBackendConfiguration, optional) – The configuration model to use when configuring the datasets for this backend. To customize, call the .get_default_backend_configuration(…) method, modify the returned BackendConfiguration object, and pass that instead. Otherwise, all datasets will use default configuration settings.

  • append_on_disk_nwbfile (bool, default: False) – Whether to append to an existing NWBFile on disk. If True, the nwbfile parameter must be None. This is useful for appending data to an existing file without overwriting it.

static get_default_backend_configuration(nwbfile: NWBFile, backend: Literal['hdf5', 'zarr'] = 'hdf5') → HDF5BackendConfiguration | ZarrBackendConfiguration[source]#

Fill and return a default backend configuration to serve as a starting point for further customization.

Parameters:

  • nwbfile (pynwb.NWBFile) – The in-memory object with this interface’s data already added to it.

  • backend (“hdf5”, default: “hdf5”) – The type of backend to use when creating the file. Additional backend types will be added soon.

Returns:

The default configuration for the specified backend type.

Return type:

HDF5BackendConfiguration | ZarrBackendConfiguration

class BaseTemporalAlignmentInterface(verbose: bool = False, **source_data)[source]#

Bases: BaseDataInterface

An extension of the BaseDataInterface that includes several methods for performing temporal alignment.

abstractmethod get_original_timestamps() → ndarray[source]#

Retrieve the original unaltered timestamps for the data in this interface.

This function should retrieve the data on-demand by re-initializing the IO.

Returns:

timestamps – The timestamps for the data stream.

Return type:

numpy.ndarray

abstractmethod get_timestamps() → ndarray[source]#

Retrieve the timestamps for the data in this interface.

Returns:

timestamps – The timestamps for the data stream.

Return type:

numpy.ndarray

abstractmethod set_aligned_timestamps(aligned_timestamps: ndarray) → None[source]#

Replace all timestamps for this interface with those aligned to the common session start time.

Must be in units seconds relative to the common ‘session_start_time’.

Parameters:

aligned_timestamps (numpy.ndarray) – The synchronized timestamps for data in this interface.

set_aligned_starting_time(aligned_starting_time: float) → None[source]#

Align the starting time for this interface relative to the common session start time.

Must be in units seconds relative to the common ‘session_start_time’.

Parameters:

aligned_starting_time (float) – The starting time for all temporal data in this interface.

align_by_interpolation(unaligned_timestamps: ndarray, aligned_timestamps: ndarray) → None[source]#

Interpolate the timestamps of this interface using a mapping from some unaligned time basis to its aligned one.

Use this method if the unaligned timestamps of the data in this interface are not directly tracked by a primary system, but are known to occur between timestamps that are tracked, then align the timestamps of this interface by interpolating between the two.

An example could be a metronomic TTL pulse (e.g., every second) from a secondary data stream to the primary timing system; if the time references of this interface are recorded within the relative time of the secondary data stream, then their exact time in the primary system is inferred given the pulse times.

Must be in units seconds relative to the common ‘session_start_time’.

Parameters:

  • unaligned_timestamps (numpy.ndarray) – The timestamps of the unaligned secondary time basis.

  • aligned_timestamps (numpy.ndarray) – The timestamps aligned to the primary time basis.

Abstract class defining the structure of all Extractor-based Interfaces.

class BaseExtractorInterface(**source_data)[source]#

Bases: BaseTemporalAlignmentInterface, ABC

Abstract class defining the structure of all Extractor-based Interfaces.

abstractmethod classmethod get_extractor_class()[source]#

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

property extractor#

Get the extractor class for this interface.

Deprecated since version 0.8.2: The extractor attribute is deprecated and will be removed on or after March 2026. This attribute was confusingly named as it returns a class, not an instance. Use the class method get_extractor_class()

Returns:

The extractor class.

Return type:

type

get_extractor()[source]#

Get the extractor class for this interface.

Deprecated since version 0.8.2: The get_extractor() method is deprecated and will be removed on or after March 2026. This method was confusingly named as it returns a class, not an instance. Use get_extractor_class() instead.

Returns:

The extractor class.

Return type:

type