Data

class temporaldata.Data(*, domain=None, **kwargs)

Bases: object

A flexible container for other data objects such as ArrayDict, RegularTimeSeries, IrregularTimeSeries, and Interval objects, as well as nested Data objects and regular Python objects like scalars, strings, and numpy arrays.

Parameters:

• **kwargs – Arbitrary attributes to attach to the data object (e.g. spikes, lfp, units, trials, metadata).

• domain (Union[Interval, Literal['auto'], None]) – An Interval specifying time domain of the data object. If "auto", the domain is computed as the union of the domains of any time-based attributes. Defaults to None.

Example

>>> import numpy as np
>>> from temporaldata import (
...     ArrayDict,
...     IrregularTimeSeries,
...     RegularTimeSeries,
...     Interval,
...     Data,
... )

>>> data = Data(
...     session_id="session_0",
...     spikes=IrregularTimeSeries(
...         timestamps=np.array([0.1, 0.2, 0.3, 2.1, 2.2, 2.3]),
...         unit_index=np.array([0, 0, 1, 0, 1, 2]),
...         waveforms=np.zeros((6, 48)),
...         domain=Interval(0., 3.),
...     ),
...     lfp=RegularTimeSeries(
...         raw=np.zeros((1000, 3)),
...         sampling_rate=250.,
...     ),
...     units=ArrayDict(
...         id=np.array(["unit_0", "unit_1", "unit_2"]),
...         brain_region=np.array(["M1", "M1", "PMd"]),
...     ),
...     trials=Interval(
...         start=np.array([0, 1, 2]),
...         end=np.array([1, 2, 3]),
...         go_cue_time=np.array([0.5, 1.5, 2.5]),
...         drifting_gratings_dir=np.array([0, 45, 90]),
...     ),
...     drifting_gratings_imgs=np.zeros((8, 3, 32, 32)),
...     domain=Interval(0., 4.),
... )

>>> data
Data(
session_id='session_0',
spikes=IrregularTimeSeries(
  timestamps=[6],
  unit_index=[6],
  waveforms=[6, 48]
),
lfp=RegularTimeSeries(
  raw=[1000, 3]
),
units=ArrayDict(
  id=[3],
  brain_region=[3]
),
trials=Interval(
  start=[3],
  end=[3],
  go_cue_time=[3],
  drifting_gratings_dir=[3]
),
drifting_gratings_imgs=[8, 3, 32, 32],
)

>>> data.slice(1, 3)
Data(
session_id='session_0',
spikes=IrregularTimeSeries(
  timestamps=[3],
  unit_index=[3],
  waveforms=[3, 48]
),
lfp=RegularTimeSeries(
  raw=[500, 3]
),
units=ArrayDict(
  id=[3],
  brain_region=[3]
),
trials=Interval(
  start=[2],
  end=[2],
  go_cue_time=[2],
  drifting_gratings_dir=[2]
),
drifting_gratings_imgs=[8, 3, 32, 32],
_absolute_start=1.0,
)

property domain

Returns the domain of the data object.

property start

Returns the start time of the data object.

property end

Returns the end time of the data object.

property absolute_start

Returns the start time of this slice relative to the original start time. Should be 0. if the data object has not been sliced.

Example

>>> from temporaldata import Data
>>> data = Data(domain=Interval(0., 4.))

>>> data.absolute_start
0.0

>>> data = data.slice(1, 3)
>>> data.absolute_start
1.0

>>> data = data.slice(0.4, 1.4)
>>> data.absolute_start
1.4

slice(start, end, reset_origin=True)

Returns a new Data object that contains the data between the start and end times. This method will slice all time-based attributes that are present in the data object.

Parameters:

• start (float) – Start time.

• end (float) – End time.

• reset_origin (bool) – If True, all time attributes will be updated to be relative to the new start time. Defaults to True.

select_by_interval(interval)

Return a new IrregularTimeSeries object where all timestamps are within the interval.

Parameters:

interval (Interval) – Interval object.

to_dict()

Returns a dictionary of stored key/value pairs.

Return type:

Dict[str, Any]

to_hdf5(file, serialize_fn_map=None)

Saves the data object to an HDF5 file. This method will also call the to_hdf5 method of all contained data objects, so that the entire data object is saved to the HDF5 file, i.e. no need to call to_hdf5 for each contained data object.

Parameters:

file (h5py.File) – HDF5 file.

import h5py
from temporaldata import Data

data = Data(...)

with h5py.File("data.h5", "w") as f:
    data.to_hdf5(f)

classmethod from_hdf5(file, lazy=True)

Loads the data object from an HDF5 file. This method will also call the from_hdf5 method of all contained data objects, so that the entire data object is loaded from the HDF5 file, i.e. no need to call from_hdf5 for each contained data object.

Parameters:

file (h5py.File) – HDF5 file.

import h5py
from temporaldata import Data

with h5py.File("data.h5", "r") as f:
    data = Data.from_hdf5(f)

property file: File | None

The underlying HDF5 file handle, or None if no file is open. Only set when the object was created via load() or from_hdf5() with lazy=True.

classmethod load(path, lazy=True)

Loads the Data object from an HDF5 file given its file path.

When lazy=True (default), the underlying HDF5 file remains open and data is loaded on demand. The caller is responsible for closing the file handle when done, either by calling close() or by using the context manager protocol.

When lazy=False, all data is read into memory immediately and the file is closed before returning.

Parameters:

• path (Union[Path, str]) – The file path to the HDF5 file containing the Data object.

• lazy (bool) – If True (default), load contained objects in lazy mode (using LazyArrayDict, LazyRegularTimeSeries, etc.); if False, read all data immediately into memory.

Returns:

The loaded Data object from the HDF5 file.

Return type:

Data

from temporaldata import Data

# lazy with context manager (recommended)
with Data.load("data.h5") as data:
    ...

# lazy with explicit close
data = Data.load("data.h5")
...
data.close()

# non-lazy (no close needed)
data = Data.load("data.h5", lazy=False)

close(strict=False)

Close the file-handle that was opened for lazy-loading. Any lazy attributes that have not been materialized will become invalid.

Parameters:

strict (bool) – If True, raise an error when no open file handle is present. Default False.

save(path)

Saves the data object to an HDF5 file at the given path.

Parameters:

path (Union[Path, str]) – Destination file path

from temporaldata import Data

data = Data(...)
data.save("data.h5")

set_train_domain(interval)

Deprecated no-op retained for backward compatibility.

set_valid_domain(interval)

Deprecated no-op retained for backward compatibility.

set_test_domain(interval)

Deprecated no-op retained for backward compatibility.

keys()

Returns a list of all attribute names.

Return type:

List[str]

get_nested_attribute(path)

Returns the attribute specified by the path. The path can be nested using dots. For example, if the path is “spikes.timestamps”, this method will return the timestamps attribute of the spikes object.

Parameters:

path (str) – Nested attribute path.

Return type:

Any

set_nested_attribute(path, value)

Set a nested attribute specified by its path. The path can be nested using dots. For example, if the path is “session.id”, this method will set the value of the id attribute of the session object. The attribute is modified in an in-place manner.

Parameters:

• path (str) – Nested attribute path (can be dot-separated, e.g. “session.id”).

• value (Any) – The value to set for the attribute.

Returns:

self with the updated nested attribute.

Return type:

Data

Raises:

AttributeError – If any component of the path cannot be resolved.

has_nested_attribute(path)

Check if the attribute specified by the path exists in the Data object.

Return type:

bool

materialize()

Materializes the data object, i.e., loads into memory all of the data that is still referenced in the HDF5 file.

Return type:

Data