{"id":6464,"library":"stumpy","title":"stumpy: Time Series Matrix Profile Library","description":"STUMPY is a powerful and scalable Python library that efficiently computes the matrix profile, a novel data structure for time series analysis. This allows for a variety of time series data mining tasks such as pattern/motif discovery, anomaly detection, semantic segmentation, and more. It is currently at version 1.14.1 and maintains an active development cycle with regular releases.","status":"active","version":"1.14.1","language":"en","source_language":"en","source_url":"https://github.com/stumpy-dev/stumpy","tags":["time-series","matrix-profile","data-mining","anomaly-detection","motif-discovery","python","scientific-computing"],"install":[{"cmd":"pip install stumpy","lang":"bash","label":"Pip"},{"cmd":"conda install -c conda-forge stumpy","lang":"bash","label":"Conda"}],"dependencies":[{"reason":"Core numerical operations.","package":"numpy","optional":false},{"reason":"Just-in-Time (JIT) compilation for performance optimization, including parallel and GPU computations.","package":"numba","optional":false},{"reason":"Scientific computing utilities.","package":"scipy","optional":false},{"reason":"For distributed computing with `stumpy.stumped`.","package":"dask","optional":true},{"reason":"Commonly used for plotting results in examples and tutorials.","package":"matplotlib","optional":true}],"imports":[{"note":"Standard import for the library.","symbol":"stumpy","correct":"import stumpy"},{"note":"Often used in conjunction with stumpy for array manipulation and data generation.","symbol":"numpy","correct":"import numpy as np"}],"quickstart":{"code":"import stumpy\nimport numpy as np\n\n# Generate a random time series\nyour_time_series = np.random.rand(1000)\n\n# Define a window size (m) for subsequences\nwindow_size = 50\n\n# Compute the matrix profile\nmatrix_profile = stumpy.stump(your_time_series, m=window_size)\n\nprint(f\"Matrix Profile shape: {matrix_profile.shape}\")\n# The matrix_profile array contains 4 columns:\n# 0: Nearest neighbor distance (matrix profile value)\n# 1: Nearest neighbor index\n# 2: Left nearest neighbor index\n# 3: Right nearest neighbor index","lang":"python","description":"This quickstart demonstrates how to compute the matrix profile for a 1-dimensional time series using the `stumpy.stump` function. The `m` parameter specifies the window size for subsequences. The output `matrix_profile` array contains crucial information about each subsequence's nearest neighbor."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or later.","message":"Python Version Requirement: STUMPY requires Python 3.10 or newer. Users on older Python versions (e.g., 3.9 or earlier) will encounter installation or runtime errors.","severity":"breaking","affected_versions":"<1.14.0"},{"fix":"Experiment with different `m` values, leverage domain knowledge, or consider using tools like the Pan Matrix Profile for broader exploration.","message":"Window Size (m) Selection: Choosing an appropriate window size (`m`) for `stumpy.stump` is critical. An ill-chosen `m` can lead to uninformative or misleading matrix profiles. The optimal `m` is highly dependent on the nature of your time series and the patterns you are looking for.","severity":"gotcha","affected_versions":"All"},{"fix":"Always refer to the official documentation for the precise meaning of each column in the output array. The `index` column gives the location of the nearest neighbor, while `left_index` and `right_index` provide indices for neighbors only to the left or right, respectively (with `-1` indicating no such neighbor exists).","message":"Understanding Matrix Profile Output: The `stumpy.stump` function returns a NumPy array with four specific columns: `[distance, index, left_index, right_index]`. Misinterpreting these columns, especially the 'index' (nearest neighbor) versus 'left_index'/'right_index' (directional nearest neighbors), is a common footgun.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure you have an NVIDIA GPU and the CUDA Toolkit properly installed and configured if you intend to use GPU-accelerated functions. Otherwise, STUMPY will default to CPU computations.","message":"GPU Acceleration Requires NVIDIA and CUDA: While STUMPY supports GPU acceleration (e.g., with `stumpy.gpu_stump`), this functionality relies on Numba's CUDA JIT compiler. This means you need an NVIDIA GPU and the appropriate CUDA Toolkit installed on your system; simply installing STUMPY will not automatically provide GPU capabilities.","severity":"gotcha","affected_versions":"All"},{"fix":"Regularly update NumPy to a recent, supported version to ensure compatibility and access to the latest features and bug fixes.","message":"NumPy Version Adherence to NEP 29: STUMPY follows NEP 29 (NumPy Enhancement Proposal 29) for its supported Python and NumPy versions. This means that older NumPy versions will eventually be dropped from support without specific breaking changes from STUMPY itself, but due to upstream dependency policy.","severity":"deprecated","affected_versions":"Future versions (as per NEP 29 rolling policy)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}