LazyRegularTimeSeries#

class temporaldata.LazyRegularTimeSeries(**kwargs)[source]#

Bases: RegularTimeSeries

Lazy variant of RegularTimeSeries. 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. LazyRegularTimeSeries.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.

slice(start, end, reset_origin=True, eps=1e-09)[source]#

Returns a new RegularTimeSeries object that contains the data between the start (inclusive) and end (exclusive) times (i.e., [start, end)).

start and end are snapped up to the next grid point (the next multiple of 1/sampling_rate).

  • Gap-filled samples at the start or end of the result are trimmed, so returned data always begins and ends on real samples.

  • Gaps in the middle of the window are preserved as-is and remain filled with the gap value.

  • Slices that fall fully outside the domain or entirely within a gap return empty data.

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.

  • eps (float) – A tiny ‘rounding buffer’ to handle floating-point noise when computing indices. If your sampling rate is very high, you may need to increase this (e.g., to 1e-7) to avoid off-by-one errors.

Returns:

A new instance of the same class containing a subset of the data. The new object will have a modified Interval domain reflecting the actual sampled boundaries.

Return type:

LazyRegularTimeSeries

to_hdf5(file)[source]#

Saves the data object to an HDF5 file.

Parameters:

file (h5py.File) – HDF5 file.

import h5py
from temporaldata import RegularTimeSeries

data = RegularTimeSeries(
    raw=np.zeros((1000, 128)),
    sampling_rate=250.,
)

with h5py.File("data.h5", "w") as f:
    data.to_hdf5(f)
classmethod from_gappy_timeseries(*_args, **_kwargs)[source]#

Not implemented for LazyRegularTimeSeries.

Use RegularTimeSeries.from_gappy_timeseries() instead.

property domain: Interval#

Domain of this time series

classmethod from_dataframe(df, unsigned_to_long=True, **kwargs)#

Creates an ArrayDict object from a pandas DataFrame.

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

Parameters:

  • df (pandas.DataFrame) – DataFrame.

  • unsigned_to_long (bool, optional) – If True, automatically converts unsigned integers to int64. Defaults to True.

classmethod from_hdf5(file)[source]#

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)
index_mask()#

Boolean mask marking which samples fall inside domain.

For a gappy RegularTimeSeries (one whose domain consists of more than one interval), some positions along the time axis are fill values rather than real observations. This method returns a 1-D boolean array of length len(self) where True marks a real sample and False marks a gap (fill).

For a contiguous RegularTimeSeries (single-interval domain) the result is all True.

Returns:

1-D boolean array of shape (len(self),).

Return type:

np.ndarray

Example

>>> import numpy as np
>>> from temporaldata import RegularTimeSeries

>>> # Contiguous (non-gappy) series: every sample is real.
>>> rts = RegularTimeSeries(
...     raw=np.arange(4), sampling_rate=100.0,
... )
>>> rts.index_mask()
array([ True,  True,  True,  True])

>>> # Gappy series: 0.02s and 0.05s samples are missing.
>>> ts = [0.0, 0.01, 0.03, 0.04, 0.06]
>>> raw = [1, 2, 3, 4, 5]
>>> rts = RegularTimeSeries.from_gappy_timeseries(
...     ts, sampling_rate=100.0, raw=raw,
... )
>>> rts.index_mask()
array([ True,  True, False,  True,  True, False,  True])
>>> rts.raw  # contains fill values
array([ 1,  2, -1,  3,  4, -1,  5])
>>> rts.raw[rts.index_mask()]
array([1, 2, 3, 4, 5])
is_gappy()#

Returns True if this RegularTimeSeries has gaps.

A series is gappy when its domain is made up of more than one interval; positions inside the gaps are filled with the configured gap value (see from_gappy_timeseries()). A contiguous series (single-interval domain) returns False.

Returns:

True if the domain has more than one interval.

Return type:

bool

See also

index_mask() for a boolean mask of real vs. gap-fill samples.

Example

>>> import numpy as np
>>> from temporaldata import RegularTimeSeries

>>> rts = RegularTimeSeries(raw=np.arange(4), sampling_rate=100.0)
>>> rts.is_gappy()
False

>>> rts = RegularTimeSeries.from_gappy_timeseries(
...     [0.0, 0.01, 0.03], sampling_rate=100.0, raw=[1, 2, 3],
... )
>>> rts.is_gappy()
True
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

property sampling_rate: float#

Sampling rate in Hz

select_by_mask(mask)#

Raises a NotImplementedError as this method is not supported for RegularTimeSeries.

Raises:

NotImplementedError – Always, because this method cannot be implemented for this class.

property timestamps: ndarray#

Sample timestamps

to_irregular()#

Converts the RegularTimeSeries object to an IrregularTimeSeries object.

Gap-fill samples (where index_mask() is False) are dropped.

The returned arrays (timestamps, values, and domain) are independent copies; mutating them will not affect this RegularTimeSeries.

Returns:

IrregularTimeSeries with timestamps and all attributes copied.

Example

>>> import numpy as np
>>> from temporaldata import RegularTimeSeries

>>> # Contiguous (non-gappy) series: every sample is kept.
>>> rts = RegularTimeSeries(raw=np.arange(4), sampling_rate=10.0)
>>> irts = rts.to_irregular()
>>> irts.timestamps
array([0. , 0.1, 0.2, 0.3])
>>> irts.raw
array([0, 1, 2, 3])

>>> # Gappy series: gap-fill samples are dropped.
>>> ts = [0.0, 0.01, 0.03, 0.04, 0.06]
>>> raw = [1, 2, 3, 4, 5]
>>> rts = RegularTimeSeries.from_gappy_timeseries(
...     ts, sampling_rate=100.0, raw=raw,
... )
>>> rts.raw  # contains fill values
array([ 1,  2, -1,  3,  4, -1,  5])
>>> irts = rts.to_irregular()
>>> irts.timestamps
array([0.  , 0.01, 0.03, 0.04, 0.06])
>>> irts.raw
array([1, 2, 3, 4, 5])