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

`distance`()	Gives the total distance between pair-wise elements in the two series after warping.
`mean_distance`()	Gives the mean distance between pair-wise elements in the two series after warping.
`path`()	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.
`warped`()	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: (TimeSeries, TimeSeries)

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, None]) – 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], None]) –
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

DTW Windows