SimHashIndexANN¶

class SimHashIndexANN(n_tables=20, n_bits_per_table=8, hash_func_distribution='gaussian', random_state=None, normalize=True, n_jobs=1)[source]¶

Bases: BaseWholeSeriesSearch

Approximate nearest neighbor search using multi-table SimHash LSH.

This is a canonical Locality-Sensitive Hashing (LSH) index for cosine/angular similarity. Each series is hashed with SimHash (the sign of Gaussian random projections over the full series), whose bit-collision probability is exactly 1 - theta / pi for the angle theta between two series.

The index uses the classic (k, L) amplification of Indyk-Motwani / Charikar:

n_bits_per_table (k) bits are concatenated into a key per table (AND-amplification: two series share a bucket only if all k bits agree),
n_tables (L) independent tables are kept (OR-amplification: a series is a candidate if it shares the query’s bucket in any table).

A query probes its bucket in each of the L tables and gathers the candidates that share at least one of those buckets. Candidates are ranked by their collision count – the number of tables in which they land in the query’s bucket – and the top k are returned. The collision count is a cheap proxy for angular similarity (a closer series agrees on more bits, so it collides in more tables); the returned distance is its reciprocal 1 / collision_count, which is monotone in that proxy (smaller means more collisions, i.e. closer). Probing a handful of buckets instead of scanning the whole collection, with no exact distance computation, is what makes the query sublinear.

Note that this method provides approximate results: a true neighbor is missed only if it never shares a bucket with the query in any table, and ties in the collision count are broken arbitrarily (by index). Larger n_tables raises recall (and candidate-set size); larger n_bits_per_table makes buckets more selective (smaller candidate sets, faster queries, lower recall).

Parameters:

n_tablesint, default=20: Number of hash tables L (OR-amplification). More tables increase recall and the candidate-set size.
n_bits_per_tableint, default=8: Number of bits k concatenated into each table key (AND-amplification). More bits make buckets more selective: smaller candidate sets and faster queries, but lower recall.
hash_func_distribution{“gaussian”, “discrete”, “uniform”}, default=”gaussian”: Distribution used to draw the random projection vectors. "gaussian" draws from a standard normal, the only choice for which the bit-collision probability is exactly 1 - theta / pi. "discrete" draws from {-1, 1} and "uniform" from [-1, 1]; both approximate the Gaussian via the central limit theorem.
random_stateint, optional: Random seed for reproducibility of hash function generation.
normalizebool, default=True: Whether to z-normalize series before hashing. Recommended for scale-independent matching: the sign random projections then capture angular (cosine) similarity.
n_jobsint, default=1: Number of parallel threads used to hash the collection at fit time.

Attributes:

X_np.ndarray of shape (n_cases, n_channels, n_timepoints): The fitted collection of time series (as stored by the base class).
tables_list of dict: The n_tables hash tables, each mapping a k-bit bucket key (the k table bits packed into an integer in [0, 2 ** k)) to an int array of the case indices that fall in that bucket.
hash_funcs_np.ndarray of shape (n_tables * n_bits_per_table, n_channels, n_timepoints): The Gaussian (or discrete/uniform) random projection vectors.
hash_funcs_flat_np.ndarray of shape (n_tables * n_bits_per_table, n_channels * n_timepoints): hash_funcs_ flattened to one vector per projection, so that hashing is a single BLAS matrix product. Its dtype follows the fitted data (float64 by default), so fitting on float32 input makes hashing ~2-3x faster without changing the (sign-only) signatures.
n_cases_int: Number of time series in the fitted collection.
n_channels_int: Number of channels in the fitted time series.
n_timepoints_int: Number of timepoints in each fitted time series.

See also

NaiveSeriesSearch: Exact nearest neighbor search (slower but exact).

Notes

Capabilities ¶
Missing Values	No
Multithreading	Yes
Univariate	Yes
Multivariate	Yes
Unequal Length	No

In addition to k and axis, predict accepts the following search option as a keyword argument:

inverse_distancebool, default=False
Must be left False. This index captures near neighbors, not far ones, so passing inverse_distance=True raises NotImplementedError. Use NaiveSeriesSearch with inverse_distance=True for farthest-neighbor queries.

Unlike NaiveSeriesSearch, this estimator does not accept dist_threshold or X_index; passing them raises a TypeError.

References

[1]

M. S. Charikar. “Similarity estimation techniques from rounding algorithms”. STOC 2002. Introduces SimHash (sign random projection) as an LSH family for cosine similarity.

[2]

P. Indyk and R. Motwani. “Approximate nearest neighbors: towards removing the curse of dimensionality”. STOC 1998. The multi-table (k, L) LSH scheme.

Examples

>>> import numpy as np
>>> from aeon.similarity_search.whole_series import SimHashIndexANN
>>> X_fit = np.random.rand(100, 1, 50)
>>> query = np.random.rand(1, 50)
>>> index = SimHashIndexANN()
>>> index.fit(X_fit)
SimHashIndexANN()
>>> indexes, distances = index.predict(query, k=5)

Methods

`clone`([random_state])	Obtain a clone of the object with the same hyperparameters.
`fit`(X[, y])	Fit estimator to X.
`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[, k, axis])	Find the k nearest neighbors to X in the fitted collection.
`reset`([keep])	Reset the object to a clean post-init state.
`set_params`(**params)	Set the parameters of this estimator.
`set_predict_request`(*[, axis, k])	Configure whether metadata should be requested to be passed to the `predict` method.
`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)

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

Fit estimator to X.

Parameters:

Xnp.ndarray shape (n_cases, n_channels, n_timepoints): Input data to store and use as database against the query given when calling predict.
y: ignored, exists for API consistency reasons.

Returns:

selfa fitted instance of the estimator

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: ndarray, k: int = 1, axis: int = 1, **kwargs)[source]¶

Find the k nearest neighbors to X in the fitted collection.

Returns the indexes and distances of the best matches to X. It is possible that fewer than k indexes are returned if fewer than k admissible matches exist.

Parameters:

Xnp.ndarray, 2D array of shape (n_channels, n_timepoints): Query series for which to find the nearest neighbors in the database. For subsequence search, n_timepoints should equal the length parameter. For whole series search, n_timepoints should match the series length in the fitted collection.
kint or np.inf, default=1: Number of best matches to return. Must be a positive integer, or the sentinel np.inf to return all matches (supported by whole series estimators).
axisint, default=1: The time point axis of the input series if it is 2D. If axis==0, it is assumed each column is a time series and each row is a time point, i.e. the shape of the data is (n_timepoints, n_channels). axis==1 indicates the time series are in rows, i.e. the shape of the data is (n_channels, n_timepoints).
**kwargsdict, optional: Additional search options passed to the estimator’s _predict method. The accepted options (e.g. dist_threshold, inverse_distance, X_index, allow_trivial_matches, exclusion_factor) and their defaults differ per estimator; see the docstring of each concrete estimator for the options it supports.

Returns:

indexesnp.ndarray

Indexes of the best matches. The shape and meaning depend on the search type:

Subsequence search: shape (n_matches, 2) with (i_case, i_timestamp) pairs indicating which series and at what position the match was found.
Whole series search: shape (n_matches,) with case indices indicating which series in the fitted collection are nearest neighbors.

distancesnp.ndarray, shape (n_matches,)

Distances of the matches to the query. Lower values indicate better matches (unless inverse_distance=True is used).

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_predict_request(*, axis: bool | None | str = '$UNCHANGED$', k: bool | None | str = '$UNCHANGED$') → SimHashIndexANN¶

Configure whether metadata should be requested to be passed to the predict method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to predict if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to predict.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

axisstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for axis parameter in predict.
kstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for k parameter in predict.

Returns: