Skip to main content

A machine learning toolkit dedicated to time-series data

Project description

tslearn

"The machine learning toolkit for time series analysis in Python"

PyPI Documentation Build Codecov Downloads


Section Description
Installation Installing the dependencies and tslearn
Getting started A quick introduction on how to use tslearn
Available features An extensive overview of tslearn's functionalities
Documentation A link to our API reference and a gallery of examples
Contributing A guide for heroes willing to contribute
Citation A citation for tslearn for scholarly articles

Installation

There are different alternatives to install tslearn:

  • PyPi: python -m pip install tslearn
  • Conda: conda install -c conda-forge tslearn
  • Git: python -m pip install https://github.com/rtavenar/tslearn/archive/master.zip

In order for the installation to be successful, the required dependencies must be installed. For a more detailed guide on how to install tslearn, please see the Documentation.

Getting started

1. Getting the data in the right format

tslearn expects a time series dataset to be formatted as a 3D numpy array. The three dimensions correspond to the number of time series, the number of measurements per time series and the number of dimensions respectively (n_ts, max_sz, d). In order to get the data in the right format, different solutions exist:

It should further be noted that tslearn supports variable-length timeseries.

>>> from tslearn.utils import to_time_series_dataset
>>> my_first_time_series = [1, 3, 4, 2]
>>> my_second_time_series = [1, 2, 4, 2]
>>> my_third_time_series = [1, 2, 4, 2, 2]
>>> X = to_time_series_dataset([my_first_time_series,
                                my_second_time_series,
                                my_third_time_series])
>>> y = [0, 1, 1]

2. Data preprocessing and transformations

Optionally, tslearn has several utilities to preprocess the data. In order to facilitate the convergence of different algorithms, you can scale time series. Alternatively, in order to speed up training times, one can resample the data or apply a piece-wise transformation.

>>> from tslearn.preprocessing import TimeSeriesScalerMinMax
>>> X_scaled = TimeSeriesScalerMinMax().fit_transform(X)
>>> print(X_scaled)
[[[0.] [0.667] [1.] [0.333] [nan]]
 [[0.] [0.333] [1.] [0.333] [nan]]
 [[0.] [0.333] [1.] [0.333] [0.333]]]

3. Training a model

After getting the data in the right format, a model can be trained. Depending on the use case, tslearn supports different tasks: classification, clustering and regression. For an extensive overview of possibilities, check out our gallery of examples.

>>> from tslearn.neighbors import KNeighborsTimeSeriesClassifier
>>> knn = KNeighborsTimeSeriesClassifier(n_neighbors=1)
>>> knn.fit(X_scaled, y)
>>> print(knn.predict(X_scaled))
[0 1 1]

As can be seen, the models in tslearn follow the same API as those of the well-known scikit-learn. Moreover, they are fully compatible with it, allowing to use different scikit-learn utilities such as hyper-parameter tuning and pipelines.

4. More analyses

tslearn further allows to perform all different types of analysis. Examples include calculating barycenters of a group of time series or calculate the distances between time series using a variety of distance metrics.

Available features

data processing clustering classification regression metrics
UCR Datasets Scaling TimeSeriesKMeans KNN Classifier KNN Regressor Dynamic Time Warping
Generators Piecewise KShape TimeSeriesSVC TimeSeriesSVR Global Alignment Kernel
Conversion(1, 2) GAKKmeans ShapeletModel Barycenters

Documentation

The documentation, including a gallery of examples, is hosted at readthedocs.

Contributing

If you would like to contribute to tslearn, please have a look at our contribution guidelines. A list of interesting TODO's can be found here. If you want other ML methods for time series to be added to this TODO list, do not hesitate to open an issue!

Referencing tslearn

If you use tslearn in a scientific publication, we would appreciate citations:

@misc{tslearn,
      title={tslearn: A machine learning toolkit dedicated to time-series
             data},
      author={Romain Tavenard and Johann Faouzi and Gilles Vandewiele and
              Felix Divo and Guillaume Androz and Chester Holtz and Marie
              Payne and Roman Yurchak and Marc Ru{\ss}wurm and Kushal
              Kolar and Eli Woods},
      year={2017},
      note={\url{https://github.com/rtavenar/tslearn}}
}

Acknowledgments

Authors would like to thank Mathieu Blondel for providing code for Kernel k-means and Soft-DTW.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for tslearn, version 0.3.1
Filename, size File type Python version Upload date Hashes
Filename, size tslearn-0.3.1.tar.gz (548.5 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page