# STUMPY
# Copyright 2019 TD Ameritrade. Released under the terms of the 3-Clause BSD license.
# STUMPY is a trademark of TD Ameritrade IP Company, Inc. All rights reserved.
import functools
import math
import numpy as np
from . import core
from .aampdist import aampdist, aampdisted
from .stump import stump
from .stumped import stumped
def _mpdist_vect(
Q,
T,
m,
μ_Q,
σ_Q,
M_T,
Σ_T,
Q_subseq_isconstant,
T_subseq_isconstant,
percentage=0.05,
k=None,
custom_func=None,
query_idx=None,
):
"""
Compute the matrix profile distance measure vector between `Q` and each subsequence,
`T[i : i + len(Q)]`, within `T`.
Parameters
----------
Q : numpy.ndarray
Query array
T : numpy.ndarray
Time series or sequence
m : int
Window size that will be used for calculating the mpdist between Q and
any subsequence in T (of size `len(Q)`)
μ_Q : numpy.ndarray
Sliding mean of `Q`
σ_Q : numpy.ndarray
Sliding standard deviation of `Q`
M_T : numpy.ndarray
Sliding mean of `T`
Σ_T : numpy.ndarray
Sliding standard deviation of `T`
Q_subseq_isconstant : numpy.ndarray
A boolean array that indicates whether the subsequence in `Q` is constant (True)
T_subseq_isconstant : numpy.ndarray
A boolean array that indicates whether a subsequence in `T` is constant (True)
percentage : float, 0.05
The percentage of distances that will be used to report `mpdist`. The value
is between 0.0 and 1.0. This parameter is ignored when `k` is not `None` or when
`custom_func` is not None.
k : int, default None
Specify the `k`th value in the concatenated matrix profiles to return. When `k`
is not `None`, then the `percentage` parameter is ignored. This parameter is
ignored when `custom_func` is not None.
custom_func : function, default None
A custom user defined function for selecting the desired value from the
unsorted `P_ABBA` array. This function may need to leverage `functools.partial`
and should take `P_ABBA` as its only input parameter and return a single
`MPdist` value. The `percentage` and `k` parameters are ignored when
`custom_func` is not None.
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 be set to None if `Q`
is not a subsequence of `T`. If `Q` is a subsequence of `T`, provding
this argument is optional. If provided, the precision of computation
can be slightly improved.
Returns
-------
MPdist_vect : numpy.ndarray
The mpdist-based distance profile of `Q` with `T`. It is a 1D array of
size `len(T) - len(Q) + 1`. MPdist_vect[i] is the mpdist distance between
`Q` and subsequence `T[i : i + len(Q)]`.
"""
j = Q.shape[0] - m + 1 # `k` is reserved for `P_ABBA` selection
l = T.shape[0] - m + 1
MPdist_vect = np.empty(T.shape[0] - Q.shape[0] + 1, dtype=np.float64)
distance_matrix = np.full((j, l), np.inf, dtype=np.float64)
P_ABBA = np.empty(2 * j, dtype=np.float64)
if k is None:
percentage = np.clip(percentage, 0.0, 1.0)
k = min(math.ceil(percentage * (2 * Q.shape[0])), 2 * j - 1)
k = min(int(k), P_ABBA.shape[0] - 1)
core._mass_distance_matrix(
Q,
T,
m,
distance_matrix,
μ_Q,
σ_Q,
M_T,
Σ_T,
Q_subseq_isconstant,
T_subseq_isconstant,
query_idx=query_idx,
)
rolling_row_min = core.rolling_nanmin(distance_matrix, j)
col_min = np.nanmin(distance_matrix, axis=0)
for i in range(MPdist_vect.shape[0]):
P_ABBA[:j] = rolling_row_min[:, i]
P_ABBA[j:] = col_min[i : i + j]
MPdist_vect[i] = core._select_P_ABBA_value(P_ABBA, k, custom_func)
return MPdist_vect
[docs]
@core.non_normalized(aampdist)
def mpdist(
T_A,
T_B,
m,
percentage=0.05,
k=None,
normalize=True,
p=2.0,
T_A_subseq_isconstant=None,
T_B_subseq_isconstant=None,
):
"""
Compute the z-normalized matrix profile distance (MPdist) measure between any two
time series
The MPdist distance measure considers two time series to be similar if they share
many subsequences, regardless of the order of matching subsequences. MPdist
concatenates the output of an AB-join and a BA-join and returns the `k`th smallest
value as the reported distance. Note that MPdist is a measure and not a metric.
Therefore, it does not obey the triangular inequality but the method is highly
scalable.
Parameters
----------
T_A : numpy.ndarray
The first time series or sequence for which to compute the matrix profile
T_B : numpy.ndarray
The second time series or sequence for which to compute the matrix profile
m : int
Window size
percentage : float, default 0.05
The percentage of distances that will be used to report `mpdist`. The value
is between 0.0 and 1.0.
k : int
Specify the `k`th value in the concatenated matrix profiles to return. When `k`
is not `None`, then the `percentage` parameter is ignored.
normalize : bool, default True
When set to `True`, this z-normalizes subsequences prior to computing distances.
Otherwise, this function gets re-routed to its complementary non-normalized
equivalent set in the `@core.non_normalized` function decorator.
p : float, default 2.0
The p-norm to apply for computing the Minkowski distance. This parameter is
ignored when `normalize == True`.
T_A_subseq_isconstant : numpy.ndarray or function, default None
A boolean array that indicates whether a subsequence in `T_A` is constant
(True). Alternatively, a custom, user-defined function that returns a
boolean array that indicates whether a subsequence in `T_A` is constant
(True). The function must only take two arguments, `a`, a 1-D array,
and `w`, the window size, while additional arguments may be specified
by currying the user-defined function using `functools.partial`. Any
subsequence with at least one np.nan/np.inf will automatically have its
corresponding value set to False in this boolean array.
T_B_subseq_isconstant : numpy.ndarray or function, default None
A boolean array that indicates whether a subsequence in `T_B` is constant
(True). Alternatively, a custom, user-defined function that returns a
boolean array that indicates whether a subsequence in `T_B` is constant
(True). The function must only take two arguments, `a`, a 1-D array,
and `w`, the window size, while additional arguments may be specified
by currying the user-defined function using `functools.partial`. Any
subsequence with at least one np.nan/np.inf will automatically have its
corresponding value set to False in this boolean array.
Returns
-------
MPdist : float
The matrix profile distance
See Also
--------
mpdisted : Compute the z-normalized matrix profile distance (MPdist) measure
between any two time series with a distributed dask cluster
gpu_mpdist : Compute the z-normalized matrix profile distance (MPdist) measure
between any two time series with one or more GPU devices
Notes
-----
`DOI: 10.1109/ICDM.2018.00119 \
<https://www.cs.ucr.edu/~eamonn/MPdist_Expanded.pdf>`__
See Section III
Examples
--------
>>> import stumpy
>>> import numpy as np
>>> stumpy.mpdist(
... np.array([-11.1, 23.4, 79.5, 1001.0]),
... np.array([584., -11., 23., 79., 1001., 0., -19.]),
... m=3)
0.00019935236191097894
"""
partial_mp_func = functools.partial(
stump,
T_A_subseq_isconstant=T_A_subseq_isconstant,
T_B_subseq_isconstant=T_B_subseq_isconstant,
)
MPdist = core._mpdist(
T_A,
T_B,
m,
partial_mp_func,
percentage,
k,
)
return MPdist
[docs]
@core.non_normalized(aampdisted)
def mpdisted(
client,
T_A,
T_B,
m,
percentage=0.05,
k=None,
normalize=True,
p=2.0,
T_A_subseq_isconstant=None,
T_B_subseq_isconstant=None,
):
"""
Compute the z-normalized matrix profile distance (MPdist) measure between any two
time series with a distributed dask/ray cluster
The MPdist distance measure considers two time series to be similar if they share
many subsequences, regardless of the order of matching subsequences. MPdist
concatenates the output of an AB-join and a BA-join and returns the `k`th smallest
value as the reported distance. Note that MPdist is a measure and not a metric.
Therefore, it does not obey the triangular inequality but the method is highly
scalable.
Parameters
----------
client : client
A Dask or Ray Distributed client. Setting up a distributed cluster is beyond
the scope of this library. Please refer to the Dask or Ray Distributed
documentation.
T_A : numpy.ndarray
The first time series or sequence for which to compute the matrix profile
T_B : numpy.ndarray
The second time series or sequence for which to compute the matrix profile
m : int
Window size
percentage : float, default 0.05
The percentage of distances that will be used to report `mpdist`. The value
is between 0.0 and 1.0. This parameter is ignored when `k` is not `None`.
k : int
Specify the `k`th value in the concatenated matrix profiles to return. When `k`
is not `None`, then the `percentage` parameter is ignored.
normalize : bool, default True
When set to `True`, this z-normalizes subsequences prior to computing distances.
Otherwise, this function gets re-routed to its complementary non-normalized
equivalent set in the `@core.non_normalized` function decorator.
p : float, default 2.0
The p-norm to apply for computing the Minkowski distance. This parameter is
ignored when `normalize == True`.
T_A_subseq_isconstant : numpy.ndarray or function, default None
A boolean array that indicates whether a subsequence in `T_A` is constant
(True). Alternatively, a custom, user-defined function that returns a
boolean array that indicates whether a subsequence in `T_A` is constant
(True). The function must only take two arguments, `a`, a 1-D array,
and `w`, the window size, while additional arguments may be specified
by currying the user-defined function using `functools.partial`. Any
subsequence with at least one np.nan/np.inf will automatically have its
corresponding value set to False in this boolean array.
T_B_subseq_isconstant : numpy.ndarray or function, default None
A boolean array that indicates whether a subsequence in `T_B` is constant
(True). Alternatively, a custom, user-defined function that returns a
boolean array that indicates whether a subsequence in `T_B` is constant
(True). The function must only take two arguments, `a`, a 1-D array,
and `w`, the window size, while additional arguments may be specified
by currying the user-defined function using `functools.partial`. Any
subsequence with at least one np.nan/np.inf will automatically have its
corresponding value set to False in this boolean array.
Returns
-------
MPdist : float
The matrix profile distance
See Also
--------
mpdist : Compute the z-normalized matrix profile distance (MPdist) measure
between any two time series
gpu_mpdist : Compute the z-normalized matrix profile distance (MPdist) measure
between any two time series with one or more GPU devices
Notes
-----
`DOI: 10.1109/ICDM.2018.00119 \
<https://www.cs.ucr.edu/~eamonn/MPdist_Expanded.pdf>`__
See Section III
Examples
--------
>>> import stumpy
>>> import numpy as np
>>> from dask.distributed import Client
>>> if __name__ == "__main__":
... with Client() as dask_client:
... stumpy.mpdisted(
... dask_client,
... np.array([-11.1, 23.4, 79.5, 1001.0]),
... np.array([584., -11., 23., 79., 1001., 0., -19.]),
... m=3)
0.00019935236191097894
"""
partial_mp_func = functools.partial(
stumped,
T_A_subseq_isconstant=T_A_subseq_isconstant,
T_B_subseq_isconstant=T_B_subseq_isconstant,
)
MPdist = core._mpdist(
T_A,
T_B,
m,
partial_mp_func,
percentage,
k,
client=client,
)
return MPdist