Type:	Package
Title:	Variable Penalty Dynamic Time Warping
Version:	2.2.1
Date:	2024-08-27
Description:	Variable Penalty Dynamic Time Warping (VPdtw) for aligning chromatographic signals. With an appropriate penalty this method performs good alignment of chromatographic data without deforming the peaks (Clifford, D., Stone, G., Montoliu, I., Rezzi S., Martin F., Guy P., Bruce S., and Kochhar S.(2009) <doi:10.1021/ac802041e>; Clifford, D. and Stone, G. (2012) <doi:10.18637/jss.v047.i08>).
License:	GPL-2
URL:	https://github.com/ethanbass/VPdtw/
BugReports:	https://github.com/ethanbass/VPdtw/issues
RoxygenNote:	7.3.0
Encoding:	UTF-8
Suggests:	testthat (≥ 3.0.0), vdiffr
Config/testthat/edition:	3
NeedsCompilation:	yes
Packaged:	2024-08-27 18:29:45 UTC; ethanbass
Author:	David Clifford [aut], Glenn Stone [aut], Ethan Bass [ctb, cre]
Maintainer:	Ethan Bass <ethanbass@gmail.com>
Repository:	CRAN
Date/Publication:	2024-08-29 07:30:09 UTC

Variable Penalty Dynamic Time Warping function

Description

Use variable penalty dynamic time warping to align one (or many) query signal(s) to a master signal. Penalties are incurred whenever a non-diagonal move is taken.

Usage

VPdtw(
  reference,
  query,
  penalty = 0,
  maxshift = 50,
  Reference.type = c("random", "median", "mean", "trimmed")
)

Arguments

Details

Performs variable penalty dynamic time warping of query to reference. Sakoe Chiba dtw used with width maxshift.

The basic operation aligns a query vector to a reference vector.

If reference is not specified and query is a matrix then the reference is created based on the value of Reference.type. The four choices are random, median, mean and trimmed. These choose a column of query at random as a reference, or the piecewise median, mean or trimmed mean (with trim = 0.1) with missing values removed.

If query is a matrix and penalty is a vector then the same penalty is used to align each column of query to the reference. Different alignment paths are chosen for each column of the query matrix.

If query is a vector and penalty is a matrix then the query is aligned to the reference several times, using each column of the penalty matrix in turn as the penalty for the alignment.

If query and penalty are matrices then nothing happens. If you wish to align many query vectors and test many penalty vectors at the same time then do the appropriate looping (over queries, or penalties) outside of VPdtw.

Value

Author(s)

David Clifford, Glenn Stone

References

Alignment Using Variable Penalty Dynamic Time Warping by Clifford, D; Stone, G; Montoliu, I; et al. Analytical Chemistry Volume: 81 Issue: 3 Pages: 1000-1007 Published: 2009

See Also

Also check out the dtw package by Toni Giorgino which covers many variations of dynamic time warping.

Examples

  ## Citation
  citation("VPdtw")

  ## Basic Examples of zero-penalty DTW

  ## Example of exact fit in the middle
  query <- c(1,5,4,3,9,8,5,2,6,5,4)
  reference <- c(rnorm(5), query, rnorm(5))
  lambda <- rep(0, length(reference))
  maxshift <- 11
  res <- VPdtw(reference, query, lambda, maxshift)
  plot(res)
  res

  ## Example of exact fit on one side
  reference <- c(1,5,4,3,9,8,5,2,6,5,4)
  query <- c(rnorm(5), reference)
  reference <- c(reference, rnorm(5))
  lambda <- rep(0, length(reference))
  maxshift <- 6
  res <- VPdtw(reference, query, lambda, maxshift)
  plot(res)
  res

  ## Example of exact fit on the other side
  reference <- c(1,5,4,3,9,8,5,2,6,5,4)
  query <- c(reference, rnorm(5))
  reference <- c(rnorm(5), reference)
  lambda <- rep(0, length(reference))
  maxshift <- 6
  res <- VPdtw(reference, query, lambda, maxshift)
  plot(res)
  res

  ## Example of exact fit except where one query gets dropped and its all on one side
  reference <- c(1,5,4,3,9,8,5,2,6,5,4)
  query <- c(reference[1:5], 20, reference[6:11])
  reference <- c(rnorm(5), reference)
  query <- c(query, rnorm(5))
  lambda <- rep(0, length(reference))
  maxshift <- 6
  res <- VPdtw(reference, query, lambda, maxshift)
  plot(res)
  res
  
## Examples that use penalty term. Examples with long signals

data(reference)
data(query)
## Do alignment on log scale
reference <- log(reference)
query <- log(query)

## VPdtw
result <- VPdtw(reference=reference[1:2500], query = query[1:2500],
                penalty = dilation(reference[1:2500], 150)/4, maxshift=150)
plot(result)
result

## Zero penalty DTW
result2 <- VPdtw(reference = reference[1:2500], query = query[1:2500],
                 penalty = rep(0, length(reference)), maxshift = 150)
plot(result2)

## Try both penalties at the same time
penalty <- dilation(reference, 350)/5
penalty <- cbind(penalty, rep(0, length(penalty)))

result <- VPdtw(reference, query, penalty = penalty, maxshift = 350)
plot(result, "After")
plot(result, "Shift")
result

## All three plots at once
plot(result)

Compute a morphological dilation of a signal

Description

A dilation is a moving local maximum over a window of specific fixed width specified by span. This dilation is computed first in one direction and then in the other.

Usage

dilation(y, span)

Arguments

Details

A dilation is a method often used in mathematical morphology and image analysis (Soille 1999). This function is for vectors not matrices or images though applying it to rows and columns of a matrix will give the corresponding results.

An erosion of a vector or image can also be computed easily from this by computing the dilation of -1 times the vector and transforming back.

We recommend using a dilation to form a penalty for use in VPdtw.

Value

Author(s)

David Clifford

References

Soille, P. Morphological Image Analysis: Principles and Applications; Springer: New York, 1999.

Examples

## Example 1 - dilation of a signal
data(reference)
dref <- dilation(reference, 150)
plot(reference, log = "y", type = "l")
lines(dref, col = 2)

## Example 2 - dilation of an image
BIN <- (volcano > 177)
dBIN <- t(apply(BIN, 1, dilation, span = 5))
dBIN <- apply(dBIN, 2, dilation, span = 5)
oldpar <- par(no.readonly = TRUE)
par(mfrow=c(2, 2))
image(volcano)
image(BIN)
image(dBIN)
par(oldpar)

Plot VPdtw object

Description

Plot VPdtw object

Usage

## S3 method for class 'VPdtw'
plot(
  x,
  type = c("All", "Before", "After", "Shift", "Chromatograms"),
  xlim = NULL,
  ...
)

Arguments

Value

No return value, called for side effects.

Side effects

Plots information about alignment according to value of type: either unaligned query and reference ("Before"), aligned query and reference ("After"), shift at each index ("Shift"), a three-panel plot containing all three of these options ("All"), or a two-panel plot with unaligned and aligned query ("Chromatograms").

Examples

  query <- c(1,5,4,3,9,8,5,2,6,5,4)
  reference <- c(rnorm(5), query, rnorm(5))
  lambda <- rep(0, length(reference))
  maxshift <- 11
  res <- VPdtw(reference, query, lambda, maxshift)
  plot(res)
  

Print VPdtw

Description

Print VPdtw

Usage

## S3 method for class 'VPdtw'
print(x, ...)

Arguments

Value

Numeric vector from the summary slot in the VPdtw object specified by x.

Examples

query <- c(1,5,4,3,9,8,5,2,6,5,4)
reference <- c(rnorm(5), query, rnorm(5))
lambda <- rep(0, length(reference))
maxshift <- 11
res <- VPdtw(reference, query, lambda, maxshift)
print(res)

GC-MS Chromatogram

Description

GC-MS chromatogram from a wine sample

Format

A numeric vector of length 10018

Details

This together with the query data are used in the VPdtw examples. The alignment of these two signals is usually carried out on the log scale. Plotting of this signal is best done also on the log scale (see example below).

Source

Amalia Berna, Stephen Trowell, CSIRO Food Futures Flagship

References

Amalia Z. Berna, Stephen Trowell, David Clifford, Wies Cynkar, Daniel Cozzolino, Geographical origin of Sauvignon Blanc wines predicted by mass spectrometry and metal oxide based electronic nose, Analytica Chimica Acta, Volume 648, Issue 2, 26 August 2009, Pages 146-152, ISSN 0003-2670, DOI: 10.1016/j.aca.2009.06.056. Keywords: Sauvignon Blanc; Electronic nose; Gas chromatography-mass spectrometry; Prediction

Examples

data(reference)
data(query)
plot(reference, log="y", type="l", main = "Gas Chromatogram", 
  ylab = "log(intensity)", lwd = 2, col = 1)
lines(query, col = 2)