{"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":"en","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,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","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')"}]}