TimeSeries

class timeseries.TimeSeries(dates, values)

Bases: object

Data structure for one-dimensional time series.

Allows for easy indexing and various convenient time series calculations including mean, variance, customizable filtering, cross-correlations, element-wise addition etc. Time series data is automatically sorted in chronological order by date.

Parameters

• dates – finite-length iterable of datetime objects

• values – finite-length iterable of float-convertable numbers

Example

>>> from datetime import datetime
>>> import timeseries as ts
>>> date1 = datetime.fromisoformat('1970-01-01')
>>> date2 = datetime.fromisoformat('1970-01-02')
>>> date3 = datetime.fromisoformat('1970-01-03')
>>> dates = (date2, date1, date3)
>>> values = (2, 1, 3)
>>> tseries = ts.TimeSeries(dates, values)

The time series is automatically ordered by dates with the earliest entry on top and the latest entry at the bottom. Various attributes allow for inspection of the data contained in the time series.

>>> tseries
date                            value
1970-01-01 00:00:00              1.00
1970-01-02 00:00:00              2.00
1970-01-03 00:00:00              3.00

>>> tseries.dates[1]
datetime.datetime(1970, 1, 2, 0, 0)

>>> tseries.iso_dates
('1970-01-01T00:00:00', '1970-01-02T00:00:00', '1970-01-03T00:00:00')

>>> tseries.values
(1.0, 2.0, 3.0)

The get_value method can be called explicitly to retrieve the value at the provided date (either ISO format or a datetime object).

>>> tseries.get_value(date2)
2.0

>>> tseries.get_value('1970-01-02')
2.0

Multiple options are available for slicing and subsetting an existing time series object. The time series can be sliced by the positional indices of entries like a list and single-element time series can be created from integer, datetime or string keys. Chronological order is maintained regardless of the order of the key.

>>> tseries[0::2]
date                            value
1970-01-01 00:00:00              1.00
1970-01-03 00:00:00              3.00

>>> tseries[0]
date                            value
1970-01-01 00:00:00              1.00

>>> tseries[date3]
date                            value
1970-01-03 00:00:00              3.00

>>> tseries['1970-01-03']
date                            value
1970-01-03 00:00:00              3.00

Subsetting by iterables of positional indices, datetimes or strings is also supported.

>>> tseries[[1,0]]
date                            value
1970-01-01 00:00:00              1.00
1970-01-02 00:00:00              2.00

>>> tseries[['1970-01-03', '1970-01-02']]
date                            value
1970-01-02 00:00:00              2.00
1970-01-03 00:00:00              3.00

Simple statistics can be computed from mean and variance methods.

>>> tseries.mean()
2.0

>>> tseries.variance()
1.0

Time series overload basic arithmetic operations by applying set operations to dates, e.g. elementwise addition applies to union of dates by default, while multiplication applies to the intersection of dates.

>>> date4 = datetime.fromisoformat('1970-01-04')
>>> dates2 = (date1, date2, date4)
>>> values2 = (1, 2, 4)
>>> tseries2 = ts.TimeSeries(dates2, values2)

>>> tseries
date                            value
1970-01-01 00:00:00              1.00
1970-01-02 00:00:00              2.00
1970-01-03 00:00:00              3.00

>>> tseries2
date                            value
1970-01-01 00:00:00              1.00
1970-01-02 00:00:00              2.00
1970-01-04 00:00:00              4.00

>>> tseries + tseries2
date                            value
1970-01-01 00:00:00              2.00
1970-01-02 00:00:00              4.00
1970-01-03 00:00:00              3.00
1970-01-04 00:00:00              4.00

>>> tseries - tseries2
date                            value
1970-01-01 00:00:00              0.00
1970-01-02 00:00:00              0.00
1970-01-03 00:00:00              3.00
1970-01-04 00:00:00             -4.00

>>> tseries * tseries2
date                            value
1970-01-01 00:00:00              1.00
1970-01-02 00:00:00              4.00

>>> tseries2 ** tseries
date                            value
1970-01-01 00:00:00              1.00
1970-01-02 00:00:00              4.00

Broadcasting to elementwise operations is supported for float-convertable values across these operations.

>>> (tseries+1) / 2
date                            value
1970-01-01 00:00:00              1.00
1970-01-02 00:00:00              1.50
1970-01-03 00:00:00              2.00

The set operation and fill values can be chosen by calling methods directly and providing arguments.

>>> tseries.add(tseries2, operation='intersection')
date                            value
1970-01-01 00:00:00              2.00
1970-01-02 00:00:00              4.00

The operator attribute allows for even more customizable applications of functions, with direct specification of function to apply, set operations and fill values for preprocessing disjoint time series. Aggregation functions can be implemented via the elementwise flag.

>>> from timeseries.stats import crosscovariance
>>> tseries.operator.custom(crosscovariance, tseries2, elementwise=False)
0.5

The above example computes the cross-covariance on the intersecting dates. This and the cross-correlation can alternatively be computed by calling their respective methods directly.

>>> tseries.crosscovariance(tseries2)
0.5

>>> tseries.crosscorrelation(tseries2)
1.0

Basic filtering can be executed by direct calls to various methods. Support includes simple moving averages, exponential moving averages and rolling variance.

>>> tseries.moving_average(window_size=2)
date                            value
1970-01-02 00:00:00              1.50
1970-01-03 00:00:00              2.50

>>> tseries.exponential_moving_average(alpha=0.1)
date                            value
1970-01-01 00:00:00              1.00
1970-01-02 00:00:00              1.10
1970-01-03 00:00:00              1.29

>>> tseries.rolling_variance(2)
date                            value
1970-01-02 00:00:00              0.50
1970-01-03 00:00:00              0.50

More advanced filtering methods can be accessed via the rolling method, which provides an interface to customizable rolling window functionality, including variable weighting of values and custom functions.

>>> tseries.rolling(2, weights='none').get_weights()
[1, 1]

>>> tseries.rolling(2, weights='none').custom(ts.stats.variance)
date                            value
1970-01-02 00:00:00              0.50
1970-01-03 00:00:00              0.50

>>> tseries.rolling(2, weights='none').sum()
date                            value
1970-01-02 00:00:00              3.00
1970-01-03 00:00:00              5.00

>>> tseries.rolling(2, weights='linear', min_weight=0.2).get_weights()
[0.2, 0.8]

>>> tseries.rolling(2, weights='linear', min_weight=0.2).sum()
date                            value
1970-01-02 00:00:00              1.80
1970-01-03 00:00:00              2.80

property dates

Return tuple of time series dates.

property iso_dates

Return tuple of time series dates in ISO format.

property values

Return tuple of time series values.

static _load_data(dates, values)

Validate inputs and return sorted date-value pairs as dict.

Parameters

• dates – finite-length iterable of datetime objects

• values – finite-length iterable of float-convertable numbers

static _infer_date(date)

Return inferred datetime object.

Parameters

date – datetime object or string in ISO format

get_value(date)

Return value of time series at specified date.

Parameters

date – datetime object or string in ISO format

to_csv(filepath, **kwargs)

Write time series to CSV file.

Parameters

• filepath – path of output file

• date_column – date column string, defaults to ‘times’

• value_column – value column string, defaults to ‘values’

• to_string – date format string or explicit function for string conversion, defaults to days since UNIX epoch

• **kwargs – optional keyword arguments passed to DictWriter

mean()

Return sample mean of time series.

variance()

Return sample variance of time series.

crosscovariance(other)

Return cross-covariance with time series on intersecting dates.

Parameters

other – time series or broadcastable argument to subtract

crosscorrelation(other)

Return cross-correlation with time series on intersecting dates.

Parameters

other – time series or broadcastable argument to subtract

rolling(window_size=1, weights='even', **kwargs)

Return rolling window object for customizable filtering.

Parameters

• window_size – integer size of rolling window, defaults to 1

• weights – type of weights, defaults to ‘even’. Current options: ‘even’ - all points weighted evenly ‘linear’ - weights increasing linearly from ‘min_weight’ parameter ‘none’ - no weighting

• **kwargs – keyword arguments passed to weights as parameters

moving_average(window_size)

Return moving average.

Parameters

window_size – integer size of rolling window

rolling_variance(window_size)

Return rolling sample variance.

Parameters

window_size – integer size of rolling window

exponential_moving_average(alpha)

Return exponential moving average.

Parameters

alpha – smoothing factor, must be between 0 and 1

property operator

Return operator object for customizable function calls.

add(other, operation='union', fill=0)

Return element-wise summed time series after set operation.

Parameters

• other – time series or broadcastable argument

• operation – set operation to apply to time series dates, defaults to ‘union’

• fill – value to fill in missing dates, defaults to 0

subtract(other, operation='union', fill=0)

Return element-wise subtracted time series after set operation.

Parameters

• other – time series or broadcastable argument to subtract

• operation – set operation to apply to time series dates, defaults to ‘union’

• fill – value to fill in missing dates, defaults to 0

multiply(other, operation='intersection', fill=1)

Return element-wise multiplied time series after set operation.

Parameters

• other – time series or broadcastable argument to subtract

• operation – set operation to apply to time series dates, defaults to ‘intersection’

• fill – value to fill in missing dates, defaults to 1

divide(other, operation='intersection', fill=1)

Return element-wise divided time series after set operation.

Parameters

• other – time series or broadcastable argument to subtract

• operation – set operation to apply to time series dates, defaults to ‘intersection’

• fill – value to fill in missing dates, defaults to 1

power(other, operation='intersection', fill=1)

Return element-wise exponentiation of time series after set operation.

Parameters

• other – time series or broadcastable argument for exponent

• operation – set operation to apply to time series dates, defaults to ‘intersection’

• fill – value to fill in missing dates, defaults to 1