The main functions of the ptw package, performing
parametric time warping of one or more samples. Features in the
samples are optimally aligned with features in the reference(s). One
may align a single sample to a single reference, several samples to a
single reference, and several samples to several references. In the
latter case, the number of references and samples should be equal. One
may require that all samples are warped with the same warping
function, or one may allow individual warpings for all samples.
reference. Either a vector (containing one reference
signal) or a matrix (one reference per row). If
more than one reference is specified, the number of reference
signals must equal the number of sample signals.
samp
sample. A vector (containing one sample signal) or a
matrix (one sample per row).
selected.traces
optional vector containing the row numbers to
use from ref (if more than one reference signal is specified)
and samp.
init.coef
starting coefficients. The first number is the
zeroth-order coefficient (i.e., a constant shift); further numbers
indicate linear, quadratic, ... stretches. The default is to start
from the identity warping using a quadratic function
(c(0, 1, 0))
try
if try = TRUE, ptw does not optimize the
warping but returns a ptw object containing the warping for
init.coef. Default: FALSE
warp.type
default is to treat samples and references as single
entities and align them individually and independently. Using the
argument warp.type = "global" leads to one alignment
function; the samples are warped simultaneously to the
reference(s). Also see details
optim.crit
either "WCC" or "RMS". In both cases,
the optimal value of the alignment leads to a value of 0. For "WCC",
this means that 1 - WCC is optimized rather than WCC
(where the optimal value equals 1)
mode
either "forward" or "backward": the latter was the
original implementation, basically for a point i in the original
signal predicting the point j in the signal that would be in
position i in the warped signal. The interpretation of the
coefficients is counterintuitive. Therefore the default is
"forward", simply predicting the location (time) in the warped
signal of a particular point. Apart from possible numerical
optimisation issues, both warpings should give the same net result.
smooth.param
smoothing parameter for smoothing the reference
and sample when optim.crit equals "RMS". If no
smoothing is required, set this to 0. The default is to use
smoothing in the optimization mode, and no smoothing otherwise
trwdth
the width of the triangle in the WCC criterion during
the optimization, given as a number of data points. Default: 20
trwdth.res
the width of the triangle in the WCC calculation in
the calculation of the quality of the final result. Default: equal
to trwdth
verbose
logical, default is FALSE. Whether to give
output during the optimisation, which may be useful for large data
sets
...
further arguments to optim
x, object
an object of class "ptw"
Details
Function ptw and friends is meant for profile data,
where intensities have been recorded at regular time points; function
stptw is meant for lists of peaks, for instance obtained after
peak-picking the profile data. The latter option is less flexible
(Euclidean distance and backward warping have not been implemented)
but is much faster, especially for larger data sets.
In the optimization mode (try = FALSE), the function
optimizes the warping coefficients using the chosen criterion (either
"WCC" or "RMS"). For "RMS", the data are smoothed before the
optimization, but the quality of the final warping is measured on the
unsmoothed data. For "WCC", the warping is performed using
trwdth as the triangle width, but the quality of the final
solution is measured using trwdth.res.
If try = TRUE is used as an argument, the function does not
start an optimization, but just calculates the warping for the given
warp function (init.coef); if smooth.param is larger
than zero for the RMS criterion, the RMS of the smoothed patterns is
calculated. The WCC criterion uses trwidth.res as the triangle
width in this case.
Five situations can be distinguished:
One sample and one reference: this obviously leads to one warping
function regardless of the setting of warp.type.
Several samples, all warped to the same single reference, each with
its own warping function: this is the default behaviour
(warp.type = "individual")
Several samples, warped to an equal number of references
(pair-wise), with their own warping functions: this is the default
behaviour (warp.type = "individual")
Several samples, warped to one reference, with one warping function
(warp.type = "global")
Several samples, warped to an equal number of references
(pair-wise), with one warping function
(warp.type = "global")
Value
A list of class "ptw" containing:
reference
the reference(s) used as input
sample
the sample(s) used as input
warped.sample
the warped sample
warp.coef
the warping coefficients
warp.fun
the warped indices
crit.value
the value of the chosen criterion, either "WCC" or "RMS"
optim.crit
the chosen criterion, either "WCC" or "RMS"
warp.type
the chosen type of warping, either "individual" or
"global"