distancematrix.consumer

Submodules

• distancematrix.consumer.abstract_consumer
• distancematrix.consumer.contextmanager
• distancematrix.consumer.contextual_matrix_profile
• distancematrix.consumer.distance_matrix
• distancematrix.consumer.matrix_profile_lr
• distancematrix.consumer.multidimensional_matrix_profile_lr
• distancematrix.consumer.radius_profile
• distancematrix.consumer.threshold_counter

Package Contents

Classes

ContextualMatrixProfile	A consumer that constructs the contextual matrix profile. The contextual matrix profile is formed by
DistanceMatrix	Helper class that provides a standard way to create an ABC using
MatrixProfileLR	Consumer of distance matrix information to form the left and right matrix profile and their corresponding
ShiftingMatrixProfileLR	Extension of MatrixProfileLR which supports streaming.
MatrixProfileLRReservoir	Consumer of distance matrix information to form the left and right matrix profile and their corresponding
MultidimensionalMatrixProfileLR	A consumer that builds the multidimensional matrix profile. This consumer takes in distance measures from
ThresholdCounter	Consumer that counts the number of values in each column of the distancematrix that are below

class distancematrix.consumer.ContextualMatrixProfile(context_manager: AbstractContextManager, rb_scale_factor=2.0)

Bases: distancematrix.consumer.abstract_consumer.AbstractStreamingConsumer

A consumer that constructs the contextual matrix profile. The contextual matrix profile is formed by taking the minimum of rectangles across the full distance matrix (where the matrix profile takes the minimum across columns).

This consumer supports streaming if the provided context manager does.

initialise(self, dims, query_subseq, series_subseq)

Initialise this consumer.

Parameters

• dims – the number of dimensions (data channels) this consumer will receive

• query_subseq – the number of query subsequences (rows in the distance matrix)

• series_subseq – the number of series subsequences (column in the distance matrix)

Returns

None

process_diagonal(self, diag, values)

Method called when a diagonal of the distance matrix is calculated.

The number of values on the diagonal might be less than the diagonal of the full matrix profile, this can occur when not enough data is available yet to calculate the entire distance matrix (typically for streaming when not enough data is available to fill the entire foreseen space).

Parameters

• diagonal_index – index of the diagonal in range ]-num_query_subseq, num_series_subseq[, the main diagonal has index 0

• values – array of shape (num_dimensions, num_values_on_diagonal) containing the distances

Returns

None

process_column(self, column_index, values)

Method called when a column of the distance matrix is calculated.

The number of values on the column might be less than the column of the full matrix profile, this can occur when not enough data is available yet to calculate the entire distance matrix (typically for streaming when not enough data is available to fill the entire foreseen space).

Parameters

• column_index – index of the column, in range [0, series_subseq[

• values – array of shape (num_dimensions, num_values_on_column) containing the distances

Returns

None

shift_series(self, amount)

Inform the consumer that the distance matrix has shifted in the series direction.

Parameters

amount – amount of subsequences that were shifted

Returns

None

shift_query(self, amount)

Inform the consumer that the distance matrix has shifted in the query direction.

Parameters

amount – amount of subsequences that were shifted

Returns

None

property match_index_query(self)

property match_index_series(self)

property distance_matrix(self)

class distancematrix.consumer.DistanceMatrix

Bases: distancematrix.consumer.abstract_consumer.AbstractStreamingConsumer

Helper class that provides a standard way to create an ABC using inheritance.

initialise(self, dims, query_subseq, series_subseq)

Initialise this consumer.

Parameters

• dims – the number of dimensions (data channels) this consumer will receive

• query_subseq – the number of query subsequences (rows in the distance matrix)

• series_subseq – the number of series subsequences (column in the distance matrix)

Returns

None

process_diagonal(self, diagonal_index, values)

Method called when a diagonal of the distance matrix is calculated.

The number of values on the diagonal might be less than the diagonal of the full matrix profile, this can occur when not enough data is available yet to calculate the entire distance matrix (typically for streaming when not enough data is available to fill the entire foreseen space).

Parameters

• diagonal_index – index of the diagonal in range ]-num_query_subseq, num_series_subseq[, the main diagonal has index 0

• values – array of shape (num_dimensions, num_values_on_diagonal) containing the distances

Returns

None

process_column(self, column_index, values)

Method called when a column of the distance matrix is calculated.

The number of values on the column might be less than the column of the full matrix profile, this can occur when not enough data is available yet to calculate the entire distance matrix (typically for streaming when not enough data is available to fill the entire foreseen space).

Parameters

• column_index – index of the column, in range [0, series_subseq[

• values – array of shape (num_dimensions, num_values_on_column) containing the distances

Returns

None

shift_series(self, amount)

Inform the consumer that the distance matrix has shifted in the series direction.

Parameters

amount – amount of subsequences that were shifted

Returns

None

shift_query(self, amount)

Inform the consumer that the distance matrix has shifted in the query direction.

Parameters

amount – amount of subsequences that were shifted

Returns

None

class distancematrix.consumer.MatrixProfileLR

Bases: distancematrix.consumer.abstract_consumer.AbstractConsumer

Consumer of distance matrix information to form the left and right matrix profile and their corresponding indices. The left matrix profile and index is a one dimensional series where each each value at index i contains the distance and index of the best match whose index is equal to or less than i. The right matrix profile and index contain the best match whose index is larger than i.

initialise(self, dims, query_subseq, series_subseq)

Initialise this consumer.

Parameters

• dims – the number of dimensions (data channels) this consumer will receive

• query_subseq – the number of query subsequences (rows in the distance matrix)

• series_subseq – the number of series subsequences (column in the distance matrix)

Returns

None

process_diagonal(self, diag, values)

Method called when a diagonal of the distance matrix is calculated.

The number of values on the diagonal might be less than the diagonal of the full matrix profile, this can occur when not enough data is available yet to calculate the entire distance matrix (typically for streaming when not enough data is available to fill the entire foreseen space).

Parameters

• diagonal_index – index of the diagonal in range ]-num_query_subseq, num_series_subseq[, the main diagonal has index 0

• values – array of shape (num_dimensions, num_values_on_diagonal) containing the distances

Returns

None

process_column(self, column_index, values)

Method called when a column of the distance matrix is calculated.

The number of values on the column might be less than the column of the full matrix profile, this can occur when not enough data is available yet to calculate the entire distance matrix (typically for streaming when not enough data is available to fill the entire foreseen space).

Parameters

• column_index – index of the column, in range [0, series_subseq[

• values – array of shape (num_dimensions, num_values_on_column) containing the distances

Returns

None

property matrix_profile_right(self)

property matrix_profile_left(self)

property profile_index_right(self)

property profile_index_left(self)

matrix_profile(self)

Creates the matrix profile based on the left and right matrix profile.

Returns

1D array

profile_index(self)

Creates the matrix profile index based on the left and right indices.

Returns

1D array

class distancematrix.consumer.ShiftingMatrixProfileLR(rb_scale_factor=2.0)

Bases: distancematrix.consumer.matrix_profile_lr.MatrixProfileLR, distancematrix.consumer.abstract_consumer.AbstractStreamingConsumer

Extension of MatrixProfileLR which supports streaming.

The profile indices tracked in this consumer refer to positions in the complete query series. As an example, if the original query consisted of 10 sequences, but has since shifted by 5 sequences, the profile indices can contain any value in [0..15], or -1 if no matrix profile value exists. These indices can be converted to indices local to the current window by subtracting the query_shift, keep in mind that some indices of the left matrix profile can refer to positions outside the current window.

The concept of left and right matrix profile is only useful when both query and series shift at the same time (distances are calculated over a self-join). Even if this is not the case, the values in this consumer are correct: the left matrix profile stores any values on or above the (unshifted) main diagonal, the right matrix profile stores any values below the (unshifted) main diagonal. (Since the diagonal shifts away when only the series is shifted, eventually only the left matrix profile will be used.)

initialise(self, dims, query_subseq, series_subseq)

Initialise this consumer.

Parameters

• dims – the number of dimensions (data channels) this consumer will receive

• query_subseq – the number of query subsequences (rows in the distance matrix)

• series_subseq – the number of series subsequences (column in the distance matrix)

Returns

None

process_diagonal(self, diag, values)

Method called when a diagonal of the distance matrix is calculated.

The number of values on the diagonal might be less than the diagonal of the full matrix profile, this can occur when not enough data is available yet to calculate the entire distance matrix (typically for streaming when not enough data is available to fill the entire foreseen space).

Parameters

• diagonal_index – index of the diagonal in range ]-num_query_subseq, num_series_subseq[, the main diagonal has index 0

• values – array of shape (num_dimensions, num_values_on_diagonal) containing the distances

Returns

None

process_column(self, column_index, values)

Method called when a column of the distance matrix is calculated.

The number of values on the column might be less than the column of the full matrix profile, this can occur when not enough data is available yet to calculate the entire distance matrix (typically for streaming when not enough data is available to fill the entire foreseen space).

Parameters

• column_index – index of the column, in range [0, series_subseq[

• values – array of shape (num_dimensions, num_values_on_column) containing the distances

Returns

None

shift_query(self, amount)

Inform the consumer that the distance matrix has shifted in the query direction.

Parameters

amount – amount of subsequences that were shifted

Returns

None

shift_series(self, amount)

Inform the consumer that the distance matrix has shifted in the series direction.

Parameters

amount – amount of subsequences that were shifted

Returns

None

property matrix_profile_right(self)

property matrix_profile_left(self)

property profile_index_right(self)

property profile_index_left(self)

class distancematrix.consumer.MatrixProfileLRReservoir(random_seed=None)

Bases: distancematrix.consumer.abstract_consumer.AbstractConsumer

Consumer of distance matrix information to form the left and right matrix profile and their corresponding indices. The left matrix profile and index is a one dimensional series where each each value at index i contains the distance and index of the best match whose index is less than i. The right matrix profile and index contain the best match whose index is equal to or larger than i.

This consumer differs from the regular MatrixProfileLR consumer in that it uses reservoir sampling to determine the matrix profile indices. This means that if multiple values in the distance matrix column have the exact same distance, a random index will be stored in the matrix profile index.

initialise(self, dims, query_subseq, series_subseq)

Initialise this consumer.

Parameters

• dims – the number of dimensions (data channels) this consumer will receive

• query_subseq – the number of query subsequences (rows in the distance matrix)

• series_subseq – the number of series subsequences (column in the distance matrix)

Returns

None

process_diagonal(self, diag, values)

Method called when a diagonal of the distance matrix is calculated.

The number of values on the diagonal might be less than the diagonal of the full matrix profile, this can occur when not enough data is available yet to calculate the entire distance matrix (typically for streaming when not enough data is available to fill the entire foreseen space).

Parameters

• diagonal_index – index of the diagonal in range ]-num_query_subseq, num_series_subseq[, the main diagonal has index 0

• values – array of shape (num_dimensions, num_values_on_diagonal) containing the distances

Returns

None

process_column(self, column_index, values)

Method called when a column of the distance matrix is calculated.

The number of values on the column might be less than the column of the full matrix profile, this can occur when not enough data is available yet to calculate the entire distance matrix (typically for streaming when not enough data is available to fill the entire foreseen space).

Parameters

• column_index – index of the column, in range [0, series_subseq[

• values – array of shape (num_dimensions, num_values_on_column) containing the distances

Returns

None

matrix_profile(self)

Creates the matrix profile based on the left and right matrix profile.

Returns

1D array

profile_index(self)

Creates the matrix profile index based on the left and right indices.

Returns

1D array

class distancematrix.consumer.MultidimensionalMatrixProfileLR(rb_scale_factor=2.0)

Bases: distancematrix.consumer.abstract_consumer.AbstractStreamingConsumer

A consumer that builds the multidimensional matrix profile. This consumer takes in distance measures from multiple channels (dimensions) at the same time and tracks the best distance, the index of this match and the dimensions used in this match. More specifically, if the input has N data channels, this consumer will select for each number of channels (1, 2, …, N), the channels containing the best match, index and dimensions. It will not track matches for any possible combination of channels.

This consumer keeps track of the left and right multidimensional profile, and can be used to create the (normal) multidimensional profile from it. The left profile, index and dimensions at index i contain information about a match whose index is less than or equal to i, while the right profile, index and dimensions track information about a match whose index is larger than i.

The profile is an array with shape (num_dimensions, num_distances). The value at row i, j contains the best averaged distances encountered at index j for any i+1 dimensions. The index is similar, but tracks the index of the query series that had the best match.

The dimensions being tracked is a list of length num_dimensions. Entry i of this list contains an (i+1, num_distances) array that lists the indices of the dimensions that contained the best match.

This consumer supports streaming.

initialise(self, dims, query_subseq, series_subseq)

Initialise this consumer.

Parameters

• dims – the number of dimensions (data channels) this consumer will receive

• query_subseq – the number of query subsequences (rows in the distance matrix)

• series_subseq – the number of series subsequences (column in the distance matrix)

Returns

None

process_diagonal(self, diag, values)

Method called when a diagonal of the distance matrix is calculated.

The number of values on the diagonal might be less than the diagonal of the full matrix profile, this can occur when not enough data is available yet to calculate the entire distance matrix (typically for streaming when not enough data is available to fill the entire foreseen space).

Parameters

• diagonal_index – index of the diagonal in range ]-num_query_subseq, num_series_subseq[, the main diagonal has index 0

• values – array of shape (num_dimensions, num_values_on_diagonal) containing the distances

Returns

None

process_column(self, column_index, values)

Method called when a column of the distance matrix is calculated.

The number of values on the column might be less than the column of the full matrix profile, this can occur when not enough data is available yet to calculate the entire distance matrix (typically for streaming when not enough data is available to fill the entire foreseen space).

Parameters

• column_index – index of the column, in range [0, series_subseq[

• values – array of shape (num_dimensions, num_values_on_column) containing the distances

Returns

None

shift_query(self, amount)

Inform the consumer that the distance matrix has shifted in the query direction.

Parameters

amount – amount of subsequences that were shifted

Returns

None

shift_series(self, amount)

Inform the consumer that the distance matrix has shifted in the series direction.

Parameters

amount – amount of subsequences that were shifted

Returns

None

md_matrix_profile(self)

Merges the left and right multidimensional matrix profile, to create the multidimensional matrix profile. :return: ndarray of shape (num_dimensions, num_subsequences)

md_profile_index(self)

Merges the left and right multidimensional matrix profile index, to create the multidimensional matrix profile index. :return: ndarray of shape (num_dimensions, num_subsequences)

md_profile_dimensions(self)

Merges the left and right dimensions, to create the dimensions for the multidimensional matrix profile. :return: list of length num_dimensions, where the entry at index i is an ndarray of shape (i+1, num_subsequences).

property md_matrix_profile_left(self)

property md_matrix_profile_right(self)

property md_profile_index_left(self)

property md_profile_index_right(self)

property md_profile_dimension_left(self)

property md_profile_dimension_right(self)

class distancematrix.consumer.ThresholdCounter(thresholds)

Bases: distancematrix.consumer.abstract_consumer.AbstractConsumer

Consumer that counts the number of values in each column of the distancematrix that are below or equal to specified thresholds.

This consumer counts values as they are passed and does not extrapolate or keep information about which values were already counted. Specifically: partial calculations will result in counts of the produced values, and passing the same diagonals multiple time could result in double counts.

initialise(self, dims, query_subseq, series_subseq)

Initialise this consumer.

Parameters

• dims – the number of dimensions (data channels) this consumer will receive

• query_subseq – the number of query subsequences (rows in the distance matrix)

• series_subseq – the number of series subsequences (column in the distance matrix)

Returns

None

process_diagonal(self, diag, values)

Method called when a diagonal of the distance matrix is calculated.

The number of values on the diagonal might be less than the diagonal of the full matrix profile, this can occur when not enough data is available yet to calculate the entire distance matrix (typically for streaming when not enough data is available to fill the entire foreseen space).

Parameters

• diagonal_index – index of the diagonal in range ]-num_query_subseq, num_series_subseq[, the main diagonal has index 0

• values – array of shape (num_dimensions, num_values_on_diagonal) containing the distances

Returns

None

process_column(self, column_index, values)

Method called when a column of the distance matrix is calculated.

The number of values on the column might be less than the column of the full matrix profile, this can occur when not enough data is available yet to calculate the entire distance matrix (typically for streaming when not enough data is available to fill the entire foreseen space).

Parameters

• column_index – index of the column, in range [0, series_subseq[

• values – array of shape (num_dimensions, num_values_on_column) containing the distances

Returns

None