******************************* :py:mod:`wildboar.distance.dtw` ******************************* .. py:module:: wildboar.distance.dtw .. autoapi-nested-parse:: DTW alignment and distance computations. The :mod:`wildboar.distance.dtw` module implements several functions for computing DTW alignments and distances. .. !! processed by numpydoc !! Module Contents --------------- Functions --------- .. autoapisummary:: wildboar.distance.dtw.ddtw_distance wildboar.distance.dtw.dtw_alignment wildboar.distance.dtw.dtw_average wildboar.distance.dtw.dtw_distance wildboar.distance.dtw.dtw_envelop wildboar.distance.dtw.dtw_lb_keogh wildboar.distance.dtw.dtw_mapping wildboar.distance.dtw.jeong_weight wildboar.distance.dtw.wddtw_distance wildboar.distance.dtw.wdtw_alignment wildboar.distance.dtw.wdtw_distance .. py:function:: ddtw_distance(x, y, *, r=1.0) Compute the derivative dynamic time warping distance. :Parameters: **x** : array-like of shape (x_timestep, ) The first time series. **y** : array-like of shape (y_timestep, ) The second time series. **r** : float, optional The warping window in [0, 1] as a fraction of max(x_timestep, y_timestep). :Returns: float The dynamic time warping distance. .. seealso:: :obj:`dtw_distance` compute the dtw distance .. !! processed by numpydoc !! .. py:function:: dtw_alignment(x, y, *, r=1.0, weight=None, out=None) Compute the Dynamic time warping alignment matrix. :Parameters: **x** : array-like of shape (x_timestep,) The first time series. **y** : array-like of shape (y_timestep,) The second time series. **r** : float, optional The warping window in [0, 1] as a fraction of max(x_timestep, y_timestep). **weight** : array-like of shape (max(x_timestep, y_timestep), ), optional A weighting vector to penalize warping. **out** : array-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. .. seealso:: :obj:`dtw_distance` compute the dtw distance .. rubric:: Notes If only the distance between two series is required use `dtw_distance` instead. .. !! processed by numpydoc !! .. py:function:: 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) Compute the DTW barycenter average (DBA). :Parameters: **X** : array-like of shape (n_samples, n_timestep) The samples to average. **r** : float, optional The warping window as a fraction of n_timestep. **g** : float, 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_weight** : array-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_stable** : int, optional The maximum number of epoch where the average with lowest cost is unchanged if `method='ssg'`. **learning_rate** : float, optional The learning rate, if `method="ssg"`. **decay** : float, optional The learning rate decay, if `method="ssg"`. **tol** : float, optional The minmum change in cost between two epochs, if `method="mm"`. **max_epoch** : int, optional The maximum number of epochs. **return_cost** : bool, optional Return the averaging cost if `True`. **verbose** : bool, optional If set, show runtime information. **random_state** : int or RandomState, optional Pseudo-random number generator. :Returns: **mean** : array-like of shape (m_timestep, ) or (n_timestep, ) The mean time series. **cost** : float, optional Return the cost of the average, if `return_cost=True`. .. rubric:: 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]) .. !! processed by numpydoc !! .. py:function:: dtw_distance(x, y, *, r=1.0) Compute the dynamic time warping distance. :Parameters: **x** : array-like of shape (x_timestep, ) The first time series. **y** : array-like of shape (y_timestep, ) The second time series. **r** : float, optional The warping window in [0, 1] as a fraction of `max(x_timestep, y_timestep)`. :Returns: float The dynamic time warping distance. .. seealso:: :obj:`dtw_alignment` compute the dtw alignment matrix .. !! processed by numpydoc !! .. py:function:: dtw_envelop(x, *, r=1.0) Compute the envelop for LB_keogh. :Parameters: **x** : array-like of shape (x_timestep,) The time series. **r** : float, optional The warping window in [0, 1] as a fraction of `max(x_timestep, y_timestep)`. :Returns: **lower** : ndarray of shape (x_timestep,) The min value of the envelop. **upper** : ndarray of shape (x_timestep,) The max value of the envelop. .. rubric:: References Keogh, E. (2002). Exact indexing of dynamic time warping. In 28th International Conference on Very Large Data Bases. .. only:: latex .. !! processed by numpydoc !! .. py:function:: dtw_lb_keogh(x, y=None, *, lower=None, upper=None, r=1.0) LB_keogh lower bound. :Parameters: **x** : array-like of shape (x_timestep,) The first time series. **y** : array-like of shape (x_timestep,), optional The second time series (same size as x). **lower** : ndarray of shape (x_timestep,), optional The min value of the envelop. **upper** : ndarray of shape (x_timestep,), optional The max value of the envelop. **r** : float, optional The warping window in [0, 1] as a fraction of `max(x_timestep, y_timestep)`. :Returns: **min_dist** : float The cumulative minimum distance. **lb_keogh** : ndarray of shape (x_timestep,), The lower bound at each time step. .. rubric:: 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 .. rubric:: References Keogh, E. (2002). Exact indexing of dynamic time warping. In 28th International Conference on Very Large Data Bases. .. only:: latex .. !! processed by numpydoc !! .. py:function:: dtw_mapping(x=None, y=None, *, alignment=None, r=1, return_index=False) Optimal warping path between two series or from a given alignment matrix. :Parameters: **x** : array-like of shape (x_timestep,), optional The first time series. **y** : array-like of shape (y_timestep,), optional The second time series. **alignment** : ndarray of shape (x_timestep, y_timestep), optional Precomputed alignment. **r** : float, optional The warping window in [0, 1] as a fraction of `max(x_timestep, y_timestep)`. **return_index** : bool, optional Return the indices of the warping path. :Returns: **indicator** : ndarray 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.. .. rubric:: 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 .. !! processed by numpydoc !! .. py:function:: jeong_weight(n, g=0.05) 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: **n** : int The number of weights. **g** : float, optional Penalty control. :Returns: ndarray of shape (n, ) The weights. .. rubric:: References .. [R4bf7d056babf-1] Jeong, Y., Jeong, M., Omitaomu, O. (2021) Weighted dynamic time warping for time series classification. Pattern Recognition 44, 2231-2240 .. only:: latex [R4bf7d056babf-1]_ .. !! processed by numpydoc !! .. py:function:: wddtw_distance(x, y, *, r=1.0, g=0.05) Compute the weighted derivative dynamic time warping distance. :Parameters: **x** : array-like of shape (x_timestep, ) The first time series. **y** : array-like of shape (y_timestep, ) The second time series. **r** : float, optional The warping window in [0, 1] as a fraction of `max(x_timestep, y_timestep)`. **g** : float, optional Penalization for points deviating the diagonal. :Returns: float The dynamic time warping distance. .. seealso:: :obj:`dtw_distance` compute the dtw distance .. !! processed by numpydoc !! .. py:function:: wdtw_alignment(x, y, *, r=1.0, g=0.5, out=None) Weighted dynamic time warping alignment. :Parameters: **x** : array-like of shape (x_timestep,) The first time series. **y** : array-like of shape (y_timestep,) The second time series. **r** : float, optional The warping window in [0, 1] as a fraction of `max(x_timestep, y_timestep)`. **g** : float, 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)) **out** : array-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. .. rubric:: References .. [Raec1aca773ed-1] Jeong, Y., Jeong, M., Omitaomu, O. (2021) Weighted dynamic time warping for time series classification. Pattern Recognition 44, 2231-2240 .. only:: latex [Raec1aca773ed-1]_ .. !! processed by numpydoc !! .. py:function:: wdtw_distance(x, y, *, r=1.0, g=0.05) Compute the weighted dynamic time warping distance. :Parameters: **x** : array-like of shape (x_timestep, ) The first time series. **y** : array-like of shape (y_timestep, ) The second time series. **r** : float, optional The warping window in [0, 1] as a fraction of `max(x_timestep, y_timestep)`. **g** : float, optional Penalization for points deviating the diagonal. :Returns: float The dynamic time warping distance. .. seealso:: :obj:`dtw_distance` compute the dtw distance .. !! processed by numpydoc !!