dtw {dtw} | R Documentation |
Compute Dynamic Time Warp and find optimal alignment between two time series.
dtw(x, y=NULL, dist.method="Euclidean", step.pattern="s", window.type="none", keep.internals=FALSE, distance.only=FALSE, ... ) is.dtw(d)
x |
query vector or local cost matrix |
y |
template vector, unused if x given as cost matrix |
dist.method |
pointwise (local) distance function. See
dist in package proxy |
step.pattern |
step pattern. Character "s" (symmetric1), "a"
(asymmetric), or a stepPattern object describing the
local warping steps allowed with their cost (see stepPattern ) |
window.type |
windowing function. Character: "none", "itakura", "sakoechiba", "slantedband", or a function (see details). |
keep.internals |
don't discard the cumulative cost matrix and other internal structures |
distance.only |
only compute distance (no backtrack, faster) |
d |
an arbitrary R object |
... |
additional arguments, passed to window.type |
The function performs Dynamic Time Warp (DTW) and computes the optimal
alignment between two time series x
and y
, given as
numeric vectors. The ``optimal'' alignment minimizes the sum of
distances between aligned elements. Lengths of x
and y
may differ.
The (local) distance between elements of x
(query) and y
(template) is computed passing x
and y
to the
dist
function in package proxy
with the method dist.method
.
Multivariate time series and arbitrary distance metrics can be handled
by supplying a local-distance matrix. Element [i,j]
of the
local-distance matrix is understood as the distance between element
x[i]
and y[j]
. The distance matrix has therefore
n=length(x)
rows and m=length(y)
columns (see note
below).
Several common variants of DTW are supported via the
step.pattern
argument, which defaults to symmetric1
(White-Neely). Most common step patterns are pre-defined, plus the
user can write their own. See stepPattern
for details.
Windowing is supported by supplying a name into the window.type
argument (abbreviations allowed) between the built-in types:
"none"
"sakoechiba"
"slantedband"
"itakura"
window.type
can also be an user-defined windowing function.
See dtwWindowingFunctions
for all available windowing
functions, details on user-defined windowing, and a discussion of the
(mis)naming of the "Itakura" parallelogram as a global constraint.
Some windowing functions may require parameters, such as the
window.size
argument.
A native (fast, compiled) version of the function is normally available. If it is not, an interpreted equivalent will be used as a fall-back, with a warning.
is.dtw
tests whether the argument is of class dtw
.
An object of class dtw
with the following items:
distance |
the computed distance not normalized. Normalization depends on the chosen step pattern. |
N,M |
query and template length |
call |
the function call that created the object |
index1 |
matched elements: indices in x |
index2 |
corresponding mapped indices in y |
stepPatterns |
the stepPattern object used for the computation |
costMatrix |
if keep.internals=TRUE , the cumulative
cost matrix |
directionMatrix |
if keep.internals=TRUE , the
directions of steps that would be taken at each alignment pair
(integers indexing step patterns) |
Cost matrices (both input and output) have query elements row-wise (first index), and template elements column-wise (second index). They print according to the usual convention, with indexes increasing down- and rightwards. Many DTW papers and tutorials show matrices according to plot-like conventions, i.e. template index growing upwards. This may be confusing.
Toni Giorgino
Sakoe, H.; Chiba, S., Dynamic programming algorithm optimization for spoken word recognition,
Acoustics, Speech, and Signal Processing [see also IEEE Transactions on Signal Processing], IEEE Transactions on ,
vol.26, no.1, pp. 43-49, Feb 1978 URL: http://ieeexplore.ieee.org/xpls/abs_all.jsp?arnumber=1163055
dtwDist
, for iterating dtw over a set of timeseries;
dtwWindowingFunctions
, for windowing and global constraints;
stepPattern
, step patterns and local constraints;
plot.dtw
, plot methods for DTW objects.
To generate a local distance matrix, the functions
dist
in package proxy,
distance
in package analogue,
outer
may come handy.
## A noisy sine wave as query idx<-seq(0,6.28,len=100); query<-sin(idx)+runif(100)/10; ## A cosine is for template; sin and cos are offset by 25 samples template<-cos(idx) plot(template); lines(query,col="blue"); ## Find the best match alignment<-dtw(query,template); ## Display the mapping, AKA warping function - may be multiple-valued ## Equivalent to: plot(alignment,type="alignment") plot(alignment$index1,alignment$index2,main="Warping function"); ## Confirm: 25 samples off-diagonal alignment lines(1:100-25,col="red") ######### ## ## Subsetting allows warping and unwarping of ## timeseries according to the warping curve. ## See first example below. ## ## Most useful: plot the warped query along with template plot(template) lines(query[alignment$index1]~alignment$index2,col="blue") ## Plot the (unwarped) query and the inverse-warped template plot(query,type="l",col="blue") points(template[alignment$index2]~alignment$index1) ######### ## ## Contour plots of the cumulative cost matrix ## similar to: plot(alignment,type="density") or ## dtwPlotDensity(alignment) ## See more plots in ?plot.dtw ## ## keep = TRUE so we can look into the cost matrix alignment<-dtw(query,template,keep=TRUE); contour(alignment$costMatrix,col=terrain.colors(100),x=1:100,y=1:100, xlab="Query (noisy sine)",ylab="Template (cosine)"); lines(alignment$index1,alignment$index2,col="red",lwd=2); ######### ## ## An hand-checkable example ## ldist<-matrix(1,nrow=6,ncol=6); # Matrix of ones ldist[2,]<-0; ldist[,5]<-0; # Mark a clear path of zeroes ldist[2,5]<-.01; # Forcely cut the corner ds<-dtw(ldist); # DTW with user-supplied local # cost matrix da<-dtw(ldist,step="a"); # Also compute the asymmetric plot(ds$index1,ds$index2,pch=3); # Symmetric: alignment follows # the low-distance marked path points(da$index1,da$index2,col="red"); # Asymmetric: visiting # 1 is required twice ds$distance; da$distance;