STUMPY Library

Modern time series analysis using Matrix Profiles. Automatically discover recurring patterns, detect anomalies, and identify market regime changes in price data. Created by TD Ameritrade.

Difficulty: Advanced

Category: Pattern Recognition

Installation

# Standard install

$ pip install stumpy

# With GPU acceleration

$ pip install stumpy[gpu]

Key Features

Matrix Profile

Find all recurring patterns in time series data

Motif Discovery

Automatically detect repeated patterns (motifs)

Discord Detection

Find anomalies and unusual price movements

Pan Matrix Profile

Multi-resolution analysis across different subsequence lengths

Semantic Segmentation

Split time series into meaningful regimes

GPU Acceleration

CUDA support for massive datasets

Code Examples

Installation

Install stumpy

Python

pip install stumpy

# Optional: GPU acceleration

pip install stumpy[gpu]

# Verify

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

Basic Matrix Profile

Compute matrix profile to find recurring price patterns

Python

import stumpy

import numpy as np

import yfinance as yf

# Get price data

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

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

# Compute Matrix Profile (window size = 20 candles)

mp = stumpy.stump(close, m=20)

# mp[:, 0] = matrix profile (distance to nearest neighbor)

# mp[:, 1] = index of nearest neighbor

# mp[:, 2] = left matrix profile index

# mp[:, 3] = right matrix profile index

print(f"Matrix Profile shape: {mp.shape}")

print(f"Min distance: {mp[:, 0].min():.4f}")

print(f"Max distance: {mp[:, 0].max():.4f}")

Find Recurring Patterns (Motifs)

Discover the most frequently occurring patterns

Python

import stumpy

import numpy as np

import yfinance as yf

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

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

# Compute matrix profile

m = 20 # Pattern length (20 candles)

mp = stumpy.stump(close, m=m)

# Find top motifs (most similar pattern pairs)

motif_idx = np.argsort(mp[:, 0])[:5] # Top 5 motifs

for i, idx in enumerate(motif_idx):

neighbor_idx = int(mp[idx, 1])

distance = mp[idx, 0]

print(f"Motif {i+1}: Pattern at index {idx}, "

f"matches index {neighbor_idx}, "

f"distance: {distance:.4f}")

print(f" Dates: {df.index[idx].date()} ~ "

f"{df.index[neighbor_idx].date()}")

Detect Price Anomalies (Discords)

Find unusual price movements that differ from normal patterns

Python

import stumpy

import numpy as np

import yfinance as yf

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

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

# Compute matrix profile

mp = stumpy.stump(close, m=20)

# Discords = highest matrix profile values (most unusual)

discord_idx = np.argsort(mp[:, 0])[-5:][::-1] # Top 5 anomalies

print("Top 5 Price Anomalies:")

for i, idx in enumerate(discord_idx):

print(f" {i+1}. Index {idx} ({df.index[idx].date()}) - "

f"Anomaly score: {mp[idx, 0]:.4f}")

Market Regime Detection

Segment the market into different regimes

Python

import stumpy

import numpy as np

import yfinance as yf

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

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

# Use semantic segmentation to find regime changes

# L = subsequence length, should be meaningful (e.g., 1 month ~ 22 trading days)

L = 22

# Compute the matrix profile

mp = stumpy.stump(close, m=L)

# Regime changes occur where the matrix profile is high

# (indicating the current pattern is unlike its neighbors)

threshold = np.percentile(mp[:, 0], 90)

regime_changes = np.where(mp[:, 0] > threshold)[0]

print(f"Detected {len(regime_changes)} potential regime changes")

for idx in regime_changes[:10]: # Show first 10

print(f" {df.index[idx].date()} - Score: {mp[idx, 0]:.4f}")

Best Practices

Choose Window Size Wisely

The subsequence length (m) determines what patterns you find — try multiple sizes

Normalize First

Z-normalize your data for better pattern matching across different price levels

Computational Cost

Matrix profiles are O(n²) — use GPU acceleration for large datasets

Interpretation Required

Raw matrix profiles need domain knowledge to interpret — combine with other analysis

Resources

Next Steps

tslearn - Time Series ML SciPy - Signal Processing