Package 'VPdtw'

Title: Variable Penalty Dynamic Time Warping
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>).
Authors: David Clifford [aut], Glenn Stone [aut], Ethan Bass [ctb, cre] (ORCID: <https://orcid.org/0000-0002-6175-6739>)
Maintainer: Ethan Bass <[email protected]>
License: GPL-2
Version: 2.3.0
Built: 2026-10-25 06:20:45 UTC
Source: https://github.com/ethanbass/VPdtw

Help Index


Compute a morphological dilation of a signal

Description

A dilation is a moving local maximum. Each point is replaced by the maximum over the 2 * span - 1 points centred on it, computed as a one-sided maximum of width span taken first in one direction and then in the other.

Usage

dilation(y, span)

Arguments

y

Signal (as a numeric or logical vector). Missing values are removed before the dilation is computed.

span

A number, truncated to a whole number of at least 1, giving a centred window of 2 * span - 1 points. This is one more than the radius k used in Clifford and Stone (2012), so their dilation(r, k) is dilation(r, k + 1) here. A span larger than length(y) is treated as length(y), giving the maximum of the whole signal.

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

res

Dilation of y over a centred window of 2 * span - 1 points

Author(s)

David Clifford

References

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

Clifford, D. and Stone, G. (2012) Variable Penalty Dynamic Time Warping Code for Aligning Mass Spectrometry Chromatograms in R. Journal of Statistical Software, 47(8), 1–17. doi:10.18637/jss.v047.i08

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

x

A VPdtw object generated by VPdtw.

type

What to plot.

xlim

Numeric vector specifying x-axis limits.

...

Additional 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

x

A VPdtw object generated by VPdtw.

...

Additional argument.

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)

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

reference

Reference signal, NULL or a vector, see details.

query

Query signal, a vector or matrix, see details

penalty

Penalty term. A single number (repeated to the length of reference), a vector of at least the same length as reference, or a matrix with at least as many rows. See details. The default, 0, makes every non-diagonal move free, so the alignment is ordinary dynamic time warping within maxshift. For a variable penalty, build one from the reference with dilation(), as in the examples.

maxshift

Maximum allowable shift. Truncated to a whole number, which must be at least 1.

Reference.type

Choices for reference if NULL is input

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.

The warped query is built by repeating query points to stretch the signal and dropping them to compress it. A peak shifted whole is copied unchanged, but a peak that is stretched or compressed changes in height, shape and area. A large penalty under the reference's peaks stops the alignment from stretching or compressing them, so the warping happens in the baseline between peaks. The peaks then line up less precisely, and where they sit too close together for the baseline between them to absorb the drift, some may still be stretched or compressed. penalty must be finite, so use a large number rather than Inf.

Value

xVals

For plotting everything to correct index

reference

reference vector used by VPdtw expanded by NAs for plotting.

query

query passed to VPdtw

penalty

penalty passed to VPdtw

warpedQuery

result of alignment, same class as query

shift

shifts required to achieve alignment

summary

Summary information about the alignment. Used for print.VPdtw

information

Information about the alignment. Used for print.VPdtw

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, query, envir = environment())
## 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)