Nothing
##
## Copyright (c) 2006-2019 of Toni Giorgino
##
## This file is part of the DTW package.
##
## DTW is free software: you can redistribute it and/or modify it
## under the terms of the GNU General Public License as published by
## the Free Software Foundation, either version 3 of the License, or
## (at your option) any later version.
##
## DTW is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
## License for more details.
##
## You should have received a copy of the GNU General Public License
## along with DTW. If not, see <http://www.gnu.org/licenses/>.
##
##
## Document in dtwWindowingFunctions.Rd
##
#' Global constraints and windowing functions for DTW
#'
#' Various global constraints (windows) which can be applied to the
#' `window.type` argument of [dtw()], including the Sakoe-Chiba
#' band, the Itakura parallelogram, and custom functions.
#'
#'
#' Windowing functions can be passed to the `window.type` argument in
#' [dtw()] to put a global constraint to the warping paths allowed.
#' They take two integer arguments (plus optional parameters) and must return a
#' boolean value `TRUE` if the coordinates fall within the allowed region
#' for warping paths, `FALSE` otherwise.
#'
#' User-defined functions can read variables `reference.size`,
#' `query.size` and `window.size`; these are pre-set upon invocation.
#' Some functions require additional parameters which must be set (e.g.
#' `window.size`). User-defined functions are free to implement any
#' window shape, as long as at least one path is allowed between the initial
#' and final alignment points, i.e., they are compatible with the DTW
#' constraints.
#'
#' The `sakoeChibaWindow` function implements the Sakoe-Chiba band, i.e.
#' `window.size` elements around the `main` diagonal. If the window
#' size is too small, i.e. if `reference.size`-`query.size` >
#' `window.size`, warping becomes impossible.
#'
#' An `itakuraWindow` global constraint is still provided with this
#' package. See example below for a demonstration of the difference between a
#' local the two.
#'
#' The `slantedBandWindow` (package-specific) is a band centered around
#' the (jagged) line segment which joins element `[1,1]` to element
#' `[query.size,reference.size]`, and will be `window.size` columns
#' wide. In other words, the "diagonal" goes from one corner to the other of
#' the possibly rectangular cost matrix, therefore having a slope of
#' `M/N`, not 1.
#'
#' `dtwWindow.plot` visualizes a windowing function. By default it plots a
#' 200 x 220 rectangular region, which can be changed via `reference.size`
#' and `query.size` arguments.
#'
#' @name dtwWindowingFunctions
#' @aliases noWindow sakoeChibaWindow slantedBandWindow itakuraWindow
#' dtwWindowingFunctions dtwWindow.plot
#' @param iw index in the query (row) -- automatically set
#' @param jw index in the reference (column) -- automatically set
#' @param query.size size of the query time series -- automatically set
#' @param reference.size size of the reference time series -- automatically set
#' @param window.size window size, used by some windowing functions -- must be
#' set
#' @param fun a windowing function
#' @param ... additional arguments passed to windowing functions
#' @return Windowing functions return `TRUE` if the coordinates passed as
#' arguments fall within the chosen warping window, `FALSE` otherwise.
#' User-defined functions should do the same.
#' @note Although `dtwWindow.plot` resembles object-oriented notation,
#' there is not a such a dtwWindow class currently.
#'
#' A widely held misconception is that the "Itakura parallelogram" (as
#' described in reference 2) is a *global* constraint, i.e. a window.
#' To the author's knowledge, it instead arises from the local slope
#' restrictions imposed to the warping path, such as the one implemented by the
#' [typeIIIc()] step pattern.
#' @author Toni Giorgino
#' @references
#' 1. Sakoe, H.; Chiba, S., *Dynamic programming algorithm
#' optimization for spoken word recognition,* Acoustics, Speech, and Signal
#' Processing, IEEE Transactions on , vol.26, no.1, pp. 43-49, Feb 1978
#' \doi{10.1109/TASSP.1978.1163055}
#' 2. Itakura, F., *Minimum prediction residual principle applied to
#' speech recognition,* Acoustics, Speech, and Signal Processing,
#' IEEE Transactions on , vol.23, no.1, pp.
#' 67-72, Feb 1975. \doi{10.1109/TASSP.1975.1162641}
#' @keywords ts
#' @examples
#'
#'
#' ## Display some windowing functions
#' dtwWindow.plot(itakuraWindow, main="So-called Itakura parallelogram window")
#' dtwWindow.plot(slantedBandWindow, window.size=2,
#' reference=13, query=17, main="The slantedBandWindow at window.size=2")
#'
#'
#' ## Asymmetric step with Sakoe-Chiba band
#'
#' idx<-seq(0,6.28,len=100);
#' query<-sin(idx)+runif(100)/10;
#' reference<-cos(idx);
#'
#' asyband<-dtw(query,reference,keep=TRUE,
#' step=asymmetric,
#' window.type=sakoeChibaWindow,
#' window.size=30 );
#'
#' dtwPlot(asyband,type="density",main="Sine/cosine: asymmetric step, S-C window")
#'
#'
#'
NULL
## A band around the diagonal. The band includes the diagonal +-
## window.size.
#' @export
#' @rdname dtwWindowingFunctions
`sakoeChibaWindow` <-
function(iw,jw,window.size,...) {
return(abs(jw-iw)<=window.size);
}
## A band around the diagonal. The band includes the segment
## connecting [1,1] to [query.size,reference.size] window.size,
## measured along the second index (columns)
#' @export
#' @rdname dtwWindowingFunctions
`slantedBandWindow` <-
function(iw,jw,query.size,reference.size,window.size,...) {
diagj<-(iw*reference.size/query.size);
return(abs(jw-diagj)<=window.size);
}
## "Itakura" parallelogram: see documentation.
##
#' @export
#' @rdname dtwWindowingFunctions
`itakuraWindow` <-
function(iw,jw,query.size,reference.size,...) {
## Shorthands
n<-query.size;
m<-reference.size;
ok<- (jw < 2*iw) &
(iw <= 2*jw) &
(iw >= n-1-2*(m-jw)) &
(jw > m-1-2*(n-iw)) ;
return(ok);
}
## Plot a sample of the windowing function
#' @export
#' @rdname dtwWindowingFunctions
dtwWindow.plot <- function(fun,query.size=200,reference.size=220,...) {
n<-query.size;
m<-reference.size;
mm<-matrix(0,n,m);
mm[fun(row(mm),col(mm),query.size=n,reference.size=m,...)]<-1;
image( z=mm,
x=1:n,
y=1:m,
xlab=sprintf("Query: samples 1..%d",n),
ylab=sprintf("Reference: samples 1..%d",m)
);
}
## no warping window: no restrictions
#' @export
#' @rdname dtwWindowingFunctions
`noWindow` <-
function(iw,jw,...) {
return(TRUE);
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.