IrregularTimeSeries

class IrregularTimeSeries(timestamps, *, timekeys=None, domain, **kwargs)

Bases: ArrayDict

An irregular time series is defined by a set of timestamps and a set of attributes that must share the same first dimension as the timestamps. This data object is ideal for event-based data as well as irregularly sampled time series.

Parameters:

• timestamps (ndarray) – an array of timestamps of shape (N,).

• timekeys (Optional[List[str]]) – a list of strings that specify which attributes are time-based attributes, this ensures that these attributes are updated appropriately when slicing.

• domain (Union[Interval, str]) – an Interval object that defines the domain over which the timeseries is defined. If set to "auto", the domain will be automatically the interval defined by the minimum and maximum timestamps.

• **kwargs (ndarray) – arrays that shares the same first dimension N.

Example

>>> import numpy as np
>>> from temporaldata import IrregularTimeSeries

>>> spikes = IrregularTimeSeries(
...     unit_index=np.array([0, 0, 1, 0, 1, 2]),
...     timestamps=np.array([0.1, 0.2, 0.3, 0.4, 0.5, 0.6]),
...     waveforms=np.zeros((6, 48)),
...     domain="auto",
... )

>>> spikes
IrregularTimeSeries(
  timestamps=[6],
  unit_index=[6],
  waveforms=[6, 48]
)

>>> spikes.domain.start, spikes.domain.end
(array([0.1]), array([0.6]))

>>> spikes.keys()
['timestamps', 'unit_index', 'waveforms']

>>> spikes.is_sorted()
True

>>> slice_of_spikes = spikes.slice(0.2, 0.5)
>>> slice_of_spikes
IrregularTimeSeries(
  timestamps=[3],
  unit_index=[3],
  waveforms=[3, 48]
)

>>> slice_of_spikes.domain.start, slice_of_spikes.domain.end
(array([0.]), array([0.3]))

>>> slice_of_spikes.timestamps
array([0. , 0.1, 0.2])

property domain

The time domain over which the time series is defined. Usually a single interval, but could also be a set of intervals.

timekeys()

Returns a list of all time-based attributes.

register_timekey(timekey)

Register a new time-based attribute.

is_sorted()

Returns True if the timestamps are sorted.

sort()

Sorts the timestamps, and reorders the other attributes accordingly. This method is applied in place.

slice(start, end, reset_origin=True)

Returns a new IrregularTimeSeries object that contains the data between the start and end times. The end time is exclusive, the slice will only include data in \([\textrm{start}, \textrm{end})\).

If reset_origin is True, all time attributes are updated to be relative to the new start time. The domain is also updated accordingly.

Warning

If the time series is not sorted, it will be automatically sorted in place.

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_mask(mask)

Return a new IrregularTimeSeries object where all array attributes are indexed using the boolean mask.

Note that this will not update the domain, as it is unclear how to resolve the domain when the mask is applied. If you wish to update the domain, you should do so manually.

select_by_interval(interval)

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

Parameters:

interval (Interval) – Interval object.

classmethod from_dataframe(df, domain='auto', unsigned_to_long=True)

Create an IrregularTimeseries object from a pandas DataFrame. The dataframe must have a timestamps column, with the name "timestamps" (use pd.Dataframe.rename if needed).

The columns in the DataFrame are converted to arrays when possible, otherwise they will be skipped.

Parameters:

• df (DataFrame) – DataFrame.

• unsigned_to_long (bool) – Whether to automatically convert unsigned integers to int64 dtype. Defaults to True.

• domain (optional) – The domain over which the time series is defined. If set to "auto", the domain will be automatically the interval defined by the minimum and maximum timestamps. Defaults to "auto".

to_hdf5(file)

Saves the data object to an HDF5 file.

Parameters:

file (h5py.File) – HDF5 file.

Warning

If the time series is not sorted, it will be automatically sorted in place.

import h5py
from temporaldata import IrregularTimeseries

data = IrregularTimeseries(
    unit_index=np.array([0, 0, 1, 0, 1, 2]),
    timestamps=np.array([0.1, 0.2, 0.3, 0.4, 0.5, 0.6]),
    waveforms=np.zeros((6, 48)),
    domain="auto",
)

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

classmethod from_hdf5(file)

Loads the data object from an HDF5 file.

Parameters:

file (h5py.File) – HDF5 file.

Note

This method will load all data in memory, if you would like to use lazy loading, call LazyIrregularTimeSeries.from_hdf5() instead.

import h5py
from temporaldata import IrregularTimeSeries

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

keys()

Returns a list of all array attribute names.

Return type:

List[str]

materialize()

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

Return type:

ArrayDict

class LazyIrregularTimeSeries(timestamps, *, timekeys=None, domain, **kwargs)

Bases: IrregularTimeSeries

Lazy variant of IrregularTimeSeries. The data is not loaded until it is accessed. This class is meant to be used when the data is too large to fit in memory, and is intended to be intantiated via. LazyIrregularTimeSeries.from_hdf5.

Note

To access an attribute without triggering the in-memory loading use self.__dict__[key] otherwise using self.key or getattr(self, key) will trigger the lazy loading and will automatically convert the h5py dataset to a numpy array as well as apply any outstanding masks.

select_by_mask(mask)

Return a new IrregularTimeSeries object where all array attributes are indexed using the boolean mask.

Note that this will not update the domain, as it is unclear how to resolve the domain when the mask is applied. If you wish to update the domain, you should do so manually.

slice(start, end, reset_origin=True)

Returns a new IrregularTimeSeries object that contains the data between the start and end times. The end time is exclusive, the slice will only include data in \([\textrm{start}, \textrm{end})\).

If reset_origin is True, all time attributes are updated to be relative to the new start time. The domain is also updated accordingly.

Warning

If the time series is not sorted, it will be automatically sorted in place.

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.

property domain

The time domain over which the time series is defined. Usually a single interval, but could also be a set of intervals.

classmethod from_dataframe(df, domain='auto', unsigned_to_long=True)

Create an IrregularTimeseries object from a pandas DataFrame. The dataframe must have a timestamps column, with the name "timestamps" (use pd.Dataframe.rename if needed).

The columns in the DataFrame are converted to arrays when possible, otherwise they will be skipped.

Parameters:

• df (DataFrame) – DataFrame.

• unsigned_to_long (bool) – Whether to automatically convert unsigned integers to int64 dtype. Defaults to True.

• domain (optional) – The domain over which the time series is defined. If set to "auto", the domain will be automatically the interval defined by the minimum and maximum timestamps. Defaults to "auto".

is_sorted()

Returns True if the timestamps are sorted.

keys()

Returns a list of all array attribute names.

Return type:

List[str]

materialize()

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

Return type:

ArrayDict

register_timekey(timekey)

Register a new time-based attribute.

select_by_interval(interval)

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

Parameters:

interval (Interval) – Interval object.

sort()

Sorts the timestamps, and reorders the other attributes accordingly. This method is applied in place.

timekeys()

Returns a list of all time-based attributes.

to_hdf5(file)

Saves the data object to an HDF5 file.

Parameters:

file (h5py.File) – HDF5 file.

Warning

If the time series is not sorted, it will be automatically sorted in place.

import h5py
from temporaldata import IrregularTimeseries

data = IrregularTimeseries(
    unit_index=np.array([0, 0, 1, 0, 1, 2]),
    timestamps=np.array([0.1, 0.2, 0.3, 0.4, 0.5, 0.6]),
    waveforms=np.zeros((6, 48)),
    domain="auto",
)

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

classmethod from_hdf5(file)

Loads the data object from an HDF5 file.

Parameters:

file (h5py.File) – HDF5 file.

import h5py
from temporaldata import ArrayDict

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