dtaidistance.subsequence.localconcurrences

(requires version 2.3.0 or higher)

DTW-based subsequence matching.

author:

Wannes Meert

copyright:

Copyright 2021-2023 KU Leuven, DTAI Research Group.

license:

Apache License, Version 2.0, see LICENSE for details.

class dtaidistance.subsequence.localconcurrences.LCMatch(lc, row=None, col=None)

LocalConcurrences match

distance(do_sqrt=True)
property path
class dtaidistance.subsequence.localconcurrences.LCMatches(lc, matches=None)
append(match)
coverage()
covered()
distance(do_sqrt=True)
distance_compensated(penalty=None, max_factor=10)

Distance with compensation for missed parts in sequences.

Parameters:

  • penalty – Base penalty per missing step in the joint path

  • max_factor – Number >1

missing()
missing_segments()
plot(begin=None, end=None, showlegend=False, showpaths=True, showboundaries=True)
segments()
str(maxlength=10)
class dtaidistance.subsequence.localconcurrences.LocalConcurrences(series1, series2=None, gamma=1, tau=0, delta=0, delta_factor=1, only_triu=False, penalty=None, window=None, use_c=False, compact=None)

Version identification based on local concurrences.

Find recurring patterns across two time series. Used to identify whether one time series is a version of another. If the two time series are the same one, it can be used to find typical or frequent patterns in a time series.

Based on 7.3.2 Identification Procedure in Fundamentals of Music Processing, Meinard Müller, Springer, 2015.

Different from the original formulation, D_tau is introduced based on the given delta factor. This makes the penalty less sensitive to the cumulative effect of the paths in the self-similarity matrix S:

S_tau(n,m) = S(n,m) if S(n,m) >= tau (with tau >= 0)

delta if S(n,m) < tau (with tau >= 0 & delta <= 0)

And for the accumulated score matrix D:

D_tau(n,m) = max(0,

df * D_tau(n−1,m−1) + S_tau(n,m), df * D_tau(n−1,m) + S_tau(n,m), df * D_tau(n,m−1) + S_tau(n,m))

where df = 1 if S(n,m) >= tau and df=delta_factor (<=1) otherwise,

For finding paths the delta_factor has no influence. For the visualisation, it helps as patterns exhibit more similar values in the D matrix.

Parameters:

  • series1 – First time series.

  • series2 – Second time series. If empty, series1 is used and compared with itself.

  • gamma – Affinity transformation exp(-gamma*(s1[i] - s2[j])**2), should be >0

  • tau – threshold parameter, should be >= 0

  • delta – penalty parameter, should be <= 0

  • delta_factor – penalty factor parameter, should be <= 1

  • only_triu – Only consider upper triangular matrix in warping paths.

  • compact – Use the compact representation for the warping paths matrix (only when use_c is true).

align()
Returns:

align_fast()
best_match()
best_path(row, col, wp=None)
estimate_settings(series, series2=None, tau_factor=0.33, tau_type='mean', gamma=None)
estimate_settings_from_abs(series, series2=None, tau_abs=0.33)
estimate_settings_from_mean(series, series2=None, tau_mean=0.33)
estimate_settings_from_std(series, series2=None, tau_std=0.33)

Estimate delta, tau and delta_factor from series, tau_std and gamma.

Parameters:

  • series

  • tau_std – Set tau to differences larger than tau_std time standard deviation of the given series (default is 0.33, or reject differences that are larger than the deviation wrt to the mean of 75% of the values in the series, assuming a normal distribution).

Returns:

static from_other(lc, series1, series2=None)
kbest_matches(k=1, minlen=2, buffer=0, restart=True)

Yields the next best LocalConcurrent match. Stops at k matches (use None for all matches).

Parameters:

  • k – Number of matches to yield, None is all matches

  • minlen – Consider only matches of length longer than minlen

  • buffer – Matches cannot be closer than buffer to each other

  • restart – Start searching from start, ignore previous calls to kbest_matches

  • keep – Keep mask to search incrementally for multiple calls of kbest_matches

Returns:

Yield an LCMatch object

kbest_matches_store(k=1, minlen=2, buffer=0, restart=True, keep=False, matches=None, tqdm=None)
reset()
settings(kind=None)
settings_from(lc)
similarity_matrix()
similarity_matrix_matshow_kwargs(sm)
property wp
wp_c_print()
wp_c_print_compact()
wp_slice(rb=None, re=None, cb=None, ce=None, positivize=False)
dtaidistance.subsequence.localconcurrences.local_concurrences(series1, series2=None, gamma=1, tau=0, delta=0, delta_factor=1, estimate_settings=None, only_triu=None, penalty=None, window=None, use_c=False, compact=None)

Local concurrences, see LocalConcurrences.

Parameters:

  • series1

  • series2

  • gamma – Affinity transformation exp(-gamma*(s1[i] - s2[j])**2)

  • tau – threshold parameter

  • delta – penalty parameter Should be negative. Added instead of the affinity score (if score below tau threshold parameter).

  • delta_factor – multiply cumulative score (e.g. by 0.5). This is useful to have the same impact at different locations in the warping paths matrix, which is cumulative (and thus typically large in one corner and small in the opposite corner).

  • estimate_settings – Estimate tau, delta, delta_factor from given series. Will be passed as tau_std to estimate_settings_from_std.

  • only_triu – Only compute the upper traingle matrix values. Useful to avoid redundant computations when series1 is equal to series2 (or equivalently if series2 is None).

  • penalty – Penalty that is added when dynamic programming is using moving vertically or horizontally through the matrix instead of diagonally. Used to prefer diagonal paths.

  • compact – Use the compact representation for the warping paths matrix (only when use_c is true).

Returns: