TimeSeries¶

class ptsa.data.timeseries.TimeSeries(data, coords, dims=None, name=None, attrs=None, fastpath=False, **kwargs)¶

A thin wrapper around xr.DataArray for dealing with time series data.

Note that xarray internals prevent us from overriding the constructor which leads to some awkwardness: you must pass coords as a dict with a samplerate entry.

Parameters:

data (array-like) – Time series data
coords (dict-like) – Coordinate arrays. This must contain at least a samplerate coordinate.
dims (array-like) – Dimension labels
name (str) – Name of the time series
attrs (dict) – Dictionary of arbitrary metadata
fastpath (bool) – Not used, but required when subclassing xr.DataArray.

Raises:

AssertionError – When samplerate is not present in coords.

See also

numpy.ndarray.astype, dask.array.Array.astype, sparse.COO.astype

baseline_corrected(base_range)¶

Return a baseline corrected timeseries by subtracting the average value in the baseline range from all other time points for each dimension.

Parameters:: base_range ({tuple}) – Tuple specifying the start and end time range (inclusive) for the baseline.
Returns:: ts – A TimeSeries instance with the baseline corrected data.
Return type:: {TimeSeries}

coerce_to(dtype=<class 'numpy.float64'>)¶: Coerce the data to the specified dtype in place. If dtype is None, this method does nothing. Default: coerce to np.float64.

count(dim=None, axis=None, **kwargs)¶

Reduce this TimeSeries’s data by applying count along some dimension(s).

Parameters:

dim (str or sequence of str, optional) – Dimension(s) over which to apply count.
axis (int or sequence of int, optional) – Axis(es) over which to apply count. Only one of the ‘dim’ and ‘axis’ arguments can be supplied. If neither are supplied, then count is calculated over axes.
keep_attrs (bool, optional) – If True, the attributes (attrs) will be copied from the original object to the new one. If False (default), the new object will be returned without attributes.
**kwargs (dict) – Additional keyword arguments passed on to the appropriate array function for calculating count on this object’s data.

Returns:

reduced – New TimeSeries object with count applied to its data and the indicated dimension(s) removed.

Return type:

TimeSeries

classmethod create(data, samplerate, coords=None, dims=None, name=None, attrs=None)¶: Factory function for creating a new timeseries object with passing the sample rate as a parameter. See __init__() for parameters.

cumprod(dim=None, axis=None, skipna=None, **kwargs)¶

Apply cumprod along some dimension of TimeSeries.

Parameters:

dim (str or sequence of str, optional) – Dimension over which to apply cumprod.
axis (int or sequence of int, optional) – Axis over which to apply cumprod. Only one of the ‘dim’ and ‘axis’ arguments can be supplied.
skipna (bool, optional) – If True, skip missing values (as marked by NaN). By default, only skips missing values for float dtypes; other dtypes either do not have a sentinel missing value (int) or skipna=True has not been implemented (object, datetime64 or timedelta64).
keep_attrs (bool, optional) – If True, the attributes (attrs) will be copied from the original object to the new one. If False (default), the new object will be returned without attributes.
**kwargs (dict) – Additional keyword arguments passed on to cumprod.

Returns:

cumvalue – New TimeSeries object with cumprod applied to its data along the indicated dimension.

Return type:

TimeSeries

cumsum(dim=None, axis=None, skipna=None, **kwargs)¶

Apply cumsum along some dimension of TimeSeries.

Parameters:

dim (str or sequence of str, optional) – Dimension over which to apply cumsum.
axis (int or sequence of int, optional) – Axis over which to apply cumsum. Only one of the ‘dim’ and ‘axis’ arguments can be supplied.
skipna (bool, optional) – If True, skip missing values (as marked by NaN). By default, only skips missing values for float dtypes; other dtypes either do not have a sentinel missing value (int) or skipna=True has not been implemented (object, datetime64 or timedelta64).
keep_attrs (bool, optional) – If True, the attributes (attrs) will be copied from the original object to the new one. If False (default), the new object will be returned without attributes.
**kwargs (dict) – Additional keyword arguments passed on to cumsum.

Returns:

cumvalue – New TimeSeries object with cumsum applied to its data along the indicated dimension.

Return type:

TimeSeries

filter_with(filters)¶

Filter the time series data using the specified filters in order.

Parameters:: filters (BaseFilter or Iterable[BaseFilter]) – The filter(s) to use.
Returns:: filtered – The resulting data from the filter.
Return type:: TimeSeries
Raises:: TypeError – When filter_class is not a valid filter class.

filtered(freq_range, filt_type='stop', order=4)¶

Filter the data using a Butterworth filter and return a new TimeSeries instance.

Parameters:

freq_range (array-like) – The range of frequencies to filter.
filt_type (str) – Filter type (default: 'stop').
order (int) – The order of the filter (default: 4).

Returns:

ts – A TimeSeries instance with the filtered data.

Return type:

TimeSeries

classmethod from_hdf(filename, engine='netcdf4', **kwargs)¶

Load a serialized time series from an HDF5 file. Uses

Parameters:: filename (str) – Path to HDF5 file.

item(*args)¶

Copy an element of an array to a standard Python scalar and return it.

Parameters:

*args (Arguments (variable number and type)) –

none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.
int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.
tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.

Returns:

z – A copy of the specified element of the array as a suitable Python scalar

Return type:

Standard Python scalar object

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
       [1, 3, 6],
       [1, 0, 1]])
>>> x.item(3)
1
>>> x.item(7)
0
>>> x.item((0, 1))
2
>>> x.item((2, 2))
1

max(dim=None, axis=None, skipna=None, **kwargs)¶

Reduce this TimeSeries’s data by applying max along some dimension(s).

Parameters:

dim (str or sequence of str, optional) – Dimension(s) over which to apply max.
axis (int or sequence of int, optional) – Axis(es) over which to apply max. Only one of the ‘dim’ and ‘axis’ arguments can be supplied. If neither are supplied, then max is calculated over axes.
skipna (bool, optional) – If True, skip missing values (as marked by NaN). By default, only skips missing values for float dtypes; other dtypes either do not have a sentinel missing value (int) or skipna=True has not been implemented (object, datetime64 or timedelta64).
keep_attrs (bool, optional) – If True, the attributes (attrs) will be copied from the original object to the new one. If False (default), the new object will be returned without attributes.
**kwargs (dict) – Additional keyword arguments passed on to the appropriate array function for calculating max on this object’s data.

Returns:

reduced – New TimeSeries object with max applied to its data and the indicated dimension(s) removed.

Return type:

TimeSeries

mean(dim=None, axis=None, skipna=None, **kwargs)¶

Reduce this TimeSeries’s data by applying mean along some dimension(s).

Parameters:

dim (str or sequence of str, optional) – Dimension(s) over which to apply mean.
axis (int or sequence of int, optional) – Axis(es) over which to apply mean. Only one of the ‘dim’ and ‘axis’ arguments can be supplied. If neither are supplied, then mean is calculated over axes.
skipna (bool, optional) – If True, skip missing values (as marked by NaN). By default, only skips missing values for float dtypes; other dtypes either do not have a sentinel missing value (int) or skipna=True has not been implemented (object, datetime64 or timedelta64).
keep_attrs (bool, optional) – If True, the attributes (attrs) will be copied from the original object to the new one. If False (default), the new object will be returned without attributes.
**kwargs (dict) – Additional keyword arguments passed on to the appropriate array function for calculating mean on this object’s data.

Returns:

reduced – New TimeSeries object with mean applied to its data and the indicated dimension(s) removed.

Return type:

TimeSeries

median(dim=None, axis=None, skipna=None, **kwargs)¶

Reduce this TimeSeries’s data by applying median along some dimension(s).

Parameters:

dim (str or sequence of str, optional) – Dimension(s) over which to apply median.
axis (int or sequence of int, optional) – Axis(es) over which to apply median. Only one of the ‘dim’ and ‘axis’ arguments can be supplied. If neither are supplied, then median is calculated over axes.
skipna (bool, optional) – If True, skip missing values (as marked by NaN). By default, only skips missing values for float dtypes; other dtypes either do not have a sentinel missing value (int) or skipna=True has not been implemented (object, datetime64 or timedelta64).
keep_attrs (bool, optional) – If True, the attributes (attrs) will be copied from the original object to the new one. If False (default), the new object will be returned without attributes.
**kwargs (dict) – Additional keyword arguments passed on to the appropriate array function for calculating median on this object’s data.

Returns:

reduced – New TimeSeries object with median applied to its data and the indicated dimension(s) removed.

Return type:

TimeSeries

min(dim=None, axis=None, skipna=None, **kwargs)¶

Reduce this TimeSeries’s data by applying min along some dimension(s).

Parameters:

dim (str or sequence of str, optional) – Dimension(s) over which to apply min.
axis (int or sequence of int, optional) – Axis(es) over which to apply min. Only one of the ‘dim’ and ‘axis’ arguments can be supplied. If neither are supplied, then min is calculated over axes.
skipna (bool, optional) – If True, skip missing values (as marked by NaN). By default, only skips missing values for float dtypes; other dtypes either do not have a sentinel missing value (int) or skipna=True has not been implemented (object, datetime64 or timedelta64).
keep_attrs (bool, optional) – If True, the attributes (attrs) will be copied from the original object to the new one. If False (default), the new object will be returned without attributes.
**kwargs (dict) – Additional keyword arguments passed on to the appropriate array function for calculating min on this object’s data.

Returns:

reduced – New TimeSeries object with min applied to its data and the indicated dimension(s) removed.

Return type:

TimeSeries

prod(dim=None, axis=None, skipna=None, **kwargs)¶

Reduce this TimeSeries’s data by applying prod along some dimension(s).

Parameters:

dim (str or sequence of str, optional) – Dimension(s) over which to apply prod.
axis (int or sequence of int, optional) – Axis(es) over which to apply prod. Only one of the ‘dim’ and ‘axis’ arguments can be supplied. If neither are supplied, then prod is calculated over axes.
skipna (bool, optional) – If True, skip missing values (as marked by NaN). By default, only skips missing values for float dtypes; other dtypes either do not have a sentinel missing value (int) or skipna=True has not been implemented (object, datetime64 or timedelta64).
min_count (int, default: None) – The required number of valid values to perform the operation. If fewer than min_count non-NA values are present the result will be NA. Only used if skipna is set to True or defaults to True for the array’s dtype. New in version 0.10.8: Added with the default being None. Changed in version 0.17.0: if specified on an integer array and skipna=True, the result will be a float array.
keep_attrs (bool, optional) – If True, the attributes (attrs) will be copied from the original object to the new one. If False (default), the new object will be returned without attributes.
**kwargs (dict) – Additional keyword arguments passed on to the appropriate array function for calculating prod on this object’s data.

Returns:

reduced – New TimeSeries object with prod applied to its data and the indicated dimension(s) removed.

Return type:

TimeSeries

query(**kwargs)¶

Wraps the following, returning as a TimeSeries: Return a new data array indexed along the specified

dimension(s), where the indexers are given as strings containing Python expressions to be evaluated against the values in the array.

queriesdict, optional
A dict with keys matching dimensions and values given by strings containing Python expressions to be evaluated against the data variables in the dataset. The expressions will be evaluated using the pandas eval() function, and can contain any valid Python expressions but cannot contain any Python statements.

parser{“pandas”, “python”}, default: “pandas”
The parser to use to construct the syntax tree from the expression. The default of ‘pandas’ parses code slightly different than standard Python. Alternatively, you can parse an expression using the ‘python’ parser to retain strict Python semantics.

engine{“python”, “numexpr”, None}, default: None
The engine used to evaluate the expression. Supported engines are: - None: tries to use numexpr, falls back to python - “numexpr”: evaluates expressions using numexpr - “python”: performs operations as if you had eval’d in top level python

missing_dims{“raise”, “warn”, “ignore”}, default: “raise”
What to do if dimensions that should be selected from are not present in the Dataset: - “raise”: raise an exception - “warn”: raise a warning, and ignore the missing dimensions - “ignore”: ignore the missing dimensions

**queries_kwargs{dim: query, …}, optional
The keyword arguments form of queries. One of queries or queries_kwargs must be provided.

objDataArray
A new DataArray with the same contents as this dataset, indexed by the results of the appropriate queries.

DataArray.isel Dataset.query pandas.eval
>>> da = xr.DataArray(np.arange(0, 5, 1), dims="x", name="a")
>>> da
<xarray.DataArray 'a' (x: 5)>
array([0, 1, 2, 3, 4])
Dimensions without coordinates: x
>>> da.query(x="a > 2")
<xarray.DataArray 'a' (x: 2)>
array([3, 4])
Dimensions without coordinates: x

reduce(**kwargs)¶

Wraps the following, returning as a TimeSeries: Reduce this array by applying func along some dimension(s).

funccallable
Function which can be called in the form f(x, axis=axis, **kwargs) to return the result of reducing an np.ndarray over an integer valued axis.

dimhashable or sequence of hashable, optional
Dimension(s) over which to apply func.

axisint or sequence of int, optional
Axis(es) over which to repeatedly apply func. Only one of the ‘dim’ and ‘axis’ arguments can be supplied. If neither are supplied, then the reduction is calculated over the flattened array (by calling f(x) without an axis argument).

keep_attrsbool, optional
If True, the variable’s attributes (attrs) will be copied from the original object to the new one. If False (default), the new object will be returned without attributes.

keepdimsbool, default: False
If True, the dimensions which are reduced are left in the result as dimensions of size one. Coordinates that use these dimensions are removed.

**kwargsdict
Additional keyword arguments passed on to func.

reducedDataArray
DataArray with this object’s array replaced with an array with summarized data and the indicated dimension(s) removed.

remove_buffer(duration)¶

Return a timeseries with the desired buffer duration (in seconds) removed and the time range reset.

Parameters:: duration (float) – The duration to be removed. The units depend on the samplerate: E.g., if samplerate is specified in Hz (i.e., samples per second), the duration needs to be specified in seconds and if samplerate is specified in kHz (i.e., samples per millisecond), the duration needs to be specified in milliseconds. The specified duration is removed from the beginning and end.
Returns:: ts – A TimeSeries instance with the requested durations removed from the beginning and/or end.
Return type:: TimeSeries

resampled(resampled_rate, window=None, loop_axis=None, num_mp_procs=0, pad_to_pow2=False)¶

Returns a time series Fourier resampled at resampled_rate.

Note that Fourier resampling assumes periodicity, so edge effects can arise. Keeping a buffer of at least 1/f for the lowest frequency of interest guards against this.

Parameters:

resampled_rate (float) – New sample rate
window – ignored for now - added for legacy reasons
loop_axis – ignored for now - added for legacy reasons
num_mp_procs – ignored for now - added for legacy reasons
pad_to_pow2 – ignored for now - added for legacy reasons

Return type:

Resampled time series

searchsorted(v, side='left', sorter=None)¶

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted