API Reference¶
TimeSeries¶
In traces, a TimeSeries is similar to a dictionary that contains measurements of something at different times. One difference is that you can ask for the value at any time – it doesn’t need to be at a measurement time. Let’s say you’re measuring the contents of a grocery cart by the number of minutes within a shopping trip.
>>> cart = traces.TimeSeries()
>>> cart[1.2] = {'broccoli'}
>>> cart[1.7] = {'broccoli', 'apple'}
>>> cart[2.2] = {'apple'}
>>> cart[3.5] = {'apple', 'beets'}
If you want to know what’s in the cart at 2 minutes, you can simply
get the value using cart[2]
and you’ll see {'broccoli',
'apple'}
. By default, if you ask for a time before the first
measurement, you’ll get the first measurement value.
>>> cart = traces.TimeSeries()
>>> cart[1]
set(['broccoli'])
If, however, you set the default when creating the TimeSeries, you’ll get that instead:
>>> cart = traces.TimeSeries(default=set())
>>> cart[1]
set([])
In this case, it might also make sense to add the t=0 point as a
measurement with cart[0] = set()
. If you know the time span
over which the measurements are taken and you want your code to break
if there is something out of that range, you can set a domain on the
TimeSeries.
>>> cart = traces.TimeSeries(domain=(0, 120))
>>> cart[121]
Traceback (most recent call last):
File "bunga.py", line 4, in <module>
cart[121]
File "/Users/stringer/Projects/traces/traces/timeseries.py", line 772, in __getitem__
return self.get(time)
File "/Users/stringer/Projects/traces/traces/timeseries.py", line 124, in get
raise KeyError(msg)
KeyError: '121 is outside of the domain.'
Setting an explicit domain can help avoid pesky bugs with dirty sensor data.
Performance note¶
Traces is not designed for maximal performance, but it’s no slouch since it uses the excellent sortedcontainers.SortedDict under the hood to store sparse time series.

class
traces.
TimeSeries
(data=None, default=<object object>)[source]¶ A class to help manipulate and analyze time series that are the result of taking measurements at irregular points in time. For example, here would be a simple time series that starts at 8am and goes to 9:59am:
>>> ts = TimeSeries() >>> ts['8:00am'] = 0 >>> ts['8:47am'] = 1 >>> ts['8:51am'] = 0 >>> ts['9:15am'] = 1 >>> ts['9:59am'] = 0
The value of the time series is the last recorded measurement: for example, at 8:05am the value is 0 and at 8:48am the value is 1. So:
>>> ts['8:05am'] 0
>>> ts['8:48am'] 1
There are also a bunch of things for operating on another time series: sums, difference, logical operators and such.

compact
()[source]¶ Convert this instance to a compact version: the value will be the same at all times, but repeated measurements are discarded.

default
¶ Return the default value of the time series.

distribution
(start=None, end=None, normalized=True, mask=None)[source]¶ Calculate the distribution of values over the given time range from start to end.
Parameters:  start (orderable, optional) – The lower time bound of when to calculate the distribution. By default, the first time point will be used.
 end (orderable, optional) – The upper time bound of when to calculate the distribution. By default, the last time point will be used.
 normalized (bool) – If True, distribution will sum to one. If False and the time values of the TimeSeries are datetimes, the units will be seconds.
 mask (
Domain
orTimeSeries
, optional) – A Domain on which to calculate the distribution.
Returns: Histogram
with the results.

get
(time, interpolate='previous')[source]¶ Get the value of the time series, even inbetween measured values.

is_floating
()[source]¶ An empty TimeSeries with no specific default value is said to be “floating”, since the value of the TimeSeries is undefined. Any operation that needs to look up the value of the TimeSeries is not defined on a floating TimeSeries.

classmethod
iter_merge
(timeseries_list)[source]¶ Iterate through several time series in order, yielding (time, list) tuples where list is the values of each individual TimeSeries in the list at time t.

iterintervals
(n=2)[source]¶ Iterate over groups of n consecutive measurement points in the time series.

iterperiods
(start=None, end=None, value=None)[source]¶ This iterates over the periods (optionally, within a given time span) and yields (interval start, interval end, value) tuples.
TODO: add mask argument here.

mean
(start=None, end=None, mask=None)[source]¶ This calculated the average value of the time series over the given time range from start to end.

classmethod
merge
(ts_list, compact=True, operation=None, default=None)[source]¶ Iterate through several time series in order, yielding (time, value) where value is the either the list of each individual TimeSeries in the list at time t (in the same order as in ts_list) or the result of the optional operation on that list of values.

moving_average
(sampling_period, window_size=None, start=None, end=None, placement='center', pandas=False)[source]¶ Averaging over regular intervals

n_points
(start=inf, end=inf, mask=None, include_start=True, include_end=False, normalized=False)[source]¶ Calculate the number of points over the given time range from start to end.
Parameters:  start (orderable, optional) – The lower time bound of when to calculate the distribution. By default, start is infinity.
 end (orderable, optional) – The upper time bound of when to calculate the distribution. By default, the end is +infinity.
 mask (
Domain
orTimeSeries
, optional) – A Domain on which to calculate the distribution.
Returns: int with the result

operation
(other, function, **kwargs)[source]¶ Calculate “elementwise” operation either between this TimeSeries and another one, i.e.
operation(t) = function(self(t), other(t))
or between this timeseries and a constant:
operation(t) = function(self(t), other)
If it’s another time series, the measurement times in the resulting TimeSeries will be the union of the sets of measurement times of the input time series. If it’s a constant, the measurement times will not change.

remove
(time)[source]¶ Allow removal of measurements from the time series. This throws an error if the given time is not actually a measurement point.

remove_points_from_interval
(start, end)[source]¶ Allow removal of all points from the time series within a interval [start:end].

sample
(sampling_period, start=None, end=None, interpolate='previous')[source]¶ Sampling at regular time periods.

set
(time, value, compact=False)[source]¶ Set the value for the time series. If compact is True, only set the value if it’s different from what it would be anyway.

set_interval
(start, end, value, compact=False)[source]¶ Set the value for the time series on an interval. If compact is True, only set the value if it’s different from what it would be anyway.

slice
(start, end)[source]¶ Return an equivalent TimeSeries that only has points between start and end (always starting at start)

Domain¶

class
traces.
Domain
(data=None)[source]¶ Initialize with:
>>> Domain(1, 4) >>> Domain([1, 4]) >>> Domain((1, 4)) >>> Domain([[1, 4]]) >>> Domain([(1, 4)]) >>> Domain((1, 4), (5, 8)) >>> Domain([1, 4], [5, 8]) >>> Domain([(1, 4), (5, 8)]) >>> Domain([[1, 4], [5, 8]])
Domain has to be closed intervals. It can be open toward inf or inf. For example, Domain(inf, 3) means a domain from inf to 3 inclusive.