`wildboar.distance.dtw`#

DTW alignment and distance computations.

The wildboar.distance.dtw module implements several functions for computing DTW alignments and distances.

Module Contents#

Functions#

`ddtw_distance`(x, y, *[, r])	Compute the derivative dynamic time warping distance.
`dtw_alignment`(x, y, *[, r, weight, out])	Compute the Dynamic time warping alignment matrix.
`dtw_average`(X, *[, r, g, sample_weight, init, method, ...])	Compute the DTW barycenter average (DBA).
`dtw_distance`(x, y, *[, r])	Compute the dynamic time warping distance.
`dtw_envelop`(x, *[, r])	Compute the envelop for LB_keogh.
`dtw_lb_keogh`(x[, y, lower, upper, r])	LB_keogh lower bound.
`dtw_mapping`([x, y, alignment, r, return_index])	Optimal warping path between two series or from a given alignment matrix.
`jeong_weight`(n[, g])	Weighting described by Jeong et. al. (2011)[R4bf7d056babf-1]_.
`wddtw_distance`(x, y, *[, r, g])	Compute the weighted derivative dynamic time warping distance.
`wdtw_alignment`(x, y, *[, r, g, out])	Weighted dynamic time warping alignment.
`wdtw_distance`(x, y, *[, r, g])	Compute the weighted dynamic time warping distance.

wildboar.distance.dtw.ddtw_distance(x, y, *, r=1.0)[source]#

Compute the derivative dynamic time warping distance.

Parameters:

xarray-like of shape (x_timestep, ): The first time series.
yarray-like of shape (y_timestep, ): The second time series.
rfloat, optional: The warping window in [0, 1] as a fraction of max(x_timestep, y_timestep).

Returns:

float: The dynamic time warping distance.

See also

dtw_distance: compute the dtw distance

wildboar.distance.dtw.dtw_alignment(x, y, *, r=1.0, weight=None, out=None)[source]#

Compute the Dynamic time warping alignment matrix.

Parameters:

xarray-like of shape (x_timestep,): The first time series.
yarray-like of shape (y_timestep,): The second time series.
rfloat, optional: The warping window in [0, 1] as a fraction of max(x_timestep, y_timestep).
weightarray-like of shape (max(x_timestep, y_timestep), ), optional: A weighting vector to penalize warping.
outarray-like of shape (x_timestep, y_timestep), optional: Store the warping path in this array.

Returns:

ndarray of shape (x_timestep, y_timestep): The dynamic time warping alignment matrix.

See also

dtw_distance: compute the dtw distance

Notes

If only the distance between two series is required use dtw_distance instead.

wildboar.distance.dtw.dtw_average(X, *, r=1.0, g=None, sample_weight=None, init='random', method='mm', max_stable=5, learning_rate=0.1, decay=0.9, tol=1e-05, max_epoch=50, return_cost=False, verbose=False, random_state=None)[source]#

Compute the DTW barycenter average (DBA).

Parameters:

Xarray-like of shape (n_samples, n_timestep)

The samples to average.

rfloat, optional

The warping window as a fraction of n_timestep.

gfloat, optional

If set, use the weighted DTW alignment with g as penalty control.

w(x)= 1.0 / 1.0 + np.exp(-g * (x - m / 2)),

sample_weightarray-like of shape (n_samples, ), optional

The sample weight. This influences how much each sample contributes to the average.

init“random” or array-like of shape (m_timestep, ), optional

The initial sample used for average.

method{“mm”, “ssg”}, optional

The method for computing the DBA.

if “mm”, use the majorize-minimize mean algorithm [1], which is equivalent to the DBA method in [2].
if “ssg”, use the stochastic subgradient mean algorithm [1].

max_stableint, optional

The maximum number of epoch where the average with lowest cost is unchanged if method=’ssg’.

learning_ratefloat, optional

The learning rate, if method=”ssg”.

decayfloat, optional

The learning rate decay, if method=”ssg”.

tolfloat, optional

The minmum change in cost between two epochs, if method=”mm”.

max_epochint, optional

The maximum number of epochs.

return_costbool, optional

Return the averaging cost if True.

verbosebool, optional

If set, show runtime information.

random_stateint or RandomState, optional

Pseudo-random number generator.

Returns:

meanarray-like of shape (m_timestep, ) or (n_timestep, ): The mean time series.
costfloat, optional: Return the cost of the average, if return_cost=True.

Examples

>>> from wildboar.datasets import load_two_lead_ecg
>>> from wildboar.distance.dtw import dtw_average
>>> X, y = load_two_lead_ecg()
>>> dtw_average(X[:5], method="mm", random_state=1)
array([-2.27442791e-01,  3.19807473e-02,  1.77490053e-01,  1.60441308e-01,
        2.31930140e-01,  2.17437783e-01,  2.43925941e-01,  2.60983434e-01,
        2.72118437e-01,  7.73352049e-02, -1.56701557e-02, -5.53269314e-02,
       -7.33366128e-02, -1.09010828e-01, -1.97539989e-01, -1.71443248e-01,
       -1.71443248e-01, -1.71443248e-01, -2.42492836e-01, -1.71408958e-01,
       -1.71408958e-01, -1.71408958e-01, -1.71408958e-01, -1.71408958e-01,
       -1.71408958e-01, -1.71408958e-01, -1.82518334e-01, -3.35671953e-01,
        1.26442901e-01, -7.38342948e-02, -9.11248815e-01, -1.99355168e+00,
       -2.08588712e+00, -2.35954194e+00, -2.78345146e+00, -2.41023092e+00,
       -1.99915956e+00, -1.82717462e+00, -1.82717462e+00, -1.71687181e+00,
       -1.55819192e+00, -1.28805337e+00, -1.06653283e+00, -7.25159669e-01,
       -4.02389872e-01, -2.39410523e-01,  2.34687887e-03,  2.98654485e-01,
        4.85832342e-01,  6.56436416e-01,  7.25302660e-01,  7.77697444e-01,
        8.24606299e-01,  8.76357782e-01,  9.27083874e-01,  9.44590342e-01,
        9.44590342e-01,  9.44590342e-01,  9.44590342e-01,  9.44590342e-01,
        9.64184026e-01,  1.03608265e+00,  1.13964118e+00,  1.33595675e+00,
        1.09954847e+00,  9.61924171e-01,  9.61924171e-01,  9.61924171e-01,
        9.61924171e-01,  9.61924171e-01,  9.61924171e-01,  9.47433305e-01,
        8.29583168e-01,  7.00425122e-01,  5.80524683e-01,  4.70210329e-01,
        4.40259039e-01,  3.59657389e-01,  3.52170730e-01,  3.54666287e-01,
        1.93690730e-01,  2.23968406e-01])

wildboar.distance.dtw.dtw_distance(x, y, *, r=1.0)[source]#

Compute the dynamic time warping distance.

Parameters:

xarray-like of shape (x_timestep, ): The first time series.
yarray-like of shape (y_timestep, ): The second time series.
rfloat, optional: The warping window in [0, 1] as a fraction of max(x_timestep, y_timestep).

Returns:

float: The dynamic time warping distance.

See also

dtw_alignment: compute the dtw alignment matrix

wildboar.distance.dtw.dtw_envelop(x, *, r=1.0)[source]#

Compute the envelop for LB_keogh.

Parameters:

xarray-like of shape (x_timestep,): The time series.
rfloat, optional: The warping window in [0, 1] as a fraction of max(x_timestep, y_timestep).

Returns:

lowerndarray of shape (x_timestep,): The min value of the envelop.
upperndarray of shape (x_timestep,): The max value of the envelop.

References

Keogh, E. (2002).: Exact indexing of dynamic time warping. In 28th International Conference on Very Large Data Bases.

wildboar.distance.dtw.dtw_lb_keogh(x, y=None, *, lower=None, upper=None, r=1.0)[source]#

LB_keogh lower bound.

Parameters:

xarray-like of shape (x_timestep,): The first time series.
yarray-like of shape (x_timestep,), optional: The second time series (same size as x).
lowerndarray of shape (x_timestep,), optional: The min value of the envelop.
upperndarray of shape (x_timestep,), optional: The max value of the envelop.
rfloat, optional: The warping window in [0, 1] as a fraction of max(x_timestep, y_timestep).

Returns:

min_distfloat: The cumulative minimum distance.
lb_keoghndarray of shape (x_timestep,),: The lower bound at each time step.

Notes

if y=None, both lower and upper must be given
if y is given, lower and upper are ignored
if lower and upper is given and y=None, r is ignored

References

Keogh, E. (2002).: Exact indexing of dynamic time warping. In 28th International Conference on Very Large Data Bases.

wildboar.distance.dtw.dtw_mapping(x=None, y=None, *, alignment=None, r=1, return_index=False)[source]#

Optimal warping path between two series or from a given alignment matrix.

Parameters:

xarray-like of shape (x_timestep,), optional: The first time series.
yarray-like of shape (y_timestep,), optional: The second time series.
alignmentndarray of shape (x_timestep, y_timestep), optional: Precomputed alignment.
rfloat, optional: The warping window in [0, 1] as a fraction of max(x_timestep, y_timestep).
return_indexbool, optional: Return the indices of the warping path.

Returns:

indicatorndarray of shape (x_timestep, y_timestep): Boolean array with the dtw path.
(x_indices, y_indices)tuple, optional: The indices of the first and second dimension of the optimal alignment path..

Notes

either x and y or alignment must be provided
if alignment is given x and y are ignored
if alignment is given r is ignored

wildboar.distance.dtw.jeong_weight(n, g=0.05)[source]#

Weighting described by Jeong et. al. (2011)[R4bf7d056babf-1]_.

Uses g as the penalty control.

w = 1.0 / 1.0 + np.exp(-g * (x - n_samples / 2))

Parameters:

nint: The number of weights.
gfloat, optional: Penalty control.

Returns:

ndarray of shape (n, ): The weights.

References

[1]

Jeong, Y., Jeong, M., Omitaomu, O. (2021) Weighted dynamic time warping for time series classification. Pattern Recognition 44, 2231-2240

wildboar.distance.dtw.wddtw_distance(x, y, *, r=1.0, g=0.05)[source]#

Compute the weighted derivative dynamic time warping distance.

Parameters:

xarray-like of shape (x_timestep, ): The first time series.
yarray-like of shape (y_timestep, ): The second time series.
rfloat, optional: The warping window in [0, 1] as a fraction of max(x_timestep, y_timestep).
gfloat, optional: Penalization for points deviating the diagonal.

Returns:

float: The dynamic time warping distance.

See also

dtw_distance: compute the dtw distance

wildboar.distance.dtw.wdtw_alignment(x, y, *, r=1.0, g=0.5, out=None)[source]#

Weighted dynamic time warping alignment.

Parameters:

xarray-like of shape (x_timestep,)

The first time series.

yarray-like of shape (y_timestep,)

The second time series.

rfloat, optional

The warping window in [0, 1] as a fraction of max(x_timestep, y_timestep).

gfloat, optional

Weighting described by Jeong et. al. (2011)[Raec1aca773ed-1]_ using g as penalty control.

w = 1.0 / 1.0 + np.exp(-g * (x - n_samples / 2))

outarray-like of shape (x_timestep, y_timestep), optional

Store the warping path in this array.

Returns:

ndarray of shape (x_timestep, y_timestep): The dynamic time warping alignment matrix.

References

[1]

Jeong, Y., Jeong, M., Omitaomu, O. (2021) Weighted dynamic time warping for time series classification. Pattern Recognition 44, 2231-2240

wildboar.distance.dtw.wdtw_distance(x, y, *, r=1.0, g=0.05)[source]#

Compute the weighted dynamic time warping distance.

Parameters:

xarray-like of shape (x_timestep, ): The first time series.
yarray-like of shape (y_timestep, ): The second time series.
rfloat, optional: The warping window in [0, 1] as a fraction of max(x_timestep, y_timestep).
gfloat, optional: Penalization for points deviating the diagonal.

Returns:

float: The dynamic time warping distance.

See also

dtw_distance: compute the dtw distance

wildboar.distance.dtw#

Module Contents#

Functions#

`wildboar.distance.dtw`#