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.
- series2¶
A TimeSeries to align with series1.
- cost¶
The CostMatrix for DTW.
Methods
distance
()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.
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.
- 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 plotargs_path (
dict
) – Some keyword arguments to pass to plot() function for warp pathargs_cost (
dict
) – Some keyword arguments to pass to imshow function for cost matrixargs_series1 (
dict
) – Some keyword arguments to pass to plot() method for series1args_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 Figureseries2_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 lineargs_series1 (
dict
) – Some keyword arguments to pass to plot() method for series1args_series2 (
dict
) – Some keyword arguments to pass to plot() method for series2
- series1: darts.timeseries.TimeSeries¶
- series2: darts.timeseries.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