dtw {dtw}R Documentation

Dynamic Time Warp

Description

Compute Dynamic Time Warp and find optimal alignment between two time series.

Usage

dtw(x, y=NULL,
         dist.method="Euclidean",
         step.pattern="s",
         window.type="none",
         keep.internals=FALSE,
         distance.only=FALSE,
         ... )

is.dtw(d)

Arguments

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

Details

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:

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.

Value

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)

Note

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.

Author(s)

Toni Giorgino

References

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

See Also

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.

Examples


## 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;




[Package dtw version 1.5-3 Index]