Function motifs

stumpy/motifs.py:166–388

Discover the top motifs for time series ``T`` A subsequence, ``Q``, becomes a candidate motif if there are at least ``min_neighbor`` number of other subsequence matches in ``T`` (outside the exclusion zone) with a distance less or equal to ``max_distance``. Note that, in the b

(
    T,
    P,
    min_neighbors=1,
    max_distance=None,
    cutoff=None,
    max_matches=10,
    max_motifs=1,
    atol=1e-8,
    normalize=True,
    p=2.0,
    T_subseq_isconstant=None,
)

    ],
)
def motifs(
    T,
    P,
    min_neighbors=1,
    max_distance=None,
    cutoff=None,
    max_matches=10,
    max_motifs=1,
    atol=1e-8,
    normalize=True,
    p=2.0,
    T_subseq_isconstant=None,
):
    """
    Discover the top motifs for time series ``T``

    A subsequence, ``Q``, becomes a candidate motif if there are at least
    ``min_neighbor`` number of other subsequence matches in ``T`` (outside the
    exclusion zone) with a distance less or equal to ``max_distance``.

    Note that, in the best case scenario, the returned arrays would have shape
    ``(max_motifs, max_matches)`` and contain all finite values. However, in reality,
    many conditions (see below) need to be satisfied in order for this to be true. Any
    truncation in the number of rows (i.e., motifs)  may be the result of insufficient
    candidate motifs with matches greater than or equal to ``min_neighbors`` or that
    the matrix profile value for the candidate motif was larger than ``cutoff``.
    Similarly, any truncation in the number of columns (i.e., matches) may be the result
    of insufficient matches being found with distances (to their corresponding candidate
    motif) that are equal to or less than ``max_distance``. Only motifs and matches that
    satisfy all of these constraints will be returned.

    If you must return a shape of ``(max_motifs, max_matches)``, then you may consider
    specifying a smaller ``min_neighbors``, a larger ``max_distance``, and/or a larger
    ``cutoff``. For example, while it is ill advised, setting ``min_neighbors=1``,
    ``max_distance = np.inf``, and ``cutoff = np.inf`` will ensure that the shape of the
    output arrays will be ``(max_motifs, max_matches)``. However, given the lack of
    constraints, the quality of each motif and the quality of each match may be
    drastically different. Setting appropriate conditions will help ensure appropriately
    constrained results that may be easier to interpret.

    Parameters
    ----------
    T : numpy.ndarray
        The time series or sequence.

    P : numpy.ndarray
        The (1-dimensional) matrix profile of ``T``. In the case where the matrix
        profile was computed with ``k > 1`` (i.e., top-k nearest neighbors), you
        must summarize the top-k nearest-neighbor distances for each subsequence
        into a single value (e.g., ``np.mean``, ``np.min``, etc) and then use that
        derived value as your ``P``.

    min_neighbors : int, default 1
        The minimum number of similar matches a subsequence needs to have in order
        to be considered a motif. This defaults to ``1``, which means that a subsequence
        must have at least one similar match in order to be considered a motif.

    max_distance : float or function, default None