timekeep

A python package for defensive timeseries analytics.

What is timekeep

All code needs to make assumptions about the data it uses: its shape, content, or format. But constantly checking and re-checking the assumptions can make the code unwieldy. Timeseries data presents additional complications in that many common python packages, such as pandas and scikitlearn, expect 2-dimensional, static data.

timekeep protects your timeseries data by providing simple decorators to check those assumptions. timekeep is heavily inspired by engarde, but does not share its assumption about data being a pandas dataframe.

Quickstart

How to install

timekeep is available from PyPi. Run

pip install timekeep

to install.

Important: timekeep is currently on version 0.1.0 and is in active development. As the version reflects, the codebase is liable to change. Once main functionality has been applied, a stable version 1.0.0 will be released.

How to use

timekeep provides decorators to be used on functions which return a timeseries dataset. Each decorator checks an assumption about the data and raises an error if this assumption is not met.

import numpy as np
import timekeep.decorators as tkd

# Check that data returned from wont_raise
# has shape (-1, 10, 2)
@tkd.is_shape((-1, 10, 2))
def wont_raise():
  return np.random.random((10, 10, 2))

# Check that data returned from will_raise is a
# timeseries dataset (has three dimensions)
@tkd.is_timeseries
def will_raise():
  return np.random.random((10, 2))

Another key feature of timekeep is conversion between timeseries data formats; timekeep can convert between tslearn style timeseries dataset and sklearn datasets, with support for tsfresh datasets in progress. The conversion functions can be applied as decorators to methods and functions to automatically convert your data as you supply it. For example:

import numpy as np
import timekeep.conversion as tkc
from sklearn.preprocessing import PCA

# Convert timeseries dataset to sklearn for input into sklearn.preprocessing.PCA
@tkc.convert_timeseries_input
def run_pca_on_timeseries(data):
  return PCA().fit(data)

timeseries_data = np.random.random((10, 100, 2))
run_pca_on_timeseries(timeseries_data)

See the examples folder for more. You can launch this repo on binder and run the examples without any installation.

Contributing

Any and all help welcome. Please see the contributing guide.