DOCSEARCHbyAlgolia
Submit Docs

STUMPY

repository·main·Indexed 24 days ago

https://github.com/stumpy-dev/stumpy

A scalable Python library for computing the matrix profile to identify patterns, anomalies, and semantic segments in time series data. Version 1.14.1 supports tasks such as motif and discord discovery, shapelet discovery, and time series chains. It includes GPU-accelerated functions like gpu_stump, gpu_ostinato, gpu_mpdist, and gpu_stimp, as well as tools for similarity search (stumpy.mass) and pattern matching (stumpy.match).

Tokens
26.1K
Snippets
30
Records
133
Agent score
87%

What's inside stumpy

  1. Overview of STUMPY

    main

    STUMPY is a scalable Python library designed to compute the matrix profile. The matrix profile identifies the nearest-neighbor subsequence for every subsequence within a time series. This capability enables various time series data mining tasks, including:

    • Pattern/Motif discovery: Finding approximately repeated subsequences.
    • Anomaly/Novelty (discord) discovery: Identifying unusual patterns.
    • Shapelet discovery
    • Semantic segmentation
    • Streaming (on-line) data analysis
    • Time series chains: Finding temporally ordered sets of patterns.
    • Pan matrix profiles: Selecting optimal subsequence window sizes.

  2. Overview of STUMPY for Time Series Data Mining

    main

    STUMPY is a scalable Python library designed for efficient time series data mining. Its core capability is computing the matrix profile, which is a vector representing the distances between all subsequences within a time series and their nearest neighbors. This allows for exact similarity joins without the computational complexity of brute-force methods.

    Key use cases for STUMPY include:

    • Pattern/Motif discovery: Finding approximately repeated subsequences.
    • Anomaly/Discord discovery: Identifying novel or unusual subsequences.
    • Shapelet discovery: Finding characteristic patterns.
    • Semantic segmentation: Dividing time series into meaningful segments.
    • Density estimation.
    • Time series chains: Finding temporally ordered sets of subsequence patterns.

    The library supports parallel and distributed computation, as well as multi-dimensional motif discovery and time series chains.

  5. Get help with STUMPY

    main

    If you encounter issues or have questions, check the following resources before opening a new request:

    1. GitHub Discussions: For general questions and community knowledge.
    2. GitHub Issues: To search for existing bug reports or technical problems.

    If no solution is found, you can open a new discussion or issue on GitHub.

  7. Python version requirements for STUMPY

    main
    STUMPY requires Python 3.10+. It is not compatible with Python 2.x due to the use of unicode variable names/identifiers. While it may work on older versions of Python 3 due to small dependencies, this is not officially supported.

  9. Handle Self-Join vs AB-Join warnings

    main

    When performing matrix profile computations, STUMPY distinguishes between self-joins (where T_A and T_B are the same array) and AB-joins (where they are different).

    • If ignore_trivial=False during a self-join, STUMPY will issue a warning suggesting you set ignore_trivial=True.
    • If ignore_trivial=True during an AB-join, STUMPY will automatically set it to False and issue a warning.

    You can suppress these warnings using Python's warnings context manager.

    import stumpy
import numpy as np
import warnings

T = np.random.rand(10_000)
m = 50
with warnings.catch_warnings():
    warnings.filterwarnings("ignore", message="Arrays T_A, T_B are equal")
    for _ in range(5):
        stumpy.stump(T, m, T, ignore_trivial=False)

  10. Find top-k matches by disabling the exclusion zone

    main

    By default, stumpy.match uses an exclusion zone of m / 4 (where m is the query length) to prevent returning overlapping matches. To find the absolute top-k matches regardless of overlap, you must set the exclusion zone denominator to infinity via stumpy.config.STUMPY_EXCL_ZONE_DENOM before calling the function.

    import numpy as np
import stumpy

# 1. Set exclusion zone denominator to infinity to disable exclusion zone
stumpy.config.STUMPY_EXCL_ZONE_DENOM = np.inf

# 2. Perform match with max_distance=np.inf and max_matches=k
matches_top_k = stumpy.match(
    Q_df["Acceleration"], 
    T_df["Acceleration"],
    max_distance=np.inf, 
    max_matches=16,
)

# 3. Reset to default (4) to avoid side effects in other code
stumpy.config.STUMPY_EXCL_ZONE_DENOM = 4

  11. Normalize Pan Matrix Profiles using anti-correlated distance

    main
    When normalizing Pan Matrix Profiles, STUMPY uses the anti-correlated distance ($2 * \sqrt {m}$) as the normalization factor. Although the 'uncorrelated' distance ($\sqrt {2m}$) is a theoretical upper bound for most Matrix Profile distances, the anti-correlated distance is chosen for normalization because it is more intuitive and produces nearly identical visual results to the uncorrelated distance.

  12. Parallel multi-GPU matrix profile computation

    main

    The gpu_aamp function supports parallel computation across multiple GPUs by passing a list of device IDs to the device_id parameter. This allows STUMPY to distribute the workload across available hardware.

    You can obtain a list of all valid device IDs using:

    import numba.cuda
device_ids = [device.id for device in numba.cuda.list_devices()]