# timeseries.TSContinuous

class timeseries.TSContinuous(times: Optional[Union[numpy.ndarray, List, Tuple]] = None, samples: Optional[Union[numpy.ndarray, List, Tuple]] = None, num_channels: Optional[int] = None, periodic: bool = False, t_start: Optional[float] = None, t_stop: Optional[float] = None, name: str = 'unnamed', units: Optional[str] = None, interp_kind: str = 'previous', fill_value: str = 'extrapolate')[source]

Represents a continuously-sampled time series. Mutliple time series can be represented by a single `TSContinuous` object, and have identical time bases. Temporal periodicity is supported. See Working with time series data for further explanation and examples.

Examples

Build a linearly-increasing time series that extends from 0 to 1 second

```>>> time_base = numpy.linspace(0, 1, 100)
>>> samples = time_base
>>> ts = TSContinuous(time_base, samples)
```

Build a periodic time series as a sinusoid

```>>> time_base = numpy.linspace(0, 2 * numpy.pi, 100)
>>> samples = numpy.sin(time_base)
>>> ts = TSContinuous(time_base, samples, periodic = True)
```

Build an object containing five random time series

```>>> time_base = numpy.linspace(0, 1, 100)
>>> samples = numpy.random.rand((100, 5))
>>> ts = TSContinuous(time_base, samples)
```

Manipulate time series using standard operators

```>>> ts + 5
>>> ts - 3
>>> ts * 2
>>> ts / 7
>>> ts // 3
>>> ts ** 2
>>> ts1 + ts2
...
```

Manipulate time series data in time

```>>> ts.delay(4)
>>> ts.clip(start, stop, [channel1, channel2, channel3])
```

Combine time series data

```>>> ts1.append_t(ts2)    # Appends the second time series, along the time axis
>>> ts1.append_c(ts2)    # Appends the second time series as an extra channel
```

Note

All `TSContinuous` manipulation methods return a copy by default. Most methods accept an optional `inplace` flag, which if `True` causes the operation to be performed in place.

Resample a time series using functional notation, list notation, or using the `resample()` method.

```>>> ts(0.5)
>>> ts([0, .1, .2, .3])
>>> ts(numpy.array([0, .1, .2, .3]))
>>> ts[0.5]
>>> ts[0, .1, .2, .3]
>>> ts.resample(0.5)
>>> ts.resample([0, .1, .2, .3])
```

Resample using slice notation

```>>> ts[0:.1:1]
```

Resample and select channels simultaneously

```>>> ts[0:.1:1, :3]
```
__init__(times: Optional[Union[numpy.ndarray, List, Tuple]] = None, samples: Optional[Union[numpy.ndarray, List, Tuple]] = None, num_channels: Optional[int] = None, periodic: bool = False, t_start: Optional[float] = None, t_stop: Optional[float] = None, name: str = 'unnamed', units: Optional[str] = None, interp_kind: str = 'previous', fill_value: str = 'extrapolate')[source]

TSContinuous - Represents a continuously-sample time series, supporting interpolation and periodicity.

Parameters
• times (ArrayLike) – [Tx1] vector of time samples

• samples (ArrayLike) – [TxM] matrix of values corresponding to each time sample

• num_channels (Optional[in]) – If `samples` is None, determines the number of channels of `self`. Otherwise it has no effect at all.

• periodic (bool) – Treat the time series as periodic around the end points. Default: `False`

• t_start (Optional[float]) – If not `None`, the series start time is `t_start`, otherwise `times`

• t_stop (Optional[float]) – If not `None`, the series stop time is `t_stop`, otherwise `times[-1]`

• name (str) – Name of the `TSContinuous` object. Default: `"unnamed"`

• units (Optional[str]) – Units of the `TSContinuous` object. Default: `None`

• interp_kind (str) – Specify the interpolation type. Default: `"previous"`

• fill_value (str) – Specify the method to fill values outside sample times. Default: `"extrapolate"`. Sampling beyond `.t_stop` is still not permitted

If the time series is not periodic (the default), then NaNs will be returned for any values outside `t_start` and `t_stop`.

Attributes overview

 `approx_limit_times` `beyond_range_exception` `duration` (float) Duration of TimeSeries `fill_value` `max` (float) Maximum value of time series `min` (float) Minimum value of time series `name` `num_channels` (int) Number of channels (dimension of sample vectors) in this TimeSeries object `num_traces` (int) Synonymous to `num_channels` `plotting_backend` (str) Current plotting backend `samples` (ArrayLike[float]) Value of time series at sampled times `t_start` (float) Start time of time series `t_stop` (float) Stop time of time series (final sample) `times` (ArrayLike[float]) Array of sample times

Methods overview

 `__init__`([times, samples, num_channels, ...]) TSContinuous - Represents a continuously-sample time series, supporting interpolation and periodicity. `append_c`(other_series[, inplace]) Append another time series to this one, along the samples axis (i.e. `append_t`(other_series[, offset, inplace]) Append another time series to this one, along the time axis `clip`([t_start, t_stop, channels, ...]) Return a TSContinuous which is restricted to given time limits and only contains events of selected channels `concatenate_t`(series[, offset]) Append multiple TimeSeries objects in time to a new series `contains`(times) Does the time series contain the time range specified in the given time trace? Always true for periodic series Return a deep copy of this time series `delay`(offset[, inplace]) Return a copy of `self` that is delayed by an offset `from_clocked`(samples, dt[, t_start, ...]) Convenience method to create a new continuous time series from a clocked sample. Test if this `TimeSeries` object is empty `load`(path[, expected_type]) Load TimeSeries object from file. `merge`(other_series[, remove_duplicates, inplace]) Merge other time series to this one, by interleaving in time. `plot`([times, target, channels, stagger, ...]) Visualise a time series on a line plot `print`([full, num_first, num_last, limit_shorten]) Print an overview of the time series and its values `resample`(times[, channels, inplace]) Return a new time series sampled to the supplied time base `save`(path[, verbose, dtype_times, dtype_samples]) Save this time series as an `npz` file using np.savez `set_plotting_backend`(backend[, verbose]) Set which plotting backend to use with the `plot` method `start_at`(t_start[, inplace]) Convenience function that calls the `delay` method such that `self.t_start` falls at `t_start`. `start_at_zero`([inplace]) Convenience function that calls the `delay` method such that `self.t_start` falls at `0`. Resample this time series to a synchronous clock and return the samples `to_dict`([dtype_times, dtype_samples]) Store data and attributes of this `TSContinuous` in a `dict`.
__init__(times: Optional[Union[numpy.ndarray, List, Tuple]] = None, samples: Optional[Union[numpy.ndarray, List, Tuple]] = None, num_channels: Optional[int] = None, periodic: bool = False, t_start: Optional[float] = None, t_stop: Optional[float] = None, name: str = 'unnamed', units: Optional[str] = None, interp_kind: str = 'previous', fill_value: str = 'extrapolate')[source]

TSContinuous - Represents a continuously-sample time series, supporting interpolation and periodicity.

Parameters
• times (ArrayLike) – [Tx1] vector of time samples

• samples (ArrayLike) – [TxM] matrix of values corresponding to each time sample

• num_channels (Optional[in]) – If `samples` is None, determines the number of channels of `self`. Otherwise it has no effect at all.

• periodic (bool) – Treat the time series as periodic around the end points. Default: `False`

• t_start (Optional[float]) – If not `None`, the series start time is `t_start`, otherwise `times`

• t_stop (Optional[float]) – If not `None`, the series stop time is `t_stop`, otherwise `times[-1]`

• name (str) – Name of the `TSContinuous` object. Default: `"unnamed"`

• units (Optional[str]) – Units of the `TSContinuous` object. Default: `None`

• interp_kind (str) – Specify the interpolation type. Default: `"previous"`

• fill_value (str) – Specify the method to fill values outside sample times. Default: `"extrapolate"`. Sampling beyond `.t_stop` is still not permitted

If the time series is not periodic (the default), then NaNs will be returned for any values outside `t_start` and `t_stop`.

_compatible_shape(other_samples) numpy.ndarray[source]

Attempt to make `other_samples` a compatible shape to `self.samples`.

Parameters

other_samples (ArrayLike) – Samples to convert

Return np.ndarray

Array the same shape as `self.samples`

Raises

ValueError if broadcast fails

_create_interpolator()[source]

Build an interpolator for the samples in this TimeSeries.

Replaces the current interpolator.

_interpolate(times: Union[int, float, numpy.ndarray, List, Tuple]) numpy.ndarray[source]

Interpolate the time series to the provided time points

Parameters

times (ArrayLike) – Array of `T` desired interpolated time points

Return np.ndarray

Array of interpolated values. Will have the shape `TxN`, where `N` is the number of channels in `self`

static _mask_duplicate_time_points(series0, series1, use_points1)[source]
_modulo_period(times: Union[numpy.ndarray, List, Tuple, float, int]) Union[numpy.ndarray, List, Tuple, float, int]

_modulo_period - Calculate provided times modulo `self.duration`

_samples = []
append_c(other_series: timeseries.TSContinuous, inplace: bool = False) [source]

Append another time series to this one, along the samples axis (i.e. add new channels)

Parameters
• other_series (TSContinuous) – Another time series. Will be resampled to the time base of `self`

• inplace (bool) – Conduct operation in-place (Default: `False`; create a copy)

Return TSContinuous`TSContinuous`

Current time series, with new channels appended

append_t(other_series: Union[timeseries.TSContinuous, Iterable[timeseries.TSContinuous]], offset: Optional[Union[float, Iterable[Optional[float]]]] = None, inplace: bool = False) [source]

Append another time series to this one, along the time axis

Parameters
• other_series (Union["TSContinuous", Iterable[TSContinuous]]) – Time series to be tacked on to the end of the called series object. These series must have the same number of channels as `self` or be empty.

• offset (Union[float, Iterable[float], Iterable[None], None]) – If not None, defines distance between last sample of one series and first sample of the next. Otherwise the offset will be the median of all timestep sizes of the first of the two series, or 0 if that series has len < 2.

• inplace (bool) – Conduct operation in-place (Default: `False`; create a copy)

Return TSContinuous

Time series containing data from `self`, with the other series appended in time

property approx_limit_times
property beyond_range_exception
clip(t_start: Optional[float] = None, t_stop: Optional[float] = None, channels: Optional[Union[numpy.ndarray, List, Tuple, int]] = None, include_stop: bool = True, sample_limits: bool = True, inplace: bool = False) [source]

Return a TSContinuous which is restricted to given time limits and only contains events of selected channels

Parameters
• t_start (float) – Time from which on events are returned

• t_stop (float) – Time until which events are returned

• channels (ArrayLike) – Channels of which events are returned

• include_stop (bool) – True -> If there are events with time `t_stop` include them. False -> Exclude these samples. Default: True.

• sample_limits (bool) – If True, make sure that a sample exists at `t_start` and, if `include_stop` is True, at `t_stop`, as long as not both are None.

• inplace (bool) – Conduct operation in-place (Default: False; create a copy)

Return TSContinuous

clipped_series: New TSContinuous clipped to bounds

classmethod concatenate_t(series: Iterable[timeseries.TS], offset: Optional[Union[float, Iterable[Optional[float]]]] = None) timeseries.TS

Append multiple TimeSeries objects in time to a new series

Parameters
• series (Iterable) – Time series to be tacked at the end of each other. These series must have the same number of channels.

• offset (Union[None, float, Iterable]) – Offset to be introduced between time traces. First value corresponds to delay of first time series.

Return TimeSeries

Time series with data from series in `series`

contains(times: Union[int, float, numpy.ndarray, List, Tuple]) bool

Does the time series contain the time range specified in the given time trace? Always true for periodic series

Parameters

times (ArrayLike) – Array-like containing time points

Return bool

True iff all specified time points are contained within this time series

copy() timeseries.TS

Return a deep copy of this time series

Return TimeSeries

copy of `self`

delay(offset: Union[int, float], inplace: bool = False) timeseries.TS

Return a copy of `self` that is delayed by an offset

For delaying self, use the `inplace` argument, or `.times += ...` instead.

Parameters
• Offset (float) – Time by which to offset this time series

• inplace (bool) – If `True`, conduct operation in-place (Default: `False`; create a copy)

Return TimeSeries

New `TimeSeries`, delayed

property duration: float

(float) Duration of TimeSeries

property fill_value
static from_clocked(samples: numpy.ndarray, dt: float, t_start: float = 0.0, periodic: bool = False, name: Optional[str] = None, interp_kind: str = 'previous') [source]

Convenience method to create a new continuous time series from a clocked sample.

`samples` is an array of clocked samples, sampled at a regular interval `dt`. Each sample is assumed to occur at the start of a time bin, such that the first sample occurs at `t = 0` (or `t = t_start`). A continuous time series will be returned, constructed using `samples`, and filling the time `t = 0` to `t = N*dt`, with `t_start` and `t_stop` set appropriately.

Parameters
• samples (np.ndarray) – A clocked set of contiguous-time samples, with a sample interval of `dt`. `samples` must be of shape `[T, C]`, where `T` is the number of time bins, and `C` is the number of channels.

• dt (float) – The sample interval for `samples`

• t_start (float) – The time of the first sample.

• periodic (bool) – Flag specifying whether or not the time series will be generated as a periodic series. Default:`False`, do not generate a periodic time series.

• name (Optional[str]) – Optional string to set as the name for this time series. Default: `None`

• interp_kind (str) – String specifying the interpolation method to be used for the returned time series. Any string accepted by `scipy.interp1d` is accepted. Default: `"previous"`, sample-and-hold interpolation.

:return `TSContinuous` : A continuous time series containing `samples`.

isempty() bool

Test if this `TimeSeries` object is empty

Return bool

`True` iff the `TimeSeries` object contains no samples

classmethod load(path: Union[str, pathlib.Path], expected_type: Optional[str] = None) timeseries.TS

Load TimeSeries object from file. If called from a subclass of :py:class’TimeSeries`, the type of the stored object must match that of the method class.

Parameters
Return TimeSeries

Loaded time series object

Raises
• TypeError – Unsupported or unexpected type

• TypeError – Argument `expected_type` is defined if class is not `TimeSeries`.

property max

(float) Maximum value of time series

merge(other_series: Union[timeseries.TSContinuous, Iterable[timeseries.TSContinuous]], remove_duplicates: bool = True, inplace: bool = False) [source]

Merge other time series to this one, by interleaving in time. Maintain each time series’ time values and channel IDs.

Parameters
• other_series (Union["TSContinuous", Iterable["TSContinuous"]]) – time series that is merged to self or iterable thereof to merge multiple series

• remove_duplicates (bool) – If `True`, time points in other series that are also in `self.times` are discarded. Otherwise they are included in the new time trace and come after the corresponding points of self.times.

• inplace (bool) – Conduct operation in-place (Default: `False`; create a copy)

Return TSContinuous

The merged time series

property min

(float) Minimum value of time series

property name: str
property num_channels

(int) Number of channels (dimension of sample vectors) in this TimeSeries object

property num_traces

(int) Synonymous to `num_channels`

plot(times: Optional[Union[int, float, numpy.ndarray, List, Tuple]] = None, target: Optional[Union[mpl.axes.Axes, hv.Curve, hv.Overlay]] = None, channels: Optional[Union[numpy.ndarray, List, Tuple, int]] = None, stagger: Optional[Union[float, int]] = None, skip: Optional[int] = None, dt: Optional[float] = None, *args, **kwargs)[source]

Visualise a time series on a line plot

Parameters
• times (Optional[ArrayLike]) – Time base on which to plot. Default: time base of time series

• target (Optional) – Axes (or other) object to which plot will be added.

• channels (Optional[ArrayLike]) – Channels of the time series to be plotted.

• stagger (Optional[float]) – Stagger to use to separate each series when plotting multiple series. (Default: `None`, no stagger)

• skip (Optional[int]) – Skip several series when plotting multiple series

• dt (Optiona[float]) – Resample time series to this timestep before plotting

Returns

Plot object. Either holoviews Layout, or matplotlib plot

property plotting_backend

(str) Current plotting backend

print(full: bool = False, num_first: int = 4, num_last: int = 4, limit_shorten: int = 10)[source]

Print an overview of the time series and its values

Parameters
• full (bool) – Print all samples of `self`, no matter how long it is

• num_first (int) – Shortened version of printout contains samples at first `num_first` points in `times`

• num_last (int) – Shortened version of printout contains samples at last `num_last` points in `times`

• limit_shorten (int) – Print shortened version of self if it comprises more than `limit_shorten` time points and if `full` is False

resample(times: Union[int, float, numpy.ndarray, List, Tuple], channels: Optional[Union[int, float, numpy.ndarray, List, Tuple]] = None, inplace: bool = False) [source]

Return a new time series sampled to the supplied time base

Parameters
• times (ArrayLike) – T desired time points to resample

• channels (Optional[ArrayLike]) – Channels to be used. Default: None (use all channels)

• inplace (bool) – True -> Conduct operation in-place (Default: False; create a copy)

Return TSContinuous

Time series resampled to new time base and with desired channels.

property samples

(ArrayLike[float]) Value of time series at sampled times

save(path: Union[str, pathlib.Path], verbose: bool = False, dtype_times: Union[None, str, type, numpy.dtype] = None, dtype_samples: Union[None, str, type, numpy.dtype] = None)[source]

Save this time series as an `npz` file using np.savez

Parameters
• path (str) – Path to save file

• dtype_times (Union[None, str, type, np.dtype]) – Data type in which `times` are to be stored, for example to save space.

• dtype_samples (Union[None, str, type, np.dtype]) – Data type in which `samples` are to be stored, for example to save space.

set_plotting_backend(backend: Optional[str], verbose: bool = True)

Set which plotting backend to use with the `plot` method

Parameters
• backend (str) – Specify a backend to use. Supported: {“holoviews”, “matplotlib”}

• verbose (bool) – If True, print feedback about which backend has been set

start_at(t_start: float, inplace: bool = False) timeseries.TS

Convenience function that calls the `delay` method such that `self.t_start` falls at `t_start`.

Parameters
• t_start (float) – Time to which `self.t_start` should be shifted;

• inplace (bool) – If `True`, conduct operation in-place (Default: `False`; create a copy)

Return TimeSeries

New `TimeSeries`, delayed

start_at_zero(inplace: bool = False) timeseries.TS

Convenience function that calls the `delay` method such that `self.t_start` falls at `0`.

Return TimeSeries

New TimeSeries, with t_start at 0

property t_start: float

(float) Start time of time series

property t_stop: float

(float) Stop time of time series (final sample)

property times

(ArrayLike[float]) Array of sample times

to_clocked(dt: float) numpy.ndarray[source]

Resample this time series to a synchronous clock and return the samples

This method will generate a time base that begins at `t_start` and extends to at least `t_stop`, sampled on a clock defined by `dt`. The time series will be resampled to that time base, using the defined interpolation method, and the clocked samples will be returned as a raster.

Parameters

dt (float) – The desired clock time step, in seconds

Returns

The samples from the clocked time series

Return type

np.ndarray

to_dict(dtype_times: Union[None, str, type, numpy.dtype] = None, dtype_samples: Union[None, str, type, numpy.dtype] = None) Dict[source]

Store data and attributes of this `TSContinuous` in a `dict`.

Parameters
• dtype_times (Union[None, str, type, np.dtype]) – Data type in which `times` are to be returned, for example to save space.

• dtype_samples (Union[None, str, type, np.dtype]) – Data type in which `samples` are to be returned, for example to save space.

Returns

Dict with data and attributes of this `TSContinuous`.