Align the Spectra in a Spectra2D Object using the HATS algorithm.

Align 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
)

Arguments

spectra	An object of S3 class `Spectra2D`.
maxF2	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.
maxF1	Integer. As for `maxF2`, but for F1.
dist_method	Character. The distance method to use in the objective function. See `rowDist` for options.
minimize	Logical. Is the goal to minimize the objective function? If so, use `TRUE`.
thres	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.
no.it	Integer. The maximum number of iterations in the optimization.
restarts	Integer. The maximum number of independent rounds of optimization.
method	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.
fill	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.
plot	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.
debug	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.

Value

An object of S3 class Spectra2D.

Advice

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.

References

Roughly follows the algorithm described in Robinette et al. 2011 Anal. Chem. vol. 83, 1649-1657 (2011) dx.doi.org/10.1021/ac102724x

Author

Bryan A. Hanson, DePauw University.

Examples

if (FALSE) {
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)
)
}