Fixed #552 Add mmotifs and aamp_mmoitfs Unit Tests (#553)

* [ADD] Added new test files

* [ADD] Added pytests for 'mmotifs' and 'aamp_mmotifs'

* [DEL] Deleted test templates for the multidimensional case

* [ADD] Added function to find one motif in all dimensions

* [FIX] Reran black and flake8

* [ADD] Added exclusion zone to function

* [MOD] Don't use naive implementation

* [ADD] Added arrange and assert to the first test function

* [MOD] Changed assertions to 'almost_equal'

* [ADD] Added match functions from 'test_motifs.py'

* [ADD] Added dummy test

* [DEL & ADD] Deleted test_match() and added test function with default parameters

* [ADD] Added test function to find the top two motifs

* [ADD] Added function to test 2-dimensional motif discovery

* [FIX] Fixed formatting

* [ADD] Added test function to find motifs with the 'max_motifs' parameter only

* Revert "[ADD] Added test function to find motifs with the 'max_matches' parameter only"

This reverts commit d169441.

* [ADD] Added test function to find motifs with the 'max_distance' parameter

* [ADD] Make copy of the matrix profile

* [ADD] Also make copy of matrix profile in 'aamp_mmotifs.py'

* [FIX] Corrected the expected motif subspaces

* [ADD] Added function to test the two dimensional and non-normalized motif discovery

* [MOD] Changed to naive matrix profile computation

* [ADD] Added 'query_idx' parameter to ensure that the self-match is returned if the query is a part of the time series.

* [MOD] Change subsequence length m and time series T

* [MOD] Change to naive computation and change time series

* [MOD] Reformat file

* [ADD] Add docstring documentation

* [MOD] Reformat file

* [MOD] Modified docstring description for the 'query_idx' parameter

* [ADD] Added 'query_idx' to 'aamp_motifs'

* [ADD] Added 'query_idx' to function call of 'aamp_match'

* [ADD] Added 'query_idx' to '_motifs' and '_aamp_motifs'

* [ADD] Added test function for 'max_matches=None'

* [FIX] Set 'max_matches=None' instead of 'max_distance=None'

* [ADD] Add test function for cutoffs parameter

* [ADD] Add test function for setting 'max_matches=None'

* [ADD] Added comment to explain function in more detail

* [ADD] Added test function for finding multiple motifs with the cutoffs parameter

* [ADD] Added 'pragma: no cover' comment

* [DEL] Remove comment

* [MOD & DEL] Modified function ordering and removed comments

* [MOD] Changed '_expected' to '_ref'

* [MOD] Marked comparison values with '_cmp'

* [MOD] Renamed functions

* [ADD] Added function that tests when cutoffs are a list

* [ADD] Also tested cutoffs as list in 'test_aamp_mmotifs'

* [MOD] Changed function ordering

* [MOD] Declare time series array once at the beginning

* [MOD] Renamed functions

* [ADD] Added function with default parameters

* [FIX] Fixed function names

Co-authored-by: Sarah <[email protected]>

Author: SaVoAMP

stumpy/aamp_mmotifs.py

@@ -118,6 +118,7 @@ def aamp_mmotifs(
         max_motifs = 1
 
     T, T_subseq_isfinite = core.preprocess_non_normalized(T, m)
+    P = P.copy()
 
     excl_zone = int(np.ceil(m / config.STUMPY_EXCL_ZONE_DENOM))
 
@@ -159,7 +160,7 @@ def aamp_mmotifs(
             motif_value > cutoffs[k]
             or not np.isfinite(motif_value)
             or (isinstance(max_distance, float) and motif_value > max_distance)
-        ):
+        ):  # pragma: no cover
             break
 
         query_matches = aamp_match(
@@ -169,6 +170,7 @@ def aamp_mmotifs(
             max_matches=max_matches,
             max_distance=max_distance,
             atol=atol,
+            query_idx=motif_idx,
             p=p,
         )
 

stumpy/aamp_motifs.py

@@ -118,6 +118,7 @@ def _aamp_motifs(
             max_matches=None,
             max_distance=max_distance,
             atol=atol,
+            query_idx=candidate_idx,
             p=p,
         )
 
@@ -295,6 +296,7 @@ def aamp_match(
     max_distance=None,
     max_matches=None,
     atol=1e-8,
+    query_idx=None,
     p=2.0,
 ):
     """
@@ -334,6 +336,14 @@ def aamp_match(
         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 matrix profile is a self-join and
+        should be set to `None` for matrix profiles computed from AB-joins.
+        If `query_idx` is set to a specific integer value, then this will help ensure
+        that the self-match will be returned first.
+
     p : float, default 2.0
         The p-norm to apply for computing the Minkowski distance.
 
@@ -381,7 +391,11 @@ def max_distance(D):
 
     matches = []
 
-    candidate_idx = np.argmin(D)
+    if query_idx is not None:
+        candidate_idx = query_idx
+    else:
+        candidate_idx = np.argmin(D)
+
     while (
         D[candidate_idx] <= atol + max_distance
         and np.isfinite(D[candidate_idx])

stumpy/mmotifs.py

@@ -137,6 +137,7 @@ def mmotifs(
         max_motifs = 1
 
     T, M_T, Σ_T = core.preprocess(T, m)
+    P = P.copy()
 
     excl_zone = int(np.ceil(m / config.STUMPY_EXCL_ZONE_DENOM))
 
@@ -178,7 +179,7 @@ def mmotifs(
             motif_value > cutoffs[k]
             or not np.isfinite(motif_value)
             or (isinstance(max_distance, float) and motif_value > max_distance)
-        ):
+        ):  # pragma: no cover
             break
 
         query_matches = match(
@@ -189,6 +190,7 @@ def mmotifs(
             max_matches=max_matches,
             max_distance=max_distance,
             atol=atol,
+            query_idx=motif_idx,
             normalize=normalize,
             p=p,
         )

stumpy/motifs.py

@@ -119,6 +119,7 @@ def _motifs(
             max_matches=None,
             max_distance=max_distance,
             atol=atol,
+            query_idx=candidate_idx,
         )
 
         if len(query_matches) > min_neighbors:
@@ -322,6 +323,7 @@ def match(
     max_distance=None,
     max_matches=None,
     atol=1e-8,
+    query_idx=None,
     normalize=True,
     p=2.0,
 ):
@@ -365,6 +367,14 @@ def match(
         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 matrix profile is a self-join and
+        should be set to `None` for matrix profiles computed from AB-joins.
+        If `query_idx` is set to a specific integer value, then this will help ensure
+        that the self-match will be returned first.
+
     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
@@ -433,7 +443,11 @@ def max_distance(D):
 
     matches = []
 
-    candidate_idx = np.argmin(D)
+    if query_idx is not None:
+        candidate_idx = query_idx
+    else:
+        candidate_idx = np.argmin(D)
+
     while (
         D[candidate_idx] <= atol + max_distance
         and np.isfinite(D[candidate_idx])

test.sh

@@ -109,6 +109,8 @@ test_unit()
     check_errs $?
     pytest -x -W ignore::RuntimeWarning -W ignore::DeprecationWarning tests/test_motifs.py
     check_errs $?
+    pytest -x -W ignore::RuntimeWarning -W ignore::DeprecationWarning tests/test_mmotifs.py
+    check_errs $?
     pytest -x -W ignore::RuntimeWarning -W ignore::DeprecationWarning tests/test_gpu_mpdist.py
     pytest -x -W ignore::RuntimeWarning -W ignore::DeprecationWarning tests/test_snippets.py
     check_errs $?
@@ -132,6 +134,8 @@ test_unit()
     check_errs $?
     pytest -x -W ignore::RuntimeWarning -W ignore::DeprecationWarning tests/test_aamp_motifs.py
     check_errs $?
+    pytest -x -W ignore::RuntimeWarning -W ignore::DeprecationWarning tests/test_aamp_mmotifs.py
+    check_errs $?
     pytest -x -W ignore::RuntimeWarning -W ignore::DeprecationWarning tests/test_gpu_aampdist.py
     pytest -x -W ignore::RuntimeWarning -W ignore::DeprecationWarning tests/test_aampdist_snippets.py
     check_errs $?