stumpy

What it is and what it does

STUMPY is a Python library for computing matrix profiles, a foundational data structure that identifies the nearest neighbor of every subsequence in a time series. Once computed, the matrix profile unlocks a range of time series analysis tasks: discovering repeated patterns (motifs), finding anomalies (discords), performing semantic segmentation, and extracting time series chains. The library is built on numpy, scipy, and numba; numba's JIT compilation provides the speed needed to handle large datasets efficiently. STUMPY offers multiple entry points: stump for single-dimensional data, mstump for multi-dimensional data, gpu_stump for GPU acceleration, and stumped/mstumped for distributed computation via Dask.

The package is designed for researchers, data scientists, and developers working with time series. It supports modern Python versions (3.10+) and runs on Linux, macOS, and Windows. The API is straightforward—typically a single function call with a time series and a window size parameter—and the library is actively maintained with comprehensive documentation and tutorials.

Use it for:

• Discover repeated patterns (motifs) in long time series to identify recurring behaviors or cycles.
• Detect anomalies and outliers by finding subsequences with no close neighbors in the time series.
• Segment time series into distinct regimes or states using semantic segmentation (FLUSS).
• Analyze multi-dimensional time series (e.g., sensor arrays) to find correlated patterns across dimensions.
• Accelerate matrix profile computation on large datasets using GPU or distributed Dask clusters.
• Extract time series chains to understand temporally ordered sequences of repeating patterns.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

STUMPY computes the matrix profile for time series data, enabling pattern discovery, anomaly detection, and other time series mining tasks through efficient algorithms optimized with Numba.

Yes. STUMPY is actively maintained, has no known vulnerabilities, installs with low friction, and is licensed permissively. It fills a specific and well-defined niche in time series analysis. Install it if you need matrix profile computation or the downstream mining tasks it enables; skip it if your time series work is limited to forecasting or simple statistics.

Install

stumpy on PyPI

pip install stumpy

uv add stumpy

poetry add stumpy

Installing stumpy

Before you install

Low friction install with pure Python wheels. Active maintenance with recent commits and a solid user base (4143 stars). Requires numpy, scipy, and numba; numba's JIT compilation adds a small first-run overhead but enables the performance gains STUMPY is designed for.

License in practice

BSD-3-Clause is permissive; you can use STUMPY in commercial and proprietary projects with minimal restrictions, provided you include the license text.

Quickstart

import stumpy
import numpy as np

your_time_series = np.random.rand(10000)
window_size = 50
matrix_profile = stumpy.stump(your_time_series, m=window_size)

Numba JIT compilation on first call may take several seconds; ensure numpy and scipy are installed alongside stumpy.

Verify before relying

• Whether GPU support (gpu_stump) requires CUDA toolkit installation or if Numba's CUDA dependencies are automatically resolved.
• Performance characteristics on very long time series (millions of points) compared to approximate methods.
• Whether distributed (stumped, mstumped) functions require Dask to be pre-installed or if they are optional.

Package facts

Evidence: stumpy-1.14.1-py3-none-any.whl

Keywords: time series, matrix profile, motif, discord

Tags

More Software Development packages