Function match

stumpy/motifs.py:404–585

Find all matches of a query ``Q`` in a time series ``T`` The indices of subsequences whose distances to ``Q`` are less than or equal to ``max_distance``, sorted by distance (lowest to highest). Around each occurrence, an exclusion zone is applied before searching for the next.

(
    Q,
    T,
    M_T=None,
    Σ_T=None,
    max_distance=None,
    max_matches=None,
    atol=1e-8,
    query_idx=None,
    normalize=True,
    p=2.0,
    T_subseq_isfinite=None,
    T_subseq_isconstant=None,
    Q_subseq_isconstant=None,
)

    replace={"M_T": "T_subseq_isfinite", "Σ_T": None},
)
def match(
    Q,
    T,
    M_T=None,
    Σ_T=None,
    max_distance=None,
    max_matches=None,
    atol=1e-8,
    query_idx=None,
    normalize=True,
    p=2.0,
    T_subseq_isfinite=None,
    T_subseq_isconstant=None,
    Q_subseq_isconstant=None,
):
    """
    Find all matches of a query ``Q`` in a time series ``T``

    The indices of subsequences whose distances to ``Q`` are less than or equal to
    ``max_distance``, sorted by distance (lowest to highest). Around each occurrence, an
    exclusion zone is applied before searching for the next.

    Parameters
    ----------
    Q : numpy.ndarray
        The query sequence. ``Q`` does not have to be a subsequence of ``T``.

    T : numpy.ndarray
        The time series of interest.

    M_T : numpy.ndarray, default None
        Sliding mean of time series, ``T``.

    Σ_T : numpy.ndarray, default None
        Sliding standard deviation of time series, ``T``.

    max_distance : float or function, default None
        Maximum distance between ``Q`` and a subsequence, ``S``, for ``S`` to be
        considered a match. If ``max_distance`` is a function,
        then it must be a function that accepts a single parameter, ``D``, in its
        function signature, which is the distance profile between ``Q`` and ``T`` (a
        1D numpy array of size ``n - m + 1``). If ``None``, this defaults to
        ``np.nanmax([np.nanmean(D) - 2 * np.nanstd(D), np.nanmin(D)])`` (i.e. at
        least the closest match will be returned).

    max_matches : int, default None
        The maximum amount of similar occurrences to be returned. The resulting
        occurrences are sorted by distance, so a value of ``10`` means that the
        indices of the most similar ``10`` subsequences is returned. If ``None``, then
        all occurrences are returned.

    atol : float, default 1e-8
        The absolute tolerance parameter. This value will be added to ``max_distance``
        when comparing distances between subsequences.

    query_idx : int, default None
        This is the index position along the time series, ``T``, where the query
        subsequence, ``Q``, is located. ``query_idx`` should only be used when the