---
title: "Tslearn"
description: "Learn how to create, train, and evaluate machine learning models in the research environment in QuantConnect with Tslearn library."
canonical: https://www.quantconnect.com/docs/v2/research-environment/machine-learning/popular-libraries/tslearn
markdown: https://www.quantconnect.com/docs/v2/research-environment/machine-learning/popular-libraries/tslearn.md
language: python
source: https://github.com/QuantConnect/Documentation/tree/master/04%20Research%20Environment/08%20Machine%20Learning/03%20Popular%20Libraries/09%20Tslearn
modified: 2026-10-31
index: https://www.quantconnect.com/llms.txt
---

# Tslearn

[Documentation](https://www.quantconnect.com/docs/v2.md) > [Research Environment](https://www.quantconnect.com/docs/v2/research-environment.md) > Machine Learning > [Popular Libraries](https://www.quantconnect.com/docs/v2/research-environment/machine-learning/popular-libraries.md) > Tslearn

> Code examples are shown in Python. Append `?lang=csharp` to this URL for the C# version of this page.

## Introduction

This page explains how to build, train, test, and store `tslearn` models.

## Import Libraries

Import the `tslearn` libraries.

```python
from tslearn.barycenters import softdtw_barycenter
from tslearn.clustering import TimeSeriesKMeans
```

## Get Historical Data

[Get some historical market data](https://www.quantconnect.com/docs/v2/research-environment/datasets/us-equity.md#04-Get-Historical-Data) to train and test the model. For example, get data for the securities shown in the following table:

| Group Name | Tickers |
| --- | --- |
| Overall US market | SPY, QQQ, DIA |
| Tech companies | AAPL, MSFT, TSLA |
| Long-term US Treasury ETFs | IEF, TLT |
| Short-term US Treasury ETFs | SHV, SHY |
| Heavy metal ETFs | GLD, IAU, SLV |
| Energy sector | USO, XLE, XOM |

```python
qb = QuantBook()
tickers = ["SPY", "QQQ", "DIA",
           "AAPL", "MSFT", "TSLA",
           "IEF", "TLT", "SHV", "SHY",
           "GLD", "IAU", "SLV",
           "USO", "XLE", "XOM"]
symbols = [qb.add_equity(ticker, Resolution.DAILY).symbol for ticker in tickers]
history = qb.history(symbols, datetime(2020, 1, 1), datetime(2022, 2, 20))
```

## Prepare Data

You need some [historical data](https://www.quantconnect.com/docs/v2/research-environment/machine-learning/popular-libraries/tslearn.md#03-Get-Historical-Data) to prepare the data for the model. If you have historical data, manipulate it to train and test the model. In this example, standardize the log close price time-series of the securities. Follow these steps to prepare the data:

1. Unstack the historical DataFrame and select the close column.
   ```python
   close = history.unstack(0).close
   ```
2. Take the logarithm of the historical time series.
   ```python
   log_close = np.log(close)
   ```
   Taking the logarithm eases the compounding effect.
3. Standardize the data.
   ```python
   standard_close = (log_close - log_close.mean()) / log_close.std()
   ```

## Train Models

Instead of using real-time comparison, apply Dynamic Time Warping (DTW) with Barycenter Averaging (DBA). This technique averages multiple time-series into a single one without losing much of their information. Since not all time-series move efficiently as in ideal EMH assumptions, this approach enables similarity analysis of different time-series with sticky lags. Check the technical details from the [tslearn documentation page](https://tslearn.readthedocs.io/en/stable/user_guide/dtw.html).

![Dynamic time warping barycenter averaging visualization](https://cdn.quantconnect.com/i/tu/dba.png)

Follow these steps to train the model:

1. Set up the Time Series KMeans model with soft DBA.
   ```python
   km = TimeSeriesKMeans(n_clusters=6,   # 6 main groups
                         metric="softdtw",  # soft for differentiable
                         random_state=0)
   ```
2. Call the `fit` method with the prepared data.
   ```python
   km.fit(standard_close.T)
   ```

## Test Models

You need to [build and train the model](https://www.quantconnect.com/docs/v2/research-environment/machine-learning/popular-libraries/tslearn.md#05-Train-Models) before you test its performance. If you have trained the model, visualize the clusters and their corresponding underlying series. Follow these steps to test the model:

1. Call the `predict` method with the data to get the cluster labels.
   ```python
   labels = km.predict(standard_close.T)
   ```
2. Create a helper function to plot the clusters.
   ```python
   def plot_helper(ts):
       # Plot all points of the data set
       for i in range(ts.shape[0]):
           plt.plot(ts[i, :], "k-", alpha=.2)

       # Plot the given barycenter of them
       barycenter = softdtw_barycenter(ts, gamma=1.)
       plt.plot(barycenter, "r-", linewidth=2)
   ```
3. Plot the results.
   ```python
   j = 1
   plt.figure(figsize=(15, 10))
   for i in set(labels):
       # Select the series in the i-th cluster.
       X = standard_close.iloc[:, [n for n, k in enumerate(labels) if k == i]].values

       # Plot the series and barycenter-averaged series.
       plt.subplot(len(set(labels)) // 3 + (1 if len(set(labels))%3 != 0 else 0), 3, j)
       plt.title(f"Cluster {i+1}")
       plot_helper(X.T)

       j += 1

   plt.show()
   ```
   ![Tslearn model equity curves of each cluster](https://cdn.quantconnect.com/i/tu/tslearn-plot.png)
4. Display the groupings.
   ```python
   for i in set(labels):
       print(f"Cluster {i+1}: {standard_close.columns[[n for n, k in enumerate(labels) if k == i]]}")
   ```
   ![Tslearn model clustering result](https://cdn.quantconnect.com/i/tu/tslearn-clustering.png)

## Store Models

You can save and load `tslearn` models using the Object Store.

### Save Models

Follow these steps to save models in the Object Store:

1. Set the key name of the model to be stored in the Object Store.
   ```python
   model_key = "model"
   ```
2. Call the `get_file_path` method with the key.
   ```python
   file_name = qb.object_store.get_file_path(model_key)
   ```
   This method returns the file path where the model will be stored.
3. Delete the current file to avoid a `FileExistsError` error when you save the model.
   ```python
   import os
   os.remove(file_name)
   ```
4. Call the `to_hdf5` method with the file path.
   ```python
   km.to_hdf5(file_name + ".hdf5")
   ```

### Load Models

You must save a model into the Object Store before you can load it from the Object Store. If you saved a model, follow these steps to load it:

1. Call the `contains_key` method.
   ```python
   qb.object_store.contains_key(model_key)
   ```
   This method returns a boolean that represents if the `model_key` is in the Object Store. If the Object Store does not contain the `model_key`, save the model using the `model_key` before you proceed.
2. Call the `get_file_path` method with the key.
   ```python
   file_name = qb.object_store.get_file_path(model_key)
   ```
   This method returns the path where the model is stored.
3. Call the `from_hdf5` method with the file path.
   ```python
   loaded_model = TimeSeriesKMeans.from_hdf5(file_name + ".hdf5")
   ```
   This method returns the saved model.

## Reference

- F. Petitjean, A. Ketterlin, P. Gancarski. (2010). A global averaging method for dynamic time warping, with applications to clustering. *Pattern Recognition. 44(2011). 678-693. Retrieved from https://lig-membres.imag.fr/bisson/cours/M2INFO-AIW-ML/papers/PetitJean11.pdf*

## Examples

The following examples demonstrate some common practices for using the `tslearn` library.

### Example 1: DBA Clustering

The following research notebook uses a `tslearn` machine learning model to cluster a collection of stocks applying Dynamic Time Warping (DTW) with Barycenter Averaging (DBA).

```python
# Import the tslearn library.
from tslearn.barycenters import softdtw_barycenter
from tslearn.clustering import TimeSeriesKMeans

# Instantiate the QuantBook for researching.
qb = QuantBook()
# Request the daily history of the collection of stocks in the date range to be studied.
tickers = ["SPY", "QQQ", "DIA",
           "AAPL", "MSFT", "TSLA",
           "IEF", "TLT", "SHV", "SHY",
           "GLD", "IAU", "SLV",
           "USO", "XLE", "XOM"]
symbols = [qb.add_equity(ticker, Resolution.DAILY).symbol for ticker in tickers]
history = qb.history(symbols, datetime(2020, 1, 1), datetime(2022, 2, 20))

# Obtain the daily log close price to be analyzed.
close = history.unstack(0).close
log_close = np.log(close)       # Taking the logarithm eases the compounding effect.
# Standardize the data for faster convergence.
standard_close = (log_close - log_close.mean()) / log_close.std()

# Set up the Time Series KMeans model with soft DBA.
km = TimeSeriesKMeans(n_clusters=6,   # 6 main groups
                      metric="softdtw",  # soft for differentiable
                      random_state=0)
# Fit the model.
km.fit(standard_close.T)

# Call the predict method with the data to get the cluster labels.
labels = km.predict(standard_close.T)

# Create a helper function to plot the clusters.
def plot_helper(ts):
    # Plot all points of the data set
    for i in range(ts.shape[0]):
        plt.plot(ts[i, :], "k-", alpha=.2)

    # Plot the given barycenter of them
    barycenter = softdtw_barycenter(ts, gamma=1.)
    plt.plot(barycenter, "r-", linewidth=2)
# Plot the results.
j = 1
plt.figure(figsize=(15, 10))
for i in set(labels):
    # Select the series in the i-th cluster.
    X = standard_close.iloc[:, [n for n, k in enumerate(labels) if k == i]].values

    # Plot the series and barycenter-averaged series.
    plt.subplot(len(set(labels)) // 3 + (1 if len(set(labels))%3 != 0 else 0), 3, j)
    plt.title(f"Cluster {i+1}")
    plot_helper(X.T)

    j += 1

plt.show()
# Display the groupings.
for i in set(labels):
    print(f"Cluster {i+1}: {standard_close.columns[[n for n, k in enumerate(labels) if k == i]]}")

# Store the model in the object store to allow accessing the model in the next research session or in the algorithm for trading.
model_key = "model"
file_name = qb.object_store.get_file_path(model_key)
import os
os.remove(file_name)
km.to_hdf5(file_name + ".hdf5")
```