data_tools.collections.TimeSeries

class data_tools.collections.TimeSeries(input_array, start_time: datetime = None, stop_time: datetime = None, period: float = None, length: float = None, units=None, meta: dict = None)

Bases: ndarray

This class encapsulates time-series data with units, a temporal x–axis, and metadata.

Data is homogenous and evenly-spaced, such that temporal period between subsequent elements is constant.

__init__(input_array, start_time: datetime, stop_time: datetime, period: float, length: float, units: Unit | str = None, meta: dict = None)

Methods

__init__(input_array, start_time, stop_time, ...)
align(*args)
all([axis, out, keepdims, where])	Returns True if all elements evaluate to True.
any([axis, out, keepdims, where])	Returns True if any of the elements of a evaluate to True.
argmax([axis, out, keepdims])	Return indices of the maximum values along the given axis.
argmin([axis, out, keepdims])	Return indices of the minimum values along the given axis.
argpartition(kth[, axis, kind, order])	Returns the indices that would partition this array.
argsort([axis, kind, order])	Returns the indices that would sort this array.
astype(dtype[, order, casting, subok, copy])	Copy of the array, cast to a specified type.
byteswap([inplace])	Swap the bytes of the array elements
choose(choices[, out, mode])	Use an index array to construct a new array from a set of choices.
clip([min, max, out])	Return an array whose values are limited to [min, max].
compress(condition[, axis, out])	Return selected slices of this array along given axis.
conj()	Complex-conjugate all elements.
conjugate()	Return the complex conjugate, element-wise.
convert_to(new_unit)	Returns a new TimeSeries after being converted to a new unit, appropriately scales TimeSeries
convert_to_base_units()	Converts TimeSeries units to the unit registry system base units (SI Units by default)
copy([order])	Return a copy of the array.
cumprod([axis, dtype, out])	Return the cumulative product of the elements along the given axis.
cumsum([axis, dtype, out])	Return the cumulative sum of the elements along the given axis.
diagonal([offset, axis1, axis2])	Return specified diagonals.
dot
dump(file)	Dump a pickle of the array to the specified file.
dumps()	Returns the pickle of the array as a string.
fill(value)	Fill the array with a scalar value.
flatten([order])	Return a copy of the array collapsed into one dimension.
from_csv(path, period, field)
from_query_dataframe(query_df, period, ...)
generate_timeseries(x_axis, y_axis, period, ...)	Creates a TimeSeries from a non-homogeneous / not evenly spaces set of data with a specified period.
getfield(dtype[, offset])	Returns a field of the given array as a certain type.
index_of(time)	Return the index of the data element that represents the time closest to time.
interpolate_indices(i)	Function which interpolates between the two nearest indices
item(*args)	Copy an element of an array to a standard Python scalar and return it.
max([axis, out, keepdims, initial, where])	Return the maximum along a given axis.
mean([axis, dtype, out, keepdims, where])	Returns the average of the array elements along given axis.
merge(*args[, fill_value])	The merge function combines several TimeSeries into one contiguous series.
min([axis, out, keepdims, initial, where])	Return the minimum along a given axis.
nonzero()	Return the indices of the elements that are non-zero.
override_units(new_unit)	Overrides the units of a TimeSeries, directly changes one unit for another.
partition(kth[, axis, kind, order])	Partially sorts the elements in the array in such a way that the value of the element in k-th position is in the position it would be in a sorted array.
plot([show])	Make a simple plot this data.
prod	a.prod(axis=None, dtype=None, out=None, keepdims=False,
promote(array)	Promote a plain ndarray, array, to a TimeSeries with the same properties as this TimeSeries (start_time, stop_time, period, length, units, meta)
put(indices, values[, mode])	Set a.flat[n] = values[n] for all n in indices.
ravel([order])	Return a flattened array.
relative_time(unix_time)	Return the relative time of the UNIX timestamp time.
repeat(repeats[, axis])	Repeat elements of an array.
reshape(shape, /, *[, order, copy])	Returns an array containing the same data with a new shape.
resize(new_shape[, refcheck])	Change shape and size of array in-place.
round([decimals, out])	Return a with each element rounded to the given number of decimals.
searchsorted(v[, side, sorter])	Find indices where elements of v should be inserted in a to maintain order.
setfield(val, dtype[, offset])	Put a value into a specified place in a field defined by a data-type.
setflags([write, align, uic])	Set array flags WRITEABLE, ALIGNED, WRITEBACKIFCOPY, respectively.
shift(shift)	A function which moves a TimeSeries backwards or forwards in time without changing any data inside it.
slice(start_time, end_time)	This function returns all values between two given points, useful for filtering out data for specific dates or times.
sort([axis, kind, order])	Sort an array in-place.
squeeze([axis])	Remove axes of length one from a.
std([axis, dtype, out, ddof, keepdims, where])	Returns the standard deviation of the array elements along given axis.
sum([axis, dtype, out, keepdims, initial, where])	Return the sum of the array elements over the given axis.
swapaxes(axis1, axis2)	Return a view of the array with axis1 and axis2 interchanged.
take(indices[, axis, out, mode])	Return an array formed from the elements of a at the given indices.
to_device
tobytes([order])	Construct Python bytes containing the raw data bytes in the array.
tofile(fid[, sep, format])	Write array to a file as text or binary (default).
tolist()	Return the array as an a.ndim-levels deep nested list of Python scalars.
tostring([order])	A compatibility alias for ~ndarray.tobytes, with exactly the same behavior.
trace([offset, axis1, axis2, dtype, out])	Return the sum along diagonals of the array.
transpose(*axes)	Returns a view of the array with axes transposed.
var([axis, dtype, out, ddof, keepdims, where])	Returns the variance of the array elements, along given axis.
view([dtype][, type])	New view of array with the same data.

Attributes

T	View of the transposed array.
base	Base object if memory is from some other object.
ctypes	An object to simplify the interaction of the array with the ctypes module.
data	Python buffer object pointing to the start of the array's data.
datetime_x_axis	This wave's x–axis as timezone-aware datetimes.
device
dtype	Data-type of the array's elements.
flags	Information about the memory layout of the array.
flat	A 1-D iterator over the array.
imag	The imaginary part of the array.
itemset
itemsize	Length of one array element in bytes.
length	Total time between the first and last element of this wave's data
mT	View of the matrix transposed array.
meta	Metadata such as the field, measurement, and car.
nbytes	Total bytes consumed by the elements of the array.
ndim	Number of array dimensions.
newbyteorder
period	Get the period, in seconds, between data points of this TimeSeries.
ptp
real	The real part of the array.
shape	Tuple of array dimensions.
size	Number of elements in the array.
start	UTC datetime of the first data element
stop	UTC datetime of the last data element
strides	Tuple of bytes to step in each dimension when traversing an array.
units	The units of this wave's data
unix_x_axis	This wave's x–axis as UTC UNIX timestamps.
x_axis	This wave's x–axis in relative seconds, such that the first element is t=0.

static align(*args) → list

convert_to(new_unit: Unit | str)

Returns a new TimeSeries after being converted to a new unit, appropriately scales TimeSeries

Parameters:

new_unit (str) – The unit the entire series will be translated to

Raises:

• ValueError – Cannot convert TimeSeries without units

• ValueError – Unable to convert between units of different dimensionality

Returns:

TimeSeries with converted units

convert_to_base_units()

Converts TimeSeries units to the unit registry system base units (SI Units by default)

Return TimeSeries:

Timeseries with converted units

property datetime_x_axis: ndarray

This wave’s x–axis as timezone-aware datetimes.

static from_csv(path, period, field)

static from_query_dataframe(query_df: DataFrame, period: float, field: str, units: Unit | str)

static generate_timeseries(x_axis: list, y_axis: list, period: float, units: Unit | str, timezone: timezone = datetime.timezone.utc, meta: dict = None)

Creates a TimeSeries from a non-homogeneous / not evenly spaces set of data with a specified period. Useful for converting weirder data into a neat TimeSeries.

Parameters:

• x_axis (list) – Data point times

• y_axis (list) – Data points

• period (float) – Time between data points in seconds

• units (str | Unit) – Units of the TimeSeries

• timezone (datetime.timezone) – Timezone

• meta (dict) – Metadata for the TimeSeries

Returns:

Homogenized TimeSeries

index_of(time: float) → int

Return the index of the data element that represents the time closest to time.

Parameters:

time (float) – time (in seconds) that will be evaluated against

Raises:

ValueError if time falls outside of x–axis

interpolate_indices(i: float) → float

Function which interpolates between the two nearest indices

Parameters:

i (float) – floating index

Return float:

interpolated value

property length: float

Total time between the first and last element of this wave’s data

static merge(*args, fill_value: float = 0)

The merge function combines several TimeSeries into one contiguous series. Any spaces in time is filled by the ‘fill_value’. It assumes that the datapoints pull from the same source, as overlapping point are overridden.

Parameters:

fill_value (float) – The value for filling between gaps of time. Defaults to 0.

Raises:

ValueError – If no TimeSeries are input

Return TimeSeries:

The merged series

property meta: dict

Metadata such as the field, measurement, and car.

override_units(new_unit: Unit | str)

Overrides the units of a TimeSeries, directly changes one unit for another. Does not convert magnitudes! If you wish to convert units, use .convert_to()

param str new_unit:

The unit the entire series will be translated to

raises ValueError:

Cannot convert TimeSeries without units

property period: float

Get the period, in seconds, between data points of this TimeSeries.

Returns:

period, in seconds.

plot(show=True) → None

Make a simple plot this data. :param bool show: Show plots (disable if you want to stack multiple plots, for example).

promote(array: ndarray)

Promote a plain ndarray, array, to a TimeSeries with the same properties as this TimeSeries (start_time, stop_time, period, length, units, meta)

This method is particularly useful for interfacing with libraries such as SciPy and NumPy, which will return an ndarray even when given a TimeSeries.

Parameters:

array – plain ndarray to be promoted

Returns:

new, promoted TimeSeries with the same properties as this TimeSeries

relative_time(unix_time: float) → float

Return the relative time of the UNIX timestamp time. :param float unix_time: UNIX timestamp that will be converted

shift(shift: float | timedelta)

A function which moves a TimeSeries backwards or forwards in time without changing any data inside it. Can have timedelta or a float as an input

Parameters:

shift (float | datetime.timedelta) – The amount of seconds the series should be shifted

Return TimeSeries:

Shifted timeseries

slice(start_time: datetime, end_time: datetime)

This function returns all values between two given points, useful for filtering out data for specific dates or times. The returned series will not have the argument start_time and end_time, instead the returned series will align the start and end time to existing points

Parameters:

• start_time (datetime.datetime) – The start datetime to slice with

• end_time (datetime.datetime) – The end datetime to slice with

Raises:

• ValueError – Naive inputs (Inputs do not have assigned timezones)

• ValueError – start_time is after stop_time

• ValueError – stop_time is before TimeSeries start time

• ValueError – start_time is after TimeSeries stop time

Return TimeSeries:

Returns a series with all values between start and stop time

property start: datetime

UTC datetime of the first data element

property stop: datetime

UTC datetime of the last data element

property units: Unit

The units of this wave’s data

property unix_x_axis: ndarray

This wave’s x–axis as UTC UNIX timestamps.

property x_axis: ndarray

This wave’s x–axis in relative seconds, such that the first element is t=0.