R/lod.R

In chemCal: Calibration Functions for Analytical Chemistry

#' Estimate a limit of detection (LOD)
#' 
#' The decision limit (German: Nachweisgrenze) is defined as the signal or
#' analyte concentration that is significantly different from the blank signal
#' with a first order error alpha (one-sided significance test).  The detection
#' limit, or more precise, the minimum detectable value (German:
#' Erfassungsgrenze), is then defined as the signal or analyte concentration
#' where the probability that the signal is not detected although the analyte
#' is present (type II or false negative error), is beta (also a one-sided
#' significance test).
#' 
#' @aliases lod lod.lm lod.rlm lod.default
#' @param object A univariate model object of class \code{\link{lm}} or
#' \code{\link[MASS:rlm]{rlm}} with model formula \code{y ~ x} or \code{y ~ x -
#' 1}, optionally from a weighted regression.
#' @param \dots Placeholder for further arguments that might be needed by
#' future implementations.
#' @param alpha The error tolerance for the decision limit (critical value).
#' @param beta The error tolerance beta for the detection limit.
#' @param method The \dQuote{default} method uses a prediction interval at the
#' LOD for the estimation of the LOD, which obviously requires iteration. This
#' is described for example in Massart, p. 432 ff.  The \dQuote{din} method
#' uses the prediction interval at x = 0 as an approximation.
#' @param tol When the \dQuote{default} method is used, the default tolerance
#' for the LOD on the x scale is the value of the smallest non-zero standard
#' divided by 1000. Can be set to a numeric value to override this.
#' @return A list containig the corresponding x and y values of the estimated
#' limit of detection of a model used for calibration.
#' @note 
#' * The default values for alpha and beta are the ones recommended by IUPAC.
#' * The estimation of the LOD in terms of the analyte amount/concentration xD
#' from the LOD in the signal domain SD is done by simply inverting the
#' calibration function (i.e. assuming a known calibration function).
#' * The calculation of a LOD from weighted calibration models requires a
#' weights argument for the internally used \code{\link{predict.lm}}
#' function, which is currently not supported in R.
#' @seealso Examples for \code{\link{din32645}}
#' @references Massart, L.M, Vandenginste, B.G.M., Buydens, L.M.C., De Jong,
#' S., Lewi, P.J., Smeyers-Verbeke, J. (1997) Handbook of Chemometrics and
#' Qualimetrics: Part A, Chapter 13.7.8
#' 
#' J. Inczedy, T. Lengyel, and A.M. Ure (2002) International Union of Pure and
#' Applied Chemistry Compendium of Analytical Nomenclature: Definitive Rules.
#' Web edition.
#' 
#' Currie, L. A. (1997) Nomenclature in evaluation of analytical methods
#' including detection and quantification capabilities (IUPAC Recommendations
#' 1995).  Analytica Chimica Acta 391, 105 - 126.
#' @importFrom stats optimize predict
#' @examples
#' 
#' m <- lm(y ~ x, data = din32645)
#' lod(m) 
#' 
#' # The critical value (decision limit, German Nachweisgrenze) can be obtained
#' # by using beta = 0.5:
#' lod(m, alpha = 0.01, beta = 0.5)
#' 
#' @export
lod <- function(object, ..., alpha = 0.05, beta = 0.05, method = "default", tol = "default")
{
  UseMethod("lod")
}

#' @export
lod.default <- function(object, ..., alpha = 0.05, beta = 0.05, method = "default", tol = "default")
{
  stop("lod is only implemented for univariate lm objects.")
}

#' @export
lod.lm <- function(object, ..., alpha = 0.05, beta = 0.05, method = "default", tol = "default")
{
  if (length(object$weights) > 0) {
    stop(paste(
      "\nThe detemination of a lod from calibration models obtained by",
      "weighted linear regression requires confidence intervals for",
      "predicted y values taking into account weights for the x values",
      "from which the predictions are to be generated.",
      "This is not supported by the internally used predict.lm method.",
      sep = "\n"
    ))
  }
  xname <- names(object$model)[[2]]
  xvalues <- object$model[[2]]
  yname <- names(object$model)[[1]]
  newdata <- data.frame(0)
  names(newdata) <- xname
  y0 <- predict(object, newdata, interval = "prediction", 
    level = 1 - 2 * alpha)
  yc <- y0[[1,"upr"]]
  if (method == "din") {
    y0.d <- predict(object, newdata, interval = "prediction",
      level = 1 - 2 * beta)
    deltay <- y0.d[[1, "upr"]] - y0.d[[1, "fit"]]
    lod.y <- yc + deltay 
    lod.x <- inverse.predict(object, lod.y)$Prediction
  } else {
    f <- function(x) {
      newdata <- data.frame(x)
      names(newdata) <- xname
      pi.y <- predict(object, newdata, interval = "prediction",
        level = 1 - 2 * beta)
      yd <- pi.y[[1,"lwr"]]
      (yd - yc)^2
    }
    if (tol == "default") tol = min(xvalues[xvalues !=0]) / 1000
    lod.x <- optimize(f, interval = c(0, max(xvalues) * 10), tol = tol)$minimum
    newdata <- data.frame(x = lod.x)
    names(newdata) <- xname
    lod.y <-  predict(object, newdata)
    names(lod.y) <- NULL
  }
  lod <- list(lod.x, lod.y)
  names(lod) <- c(xname, yname)
  return(lod)
}