# Dynamic Time Warping (DTW)¶

class darts.dataprocessing.dtw.dtw.DTWAlignment(series1, series2, cost)[source]

Bases: `object`

Dynamic Time Warping (DTW) Alignment.

n

The length of series1

Type

int

m

The length of series2

Type

int

series1

A TimeSeries to align with series2.

Type

darts.timeseries.TimeSeries

series2

A TimeSeries to align with series1.

Type

darts.timeseries.TimeSeries

cost

The CostMatrix for DTW.

Type

darts.dataprocessing.dtw.cost_matrix.CostMatrix

Methods

 Gives the total distance between pair-wise elements in the two series after warping. Gives the mean distance between pair-wise elements in the two series after warping. Gives the index paths from series1 to series2. `plot`([new_plot, show_series, show_cost, ...]) Plot the warp path. `plot_alignment`([new_plot, series1_y_offset, ...]) Plots the uni-variate component of each series, with lines between them indicating the alignment selected by the DTW algorithm. Warps the two time series according to the warp path returned by DTWAlignment.path(), which minimizes the pair-wise distance.
cost: CostMatrix
distance()[source]

Gives the total distance between pair-wise elements in the two series after warping.

Returns

The total distance between pair-wise elements in the two series after warping.

Return type

float

m: int
mean_distance()[source]

Gives the mean distance between pair-wise elements in the two series after warping.

Returns

The mean distance between pair-wise elements in the two series after warping.

Return type

float

n: int
path()[source]

Gives the index paths from series1 to series2.

Returns

An array of indices [[i0,j0], [i1,j1], [i2,j2], …], where i indexes into series1 and j indexes into series2. Indices are in monotonic order, path[n] >= path[n-1]

Return type

np.ndarray of shape (len(path), 2)

plot(new_plot=False, show_series=False, show_cost=True, cost_cmap='summer', args_path={}, args_cost={}, args_series1={}, args_series2={})

Plot the warp path.

Parameters
• new_plot (`bool`) – Boolean value indicating whether to spawn a new figure.

• show_series (`bool`) – Boolean value indicating whether to additionally plot the two time series. Series1 will be plotted below the cost matrix and series2 to the left of the cost matrix.

• show_cost (`bool`) – Boolean value indicating whether to additionally plot the cost matrix. Cost Matrix will be displayed as a heatmap. Useful for visualizing the effect of the window function.

• cost_cmap (`str`) – Colormap style for cost matrix plot

• args_path (`dict`) – Some keyword arguments to pass to plot() function for warp path

• args_cost (`dict`) – Some keyword arguments to pass to imshow function for cost matrix

• args_series1 (`dict`) – Some keyword arguments to pass to plot() method for series1

• args_series2 (`dict`) – Some keyword arguments to pass to plot() method for series2

plot_alignment(new_plot=False, series1_y_offset=0, series2_y_offset=0, components=(0, 0), args_line={}, args_series1={}, args_series2={})

Plots the uni-variate component of each series, with lines between them indicating the alignment selected by the DTW algorithm.

Parameters
• new_plot (`bool`) – whether to spawn a new Figure

• series2_y_offset (`float`) – offset series1 vertically for ease of viewing.

• series1_y_offset (`float`) – offset series2 vertically for ease of viewing.

• components (`Tuple`[`Union`[`str`, `int`], `Union`[`str`, `int`]]) – Tuple of component index for series1 and component index for series2.

• args_line (`dict`) – Some keywords arguments to pass to plot() method for line

• args_series1 (`dict`) – Some keyword arguments to pass to plot() method for series1

• args_series2 (`dict`) – Some keyword arguments to pass to plot() method for series2

series1: TimeSeries
series2: TimeSeries
warped()[source]

Warps the two time series according to the warp path returned by DTWAlignment.path(), which minimizes the pair-wise distance. This will bring two time series that are out-of-phase back into phase.

Returns

Two new TimeSeries instances of the same length, indexed by pd.RangeIndex.

Return type
darts.dataprocessing.dtw.dtw.dtw(series1, series2, window=None, distance=None, multi_grid_radius=- 1)[source]

Determines the optimal alignment between two time series series1 and series2, according to the Dynamic Time Warping algorithm. The alignment minimizes the distance between pair-wise elements after warping. All elements in the two series are matched and are in strictly monotonically increasing order. Considers only the values in the series, ignoring the time axis.

Dynamic Time Warping can be applied to determine how closely two time series correspond, irrespective of phase, length or speed differences.

Parameters
• series1 (`TimeSeries`) – A TimeSeries to align with series2.

• series2 (`TimeSeries`) – A TimeSeries to align with series1.

• window (`Optional`[`Window`]) – Optionally, a Window used to constrain the search for the optimal alignment: see SakoeChiba and Itakura. Default considers all possible alignments (NoWindow).

• distance (`Optional`[`Callable`[[`Union`[`ndarray`, `floating`], `Union`[`ndarray`, `floating`]], `float`]]) –

Function taking as input either two floats for univariate series or two np.ndarray, and returning the distance between them.

Defaults to the abs difference for univariate-data and the sum of the abs difference for multi-variate series.

• multi_grid_radius (`int`) –

Default radius of -1 results in an exact evaluation of the dynamic time warping algorithm. Without constraints DTW runs in O(nxm) time where n,m are the size of the series. Exact evaluation with no constraints, will result in a performance warning on large datasets.

Setting multi_grid_radius to a value other than -1, will enable the approximate multi-grid solver, which executes in linear time, vs quadratic time for exact evaluation. Increasing radius trades solution accuracy for performance.

Returns

Helper object for getting warp path, mean_distance, distance and warped time series

Return type

DTWAlignment