R/pds.R

Defines functions pls_coef pds

Documented in pds

#' @title Piecewise Direct Standardization
#'
#' @author Christian L. Goueguel
#'
#' @description
#' The `pds` function performs Piecewise Direct Standardization (PDS), a method
#' proposed by Wang *et al.* (1991) to transfer spectra from
#' one instrument to another. Optionally, the local models can be blended with
#' a global PLSR model (direct standardization), which can lead to better
#' transfer performance when the instrumental differences are not purely local.
#'
#' @details
#' For each wavelength \eqn{j} of the primary (reference) instrument, a PLSR model
#' is fitted between the response of the primary instrument at \eqn{j} and the
#' responses of the secondary instrument in the window \eqn{[j - win, j + win]}
#' (truncated at the edges of the spectrum). The regression coefficients are
#' stored in a banded transfer matrix \eqn{\textbf{F}}, and the intercepts in a
#' vector \eqn{\textbf{b}_0}. Spectra measured on the secondary instrument are then
#' standardized as
#' \deqn{\textbf{X}_{2,std} = \textbf{X}_2 \textbf{F} + \textbf{1}\textbf{b}_0^T}
#'
#' When `alpha > 0`, a global PLSR model mapping the whole secondary spectrum to
#' the whole primary spectrum is also fitted, and the transfer matrix and
#' intercept are \eqn{(1 - \alpha)} times the local ones plus \eqn{\alpha}
#' times the global ones.
#'
#' @param x1 A matrix or data frame containing spectra acquired with the
#'   primary (reference) instrument.
#' @param x2 A matrix or data frame containing spectra of the same samples
#'   acquired with the secondary instrument, to be standardized.
#' @param win An integer specifying the half size of the moving window used for PLSR. A larger value may improve the transfer but will increase computational time. Default is 5.
#' @param ncomp An integer specifying the number of components to be used in PLSR. Typically, a small number (e.g., 2-5) is sufficient. Default is 2.
#' @param alpha A numeric value between 0 and 1 specifying the weight for the global PLSR model. A value of 0 (default) corresponds to the original PDS method, while a value of 1 corresponds to using only the global PLSR model.
#'
#' @return An object of class `specproc_transfer`, a list with
#'   \item{`transfer_matrix`}{The \eqn{p \times p} transfer matrix \eqn{\textbf{F}}.}
#'   \item{`intercept`}{A vector of length \eqn{p} containing the intercepts.}
#'   and the settings of the transfer. Use
#'   [predict()][predict.specproc_transfer] to transfer secondary spectra.
#'
#' @references
#'   - Wang, Y., Veltkamp, D.J., Kowalski, B.R., (1991).
#'     Multivariate instrument standardization.
#'     Analytical Chemistry, 63(23):2750-2756.
#'   - Bouveresse, E., Massart, D.L., (1996).
#'     Improvement of the piecewise direct standardization procedure for the
#'     transfer of NIR spectra for multivariate calibration.
#'     Chemometrics and Intelligent Laboratory Systems, (32)2:201-213.
#'
#' @seealso [ds()], [sst()], [slope_bias()], [predict.specproc_transfer()]
#' @export pds
#'
#' @examples
#' data(forageLIBS)
#' wl <- suppressWarnings(as.numeric(names(forageLIBS)))
#' spectra <- forageLIBS[which(wl > 760 & wl < 780)]  # the K I resonance lines
#' # a second instrument, with a shifted and less sensitive response
#' x1 <- as.matrix(spectra[1:30, ])
#' x2 <- 0.8 * cbind(x1[, -1], x1[, ncol(x1)]) + 50
#' res <- pds(x1, x2, win = 3, ncomp = 2)
#' # spectra of the second instrument transferred to the first one
#' transferred <- predict(res, x2)
#' max(abs(transferred - x1)) / max(x1)
pds <- function(x1, x2, win = 5, ncomp = 2, alpha = 0) {
  x1 <- as_numeric_matrix(x1, "x1")
  x2 <- as_numeric_matrix(x2, "x2")
  if (ncol(x1) != ncol(x2)) {
    stop("Input matrices x1 and x2 must have the same number of columns.")
  }
  if (nrow(x1) != nrow(x2)) {
    stop("Input matrices x1 and x2 must have the same number of rows (same samples).")
  }
  if (anyNA(x1) || anyNA(x2)) {
    stop("'x1' and 'x2' cannot contain missing values.")
  }
  check_count(win, "win", lower = 0)
  check_count(ncomp, "ncomp")
  check_number(alpha, "alpha", lower = 0, upper = 1)

  n <- nrow(x1)
  p <- ncol(x1)
  if (n < 3) {
    stop("At least 3 transfer samples are required.")
  }

  mu1 <- colMeans(x1)
  mu2 <- colMeans(x2)
  x1c <- sweep(x1, 2, mu1)
  x2c <- sweep(x2, 2, mu2)

  transfer <- matrix(0, p, p)
  if (alpha < 1) {
    for (j in seq_len(p)) {
      idx <- max(1, j - win):min(p, j + win)
      transfer[idx, j] <- pls_coef(x2c[, idx, drop = FALSE], x1c[, j], ncomp)
    }
  }
  if (alpha > 0) {
    global <- pls_coef(x2c, x1c, ncomp)
    transfer <- (1 - alpha) * transfer + alpha * global
  }
  intercept <- mu1 - drop(mu2 %*% transfer)

  dimnames(transfer) <- list(colnames(x2), colnames(x1))
  names(intercept) <- colnames(x1)
  structure(list(transfer_matrix = transfer, intercept = intercept, method = "pds", win = win,
                 ncomp = ncomp, alpha = alpha, n = n),
            class = "specproc_transfer")
}

# Regression coefficients of a PLS model fitted on centered data.
pls_coef <- function(x, y, ncomp) {
  y <- as.matrix(y)
  if (all(abs(y) < .Machine$double.eps) || all(abs(x) < .Machine$double.eps)) {
    return(matrix(0, ncol(x), ncol(y)))
  }
  k <- min(ncomp, ncol(x), nrow(x) - 1, qr(x)$rank)
  fit <- pls::simpls.fit(x, y, ncomp = k, center = FALSE)
  coef <- fit$coefficients[, , k]
  matrix(coef, ncol(x), ncol(y))
}

Try the specProc package in your browser

Any scripts or data that you put into this service are public.

specProc documentation built on Nov. 20, 2026, 5:11 p.m.