R/hats_alignSpectra2D.R
hats_alignSpectra2D.RdAlign the spectra in a Spectra2D object using an implementation
of the HATS algorithm described by Robinette et al.. Currently, only
global, not local, alignment is carried out.
hats_alignSpectra2D(
spectra,
maxF2 = NULL,
maxF1 = NULL,
dist_method = "cosine",
minimize = FALSE,
thres = 0.99,
no.it = 20L,
restarts = 2L,
method = "MBO",
fill = "noise",
plot = FALSE,
debug = 1
)An object of S3 class Spectra2D.
Integer. The most extreme positive F2step to allow during the
alignment process (units are data points). Search for the optimal alignment will
cover the region -maxF2 ... maxF2 and -maxF1
... maxF1. Defaults to about 10% of the number of points.
Integer. As for maxF2, but for F1.
Character. The distance method to use in the objective function.
See rowDist for options.
Logical. Is the goal to minimize the objective function? If so, use TRUE.
Numeric. Prior to launching the optimization, the objective function is evaluated
for no shift in case this is actually the best alignment (saving a great deal of time).
If this initial check exceeds the value of thres (when minimize = FALSE),
or is below thres when minimize = TRUE, no optimization is performed
and the unshifted spectra are returned.
Integer. The maximum number of iterations in the optimization.
Integer. The maximum number of independent rounds of optimization.
Character. Currently only method = "MBO" is available which uses
the HATS algorithm plus model based optimization (aka Bayesian optimization) method to
align the spectra. Use plot = TRUE to see this in action.
Aligning spectra requires that at least some spectra be shifted left/right and up/down. When a spectrum is shifted, spaces are opened that must be filled with something:
If fill = "zeros" the spaces are filled with zeros.
If fill = "noise" the spaces are filled with an estimate of the noise from the
original spectrum.
Logical. Shall a plot of the alignment progress be made? The plot is useful for diagnostic purposes. Every step of the alignment has a corresponding plot so you should probably direct the output to a pdf file.
Integer.
Values >= 1 give messages about alignment progress in black text.
Values >= 2 print the merge matrix from the hclust object, if plot
is also TRUE. This is the guide tree.
For method = "MBO" values less than 2 suppress some messages and warnings from
the underlying functions. If the alignment doesn't work well, set debug = 2.
Setting plot = TRUE also gives a view of alignment diagnostics.
An object of S3 class Spectra2D.
I suggest that you plot your possibly mis-aligned spectra first, zooming in on a small region where
alignment might be an issue, and get an idea of the size of the alignment problem. This will help
you choose good values for maxF1 and maxF2 which will speed up the search.
The algorithm uses random numbers to initialize the search, so set the seed for reproducible results. Different seeds may give different results; you may find it useful to experiment a bit and see how the alignment turns out.
Be sure that your choice of thres, minimize and dist_method are self-consistent.
Some dist_method choices are bounded, others unbounded, and some should be minimized, others maximized.
You should use sampleDist to visualize the distances ahead of time. The method
chosen should return a wide numerical range between samples or it won't give a good alignment result.
Roughly follows the algorithm described in Robinette et al. 2011 Anal. Chem. vol. 83, 1649-1657 (2011) dx.doi.org/10.1021/ac102724x
if (FALSE) { # \dontrun{
set.seed(123)
library("ggally") # for diagnostic plots
data(MUD2)
sumSpectra(MUD2)
mylvls <- seq(3, 30, 3)
# Plot before alignment
plotSpectra2D(MUD2,
which = c(2, 3, 5, 6), showGrid = TRUE,
lvls = LofL(mylvls, 4),
cols = LofC(c("black", "red", "blue", "green"), 4, 10, 2)
)
# Carry out alignment
# You might want to direct the diagnostic output here to a pdf file
# This alignment takes about 90 seconds including the plotting overhead
MUD2a <- hats_alignSpectra2D(MUD2, method = "MBO", debug = 1, plot = TRUE)
# Plot after alignment
plotSpectra2D(MUD2a,
which = c(2, 3, 5, 6), showGrid = TRUE,
lvls = LofL(mylvls, 4),
cols = LofC(c("black", "red", "blue", "green"), 4, 10, 2)
)
} # }