{"id":7810,"library":"tslearn","title":"tslearn: Time-Series Machine Learning Toolkit","description":"tslearn is a Python package providing a comprehensive machine learning toolkit specifically designed for the analysis of time-series data. It offers various algorithms for clustering, classification, and regression on time series, building upon the `scikit-learn`, `numpy`, and `scipy` libraries. The current version is 0.8.1, and the library is under active development and maintenance.","status":"active","version":"0.8.1","language":"python","source_language":"en","source_url":"https://github.com/tslearn-team/tslearn","tags":["time-series","machine-learning","clustering","classification","regression","dynamic-time-warping","preprocessing","python"],"install":[{"cmd":"pip install tslearn","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Core array manipulation and numerical operations.","package":"numpy","optional":false},{"reason":"Scientific computing functionalities.","package":"scipy","optional":false},{"reason":"Provides a scikit-learn compatible API for models and utilities.","package":"scikit-learn","optional":false},{"reason":"Used for just-in-time compilation for performance-critical sections.","package":"numba","optional":false},{"reason":"Used for parallel processing.","package":"joblib","optional":false},{"reason":"Required for the `tslearn.shapelets` module (Keras3+).","package":"keras","optional":true},{"reason":"Optional backend for Keras in `tslearn.shapelets` module.","package":"tensorflow","optional":true},{"reason":"Optional backend for Keras in `tslearn.shapelets` module.","package":"torch","optional":true},{"reason":"Optional backend for Keras in `tslearn.shapelets` module.","package":"jax","optional":true}],"imports":[{"symbol":"TimeSeriesKMeans","correct":"from tslearn.clustering import TimeSeriesKMeans"},{"symbol":"to_time_series_dataset","correct":"from tslearn.utils import to_time_series_dataset"},{"symbol":"SoftDTW","correct":"from tslearn.metrics import SoftDTW"},{"symbol":"TimeSeriesScalerMeanVariance","correct":"from tslearn.preprocessing import TimeSeriesScalerMeanVariance"}],"quickstart":{"code":"import numpy as np\nfrom tslearn.clustering import TimeSeriesKMeans\nfrom tslearn.utils import to_time_series_dataset\n\n# Generate some sample time series data\nnp.random.seed(0)\nn_ts = 10 # Number of time series\nmax_sz = 100 # Maximum length of time series\nd = 1 # Dimensionality of each time point (univariate)\n\n# Create a list of 2D numpy arrays for variable-length time series\nmy_time_series = []\nfor i in range(n_ts):\n    length = np.random.randint(50, max_sz + 1)\n    series = np.random.rand(length, d)\n    my_time_series.append(series)\n\n# Convert to tslearn's expected 3D dataset format\nX = to_time_series_dataset(my_time_series)\n\n# Initialize and fit a TimeSeriesKMeans model\n# Using dtw (Dynamic Time Warping) as the metric\nkm = TimeSeriesKMeans(n_clusters=2, metric=\"dtw\", max_iter=10, random_state=0)\ncluster_labels = km.fit_predict(X)\n\nprint(f\"Input shape: {X.shape}\")\nprint(f\"Cluster labels: {cluster_labels}\")","lang":"python","description":"This quickstart demonstrates how to prepare time-series data for `tslearn` using `to_time_series_dataset` and then perform clustering with `TimeSeriesKMeans`. The data is formatted into a 3D NumPy array, which is the standard input format for `tslearn` estimators."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or higher (e.g., `python -m venv .venv` followed by `source .venv/bin/activate` and `pip install tslearn`).","message":"Support for Python versions 3.8 and 3.9 was dropped starting from `tslearn` version 0.7.0. Current versions (e.g., 0.8.1) require Python 3.10 or newer.","severity":"breaking","affected_versions":">=0.7.0"},{"fix":"Always use `tslearn.utils.to_time_series_dataset` to convert your list of 1D or 2D time series into the expected 3D format. For example: `X = to_time_series_dataset([my_series_1, my_series_2])`.","message":"`tslearn` expects time series datasets to be formatted as a 3D NumPy array of shape `(n_ts, max_sz, d)`, where `n_ts` is the number of time series, `max_sz` is the maximum length of the time series in the dataset, and `d` is the dimensionality of each time point. Variable-length time series are handled by padding shorter series with `NaN` values.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If using the `shapelets` module, ensure `keras` (Keras3+) and your desired backend (`tensorflow`, `torch`, or `jax`) are installed: `pip install tslearn[shapelets] keras tensorflow` (or `torch`, `jax`). You might also need to set `os.environ['KERAS_BACKEND'] = 'tensorflow'` (or 'torch', 'jax') before importing `keras` or `tslearn.shapelets`.","message":"The `tslearn.shapelets` module has additional dependencies, specifically requiring `Keras3+`. The backend (TensorFlow, PyTorch, or JAX) used by Keras can be selected via the `KERAS_BACKEND` environment variable.","severity":"gotcha","affected_versions":">=0.7.0"}],"env_vars":null,"search_vec":"'0.8.1':55 'activ':61 'algorithm':32 'analysi':23 'build':41 'classif':35,72 'cluster':34,71 'comprehens':15 'current':52 'data':28 'design':20 'develop':62 'dynam':75 'dynamic-time-warp':74 'learn':6,17,46,70 'librari':50,58 'machin':5,16,69 'machine-learn':68 'mainten':64 'numpi':47 'offer':30 'packag':12 'preprocess':78 'provid':13 'python':11,79 'regress':37,73 'scikit':45 'scikit-learn':44 'scipi':49 'seri':4,27,40,67 'specif':19 'time':3,26,39,66,76 'time-seri':2,25,65 'toolkit':7,18 'tslearn':1,8 'upon':42 'various':31 'version':53 'warp':77","created_at":"2026-04-16T14:14:21.934448+00:00","updated_at":"2026-04-16T14:14:21.934448+00:00","problems":[{"fix":"Wrap your single 2D time series in a list (e.g., `[my_single_time_series]`) or, preferably, use `tslearn.utils.to_time_series_dataset` to ensure correct formatting for both single and multiple time series: `X_formatted = to_time_series_dataset([my_single_time_series])` or `X_formatted = to_time_series_dataset(list_of_time_series)`.","cause":"Attempting to pass a 2D NumPy array (e.g., `(length, features)`) directly to a `tslearn` estimator when a dataset of multiple time series (3D array or list of 2D arrays) is expected. This often happens when users treat a single time series as a dataset.","error":"ValueError: Expected a 3D array (n_ts, sz, d) or a list of 2D arrays (sz, d), got 2D array (sz, d)"},{"fix":"Install Keras3+: `pip install keras` (or use `pip install tslearn[shapelets]`). If you intend to use a specific backend, install it too (e.g., `pip install tensorflow`).","cause":"Trying to import or use functionalities from `tslearn.shapelets` without having `Keras` (specifically Keras3+) installed. This module has an optional dependency.","error":"ModuleNotFoundError: No module named 'keras'"},{"fix":"Refer to the `tslearn` documentation or API reference to find the correct submodule for the desired function or class. For example, `TimeSeriesKMeans` is in `tslearn.clustering`, not directly under `tslearn`. Correct: `from tslearn.clustering import TimeSeriesKMeans`.","cause":"Incorrect import path for a specific function or class. `tslearn` organizes its functionalities into submodules (e.g., `clustering`, `utils`, `metrics`).","error":"Cannot import name '...' from 'tslearn' (most likely 'tslearn.something')"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.8.1","cli_name":"","cli_version":null,"type":"library","homepage":"https://tslearn.readthedocs.io","github":"https://github.com/tslearn-team/tslearn","docs":"http://tslearn.readthedocs.io","changelog":"https://github.com/tslearn-team/tslearn/CHANGELOG.md","pypi":"https://pypi.org/project/tslearn/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}