tslearn Library

Machine learning toolkit for time series data. Use Dynamic Time Warping (DTW) to find similar price patterns, cluster market behaviors, and classify chart formations.

Difficulty: Advanced

Category: Pattern Recognition

Installation

$ pip install tslearn

Key Features

Dynamic Time Warping (DTW)

Match patterns that are similar but stretched or compressed in time

Time Series Clustering

Group similar price patterns using k-means and k-shape algorithms

Time Series Classification

Train classifiers to recognize bullish/bearish patterns

Shapelet Learning

Discover discriminative sub-patterns that define chart formations

Barycenter Averaging

Compute average shapes of pattern groups

scikit-learn Compatible

Follows the same fit/predict/transform API as scikit-learn

Code Examples

Installation

Install tslearn

Python

pip install tslearn

# Verify

python -c "import tslearn; print(tslearn.__version__)"

Dynamic Time Warping (DTW)

Find similar price patterns even if they occur at different speeds

Python

from tslearn.metrics import dtw

import numpy as np

import yfinance as yf

df = yf.download("EURUSD=X", period="1y")

close = df['Close'].values.flatten()

# Define two price segments to compare

pattern_a = close[0:50] # First 50 candles

pattern_b = close[100:150] # Candles 100-150

# Normalize patterns (z-score)

pattern_a = (pattern_a - pattern_a.mean()) / pattern_a.std()

pattern_b = (pattern_b - pattern_b.mean()) / pattern_b.std()

# Calculate DTW distance

distance = dtw(pattern_a, pattern_b)

print(f"DTW distance: {distance:.4f}")

print("Lower distance = more similar patterns")

Pattern Clustering

Group similar chart patterns together

Python

from tslearn.clustering import TimeSeriesKMeans

from tslearn.preprocessing import TimeSeriesScalerMeanVariance

import numpy as np

import yfinance as yf

df = yf.download("EURUSD=X", period="2y")

close = df['Close'].values.flatten()

# Create sliding window patterns

window_size = 20

patterns = []

for i in range(0, len(close) - window_size, 5):

patterns.append(close[i:i+window_size])

patterns = np.array(patterns).reshape(len(patterns), window_size, 1)

# Normalize

scaler = TimeSeriesScalerMeanVariance()

patterns_scaled = scaler.fit_transform(patterns)

# Cluster into 4 groups (e.g., uptrend, downtrend, range, volatile)

model = TimeSeriesKMeans(n_clusters=4, metric="dtw",

max_iter=10, random_state=42)

labels = model.fit_predict(patterns_scaled)

# Count patterns per cluster

for i in range(4):

count = (labels == i).sum()

print(f"Cluster {i}: {count} patterns ({count/len(labels)*100:.1f}%)")

Pattern Classification

Train a classifier to recognize bullish vs bearish patterns

Python

from tslearn.neighbors import KNeighborsTimeSeriesClassifier

from tslearn.preprocessing import TimeSeriesScalerMeanVariance

import numpy as np

import yfinance as yf

df = yf.download("EURUSD=X", period="2y")

close = df['Close'].values.flatten()

# Create labeled patterns

window = 20

X, y = [], []

for i in range(len(close) - window - 5):

pattern = close[i:i+window]

future_return = (close[i+window+5] - close[i+window]) / close[i+window]

X.append(pattern)

y.append(1 if future_return > 0 else 0) # 1=bullish, 0=bearish

X = np.array(X).reshape(len(X), window, 1)

y = np.array(y)

# Normalize

scaler = TimeSeriesScalerMeanVariance()

X = scaler.fit_transform(X)

# Train/test split

split = int(len(X) * 0.8)

X_train, X_test = X[:split], X[split:]

y_train, y_test = y[:split], y[split:]

# Train KNN with DTW

clf = KNeighborsTimeSeriesClassifier(n_neighbors=5, metric="dtw")

clf.fit(X_train, y_train)

accuracy = clf.score(X_test, y_test)

print(f"Accuracy: {accuracy:.2%}")

Best Practices

Always Normalize

Z-score normalize time series before DTW — otherwise absolute price levels dominate

scikit-learn API

Same fit/predict/transform API as sklearn — easy if you know sklearn

DTW is Slow

DTW is O(n²) per comparison — use FastDTW or limit pattern length

Overfitting Risk

Pattern matching can overfit — always validate on out-of-sample data

Resources

Next Steps

STUMPY - Matrix Profiles scikit-learn - ML Models