R/epo.R

Defines functions epo_project epo

Documented in epo

#' @title External Parameter Orthogonalization
#'
#' @author Christian L. Goueguel
#'
#' @description
#' This function implements the External Parameter Orthogonalization (EPO)
#' algorithm as proposed by Roger *et al.* (2003). The EPO algorithm aims to
#' remove interferences or clutter present in the spectral matrix, effectively
#' separating the signal of interest from unwanted perturbations.
#'
#' @details
#' The EPO algorithm works by detecting the dominant directions (right singular
#' vectors) of a clutter matrix \eqn{\textbf{D}} that describe the external
#' variations, e.g. the differences between spectra of the same samples measured
#' under different temperatures or moisture levels. It then projects the spectral
#' matrix onto the subspace orthogonal to these variations, effectively removing
#' the unwanted perturbations and extracting the signal of interest.
#'
#' Let \eqn{\textbf{X}} be the spectral matrix. The EPO algorithm aims to split \eqn{\textbf{X}} into:
#'
#' \deqn{\textbf{X} = \textbf{XP} + \textbf{XQ} + \textbf{R}}
#'
#' where \eqn{\textbf{P}} and \eqn{\textbf{Q}} are, respectively, the projection
#' matrices of \eqn{\textbf{X}} onto the useful and perturbation (clutter) subspaces.
#' \eqn{\textbf{R}} is the residual matrix. With \eqn{\textbf{V}} the first `ncomp`
#' right singular vectors of \eqn{\textbf{D}}, \eqn{\textbf{Q} = \textbf{VV}^T} and
#' the corrected matrix is \eqn{\textbf{X} - \textbf{XVV}^T}.
#'
#' The singular value decomposition is computed in C++ (Eigen), and the
#' \eqn{p \times p} projection matrix is never formed explicitly.
#'
#' @param x A numeric matrix, data frame or tibble.
#' @param ncomp An integer specifying the number of singular vectors to orthogonalize against. Default is 2.
#' @param clutter An optional numeric matrix or data frame, with the same number of
#'   columns as `x`, describing the external (clutter) variation. If `NULL`
#'   (default), the clutter directions are estimated from `x` itself, i.e. the
#'   `ncomp` dominant directions of `x` are removed.
#'
#' @return An object of class `specproc_epo` (a list), which [predict()][predict.specproc_filter] applies to new spectra, with four components:
#' \itemize{
#'   \item \code{correction}: The orthogonalized matrix, representing the signal of interest.
#'   \item \code{clutter}: The clutter part of `x`, \eqn{\textbf{XVV}^T}.
#'   \item \code{loadings}: The singular vectors \eqn{\textbf{V}} used for the orthogonalization.
#'   \item \code{singular_values}: The corresponding singular values of the clutter matrix.
#' }
#'
#' @references
#'  - Roger, J.-M., Chauchard, F., Bellon-Maurel, V. (2003).
#'    EPO-PLS external parameter orthogonalization of PLS application to temperature-independent measurement of sugar content of intact fruits.
#'    Chemometrics and Intelligent Laboratory Systems, 66(2):191-204.
#'
#' @seealso [predict.specproc_filter()] to correct new spectra with the fitted filter, and
#'   [step_epo()] to use it in a tidymodels recipe.
#'
#' @export epo
#'
#' @examples
#' data(forageLIBS)
#' spectra <- forageLIBS[-(1:14)]  # the spectral channels
#' # the three samples measured twice
#' twice <- forageLIBS$Sample[duplicated(forageLIBS$Sample)]
#' first <- match(twice, forageLIBS$Sample)
#' second <- vapply(twice, function(s) max(which(forageLIBS$Sample == s)), integer(1))
#' # their differences describe the variation between repeated measurements
#' clutter <- as.matrix(spectra[second, ]) - as.matrix(spectra[first, ])
#' res <- epo(spectra, ncomp = 1, clutter = clutter)
#' dim(res$correction)
epo <- function(x, ncomp = 2, clutter = NULL) {
  if (missing(x)) {
    stop("Missing 'x' argument.")
  }
  x <- as_numeric_matrix(x, "x")
  if (nrow(x) < 2 || ncol(x) < 2) {
    stop("The dimensions of the input data must be at least 2 x 2")
  }
  d <- if (is.null(clutter)) x else as_numeric_matrix(clutter, "clutter")
  if (ncol(d) != ncol(x)) {
    stop("'clutter' must have the same number of columns as 'x'.")
  }
  if (anyNA(x) || anyNA(d)) {
    stop("'x' and 'clutter' cannot contain missing values.")
  }
  if (!is.numeric(ncomp) || length(ncomp) != 1 || ncomp %% 1 != 0 || ncomp <= 0) {
    stop("'ncomp' must be a positive integer greater than 0.")
  }
  ncomp <- min(ncomp, dim(d))

  result <- epo_project(x, d, ncomp)
  comp <- paste0("comp", seq_len(ncomp))

  res <- list(
    correction = as_tbl(result$correction, colnames(x)),
    clutter = as_tbl(result$clutter, colnames(x)),
    loadings = as_tbl(result$loadings, comp),
    singular_values = drop(result$singular_values)
  )
  new_filter(res, "specproc_epo", x)
}

# Projection of x on the orthogonal complement of the `ncomp` dominant right
# singular vectors P of the clutter d: x - (x P) P'. The p x p projection
# matrix is never formed.
epo_project <- function(x, d, ncomp) {
  s <- svd(d, nu = 0, nv = ncomp)
  P <- s$v[, seq_len(ncomp), drop = FALSE]
  clutter <- (x %*% P) %*% t(P)
  list(correction = x - clutter, clutter = clutter, loadings = P,
       singular_values = s$d[seq_len(ncomp)])
}

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.