StompMotif¶

class StompMotif(length: int, normalize: bool | None = False)[source]¶

Bases: BaseSeriesSimilaritySearch

Estimator to extract top k motifs using STOMP, described in [1].

This estimator can perform multiple types of motif search operation by using different parameterization. We base oursleves on Figure 3 of [R498399f961be-2] to establish the following list, but modify the confusing naming for some of them. We do not yet support “Learning” and “Valmod” motifs :

for “Pair Motifs”This is the default configuration: {
“motif_size”: 1,

}

for “k-motifs”the extension of pair motifs: {
“motif_size”: k,

}

for “r-motifs” (originally named k-motifs, which was confusing as it is a

range based motif): {

“motif_size”:np.inf, “dist_threshold”:r, “motif_extraction_method”:”r_motifs”

}

Parameters:

lengthint: The length of the motifs to extract. This is the length of the subsequence that will be used in the computations.
normalizebool: Whether the computations between subsequences should use a z-normalied distance.

Notes

Capabilities ¶
Missing Values	No
Multithreading	No
Univariate	Yes
Multivariate	Yes

This estimator only provides an exact computation method, faster approximate methods also exist in the literature. We use a squared euclidean distance instead of the euclidean distance, if you want euclidean distance results, you should square root the obtained results.

References

[1]

Yan Zhu, Zachary Zimmerman, Nader Shakibay Senobari, Chin-Chia Michael

Yeh, Gareth Funning, Abdullah Mueen, Philip Brisk, and Eamonn Keogh. 2016. Matrix profile II: Exploiting a novel algorithm and GPUs to break the one hundred million barrier for time series motifs and joins. In 2016 IEEE 16th international conference on data mining (ICDM). IEEE, 739–748. .. [R498399f961be-2] Patrick Schäfer and Ulf Leser. 2022. Motiflets: Simple and Accurate Detection of Motifs in Time Series. Proc. VLDB Endow. 16, 4 (December 2022), 725–737. https://doi.org/10.14778/3574245.3574257

Methods

`clone`([random_state])	Obtain a clone of the object with the same hyperparameters.
`compute_matrix_profile`(X[, motif_size, ...])	Compute matrix profile.
`fit`(X[, y])	Fit method: data preprocessing and storage.
`fit_predict`(X, **kwargs)	Fit and predict on a single series X in order to compute self-motifs.
`get_class_tag`(tag_name[, raise_error, ...])	Get tag value from estimator class (only class tags).
`get_class_tags`()	Get class tags from estimator class and all its parent classes.
`get_fitted_params`([deep])	Get fitted parameters.
`get_params`([deep])	Get parameters for this estimator.
`get_tag`(tag_name[, raise_error, ...])	Get tag value from estimator class.
`get_tags`()	Get tags from estimator.
`predict`(X, **kwargs)	Predict function.
`reset`([keep])	Reset the object to a clean post-init state.
`set_params`(**params)	Set the parameters of this estimator.
`set_tags`(**tag_dict)	Set dynamic tags to given values.

clone(random_state=None)[source]¶

Obtain a clone of the object with the same hyperparameters.

A clone is a different object without shared references, in post-init state. This function is equivalent to returning sklearn.clone of self. Equal in value to type(self)(**self.get_params(deep=False)).

Parameters:

random_stateint, RandomState instance, or None, default=None: Sets the random state of the clone. If None, the random state is not set. If int, random_state is the seed used by the random number generator. If RandomState instance, random_state is the random number generator.

Returns:

estimatorobject: Instance of type(self), clone of self (see above)

Compute matrix profile.

The matrix profile is computed on the series given in fit (X_). If X is not given, computes the self matrix profile of X_. Otherwise, compute the matrix profile of X_ relative to X.

Parameters:

Xnp.ndarray, shape = (n_channels, n_timepoints): A 2D array time series against which the matrix profile of X_ will be computed.
motif_sizeint: The number of subsequences in a motif. Default is 1, meaning we extract motif pairs (the query and its best match).
dist_thresholdfloat: The maximum allowed distance of a candidate subsequence of X to a query subsequence from X_ for the candidate to be considered as a neighbor.
inverse_distancebool: If True, the matching will be made on the inverse of the distance, and thus, the worst matches to the query will be returned instead of the best ones.
exclusion_factorfloat, default=0.5: A factor of the query length used to define the exclusion zone when allow_trivial_matches is set to False. For a given timestamp, the exclusion zone starts from :math:id_timestamp - floor(length * exclusion_factor) and end at :math:id_timestamp + floor(length * exclusion_factor).
is_self_computationbool: Whether X is equal to the series X_ given during fit.

Returns:

MPTypedList of np.ndarray (n_timepoints - L + 1): Matrix profile distances for each query subsequence. n_timepoints is the number of timepoint of X_. Each element of the list contains array of variable size.
IPTypedList of np.ndarray (n_timepoints - L + 1): Indexes of the top matches for each query subsequence. n_timepoints is the number of timepoint of X_. Each element of the list contains array of variable size.

fit(X: ndarray, y=None)[source]¶

Fit method: data preprocessing and storage.

Parameters:

Xnp.ndarray, 2D array of shape (n_channels, n_timepoints): Input series to be used for the similarity search operations.
yoptional: Not used.

Returns:

self

Raises:

TypeError: If the input X array is not 2D raise an error.

fit_predict(X, **kwargs)[source]¶

Fit and predict on a single series X in order to compute self-motifs.

Parameters:

Xnp.ndarray, shape = (n_channels, n_tiempoints): Series to fit and predict on.
kwargsdict, optional: Additional keyword argument as dict or individual keywords args to pass to the estimator during predict.

Returns:

indexesnp.ndarray: Indexes of series in the that are similar to X.
distancesnp.ndarray: Distance of the matches to each series

classmethod get_class_tag(tag_name, raise_error=True, tag_value_default=None)[source]¶

Get tag value from estimator class (only class tags).

Parameters:

tag_namestr: Name of tag value.
raise_errorbool, default=True: Whether a ValueError is raised when the tag is not found.
tag_value_defaultany type, default=None: Default/fallback value if tag is not found and error is not raised.

Returns:

tag_value: Value of the tag_name tag in cls. If not found, returns an error if raise_error is True, otherwise it returns tag_value_default.

Raises:

ValueError: if raise_error is True and tag_name is not in self.get_tags().keys()

Examples

>>> from aeon.classification import DummyClassifier
>>> DummyClassifier.get_class_tag("capability:multivariate")
True

classmethod get_class_tags()[source]¶

Get class tags from estimator class and all its parent classes.

Returns:

collected_tagsdict: Dictionary of tag name and tag value pairs. Collected from _tags class attribute via nested inheritance. These are not overridden by dynamic tags set by set_tags or class __init__ calls.

get_fitted_params(deep=True)[source]¶

Get fitted parameters.

State required:: Requires state to be “fitted”.

Parameters:

deepbool, default=True: If True, will return the fitted parameters for this estimator and contained subobjects that are estimators.

Returns:

fitted_paramsdict: Fitted parameter names mapped to their values.

get_params(deep=True)¶

Get parameters for this estimator.

Parameters:

deepbool, default=True: If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict: Parameter names mapped to their values.

get_tag(tag_name, raise_error=True, tag_value_default=None)[source]¶

Get tag value from estimator class.

Includes dynamic and overridden tags.

Parameters:

tag_namestr: Name of tag to be retrieved.
raise_errorbool, default=True: Whether a ValueError is raised when the tag is not found.
tag_value_defaultany type, default=None: Default/fallback value if tag is not found and error is not raised.

Returns:

tag_value: Value of the tag_name tag in self. If not found, returns an error if raise_error is True, otherwise it returns tag_value_default.

Raises:

ValueError: if raise_error is True and tag_name is not in self.get_tags().keys()

Examples

>>> from aeon.classification import DummyClassifier
>>> d = DummyClassifier()
>>> d.get_tag("capability:multivariate")
True

get_tags()[source]¶

Get tags from estimator.

Includes dynamic and overridden tags.

Returns:

collected_tagsdict: Dictionary of tag name and tag value pairs. Collected from _tags class attribute via nested inheritance and then any overridden and new tags from __init__ or set_tags.

predict(X, **kwargs)[source]¶

Predict function.

Parameters:

Xnp.ndarray, shape = (n_channels, n_tiempoints): Series to predict on.
kwargsdict, optional: Additional keyword argument as dict or individual keywords args to pass to the estimator.

Returns:

indexesnp.ndarray, shape = (k): Indexes of series in the that are similar to X.
distancesnp.ndarray, shape = (k): Distance of the matches to each series

reset(keep=None)[source]¶

Reset the object to a clean post-init state.

After a self.reset() call, self is equal or similar in value to type(self)(**self.get_params(deep=False)), assuming no other attributes were kept using keep.

Detailed behaviour:

removes any object attributes, except:: hyper-parameters (arguments of __init__) object attributes containing double-underscores, i.e., the string “__”

runs __init__ with current values of hyperparameters (result of get_params)

Not affected by the reset are:

object attributes containing double-underscores class and object methods, class attributes any attributes specified in the keep argument

Parameters:

keepNone, str, or list of str, default=None: If None, all attributes are removed except hyperparameters. If str, only the attribute with this name is kept. If list of str, only the attributes with these names are kept.

Returns:

selfobject: Reference to self.

Raises:

TypeError: If ‘keep’ is not a string or a list of strings.

set_params(**params)¶

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict: Estimator parameters.

Returns:

selfestimator instance: Estimator instance.

set_tags(**tag_dict)[source]¶

Set dynamic tags to given values.

Parameters:

**tag_dictdict: Dictionary of tag name and tag value pairs.

Returns:

selfobject: Reference to self.