1 files changed, 73 insertions, 4 deletions
diff --git a/R/inverse.predict.lm.R b/R/inverse.predict.lm.R
index 77d548f..031f9d4 100644
--- a/R/inverse.predict.lm.R
+++ b/R/inverse.predict.lm.R
@@ -1,19 +1,87 @@
-# This is an implementation of Equation (8.28) in the Handbook of Chemometrics
-# and Qualimetrics, Part A, Massart et al (1997), page 200, validated with
-# Example 8 on the same page, extended as specified in the package vignette
-
+#' Predict x from y for a linear calibration
+#' 
+#' This function predicts x values using a univariate linear model that has
+#' been generated for the purpose of calibrating a measurement method.
+#' Prediction intervals are given at the specified confidence level.  The
+#' calculation method was taken from Massart et al. (1997). In particular,
+#' Equations 8.26 and 8.28 were combined in order to yield a general treatment
+#' of inverse prediction for univariate linear models, taking into account
+#' weights that have been used to create the linear model, and at the same time
+#' providing the possibility to specify a precision in sample measurements
+#' differing from the precision in standard samples used for the calibration.
+#' This is elaborated in the package vignette.
+#'
+#' This is an implementation of Equation (8.28) in the Handbook of Chemometrics
+#' and Qualimetrics, Part A, Massart et al (1997), page 200, validated with
+#' Example 8 on the same page, extended as specified in the package vignette
+#' 
+#' @aliases inverse.predict inverse.predict.lm inverse.predict.rlm
+#' inverse.predict.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}.
+#' @param newdata A vector of observed y values for one sample.
+#' @param \dots Placeholder for further arguments that might be needed by
+#' future implementations.
+#' @param ws The weight attributed to the sample. This argument is obligatory
+#' if \code{object} has weights.
+#' @param alpha The error tolerance level for the confidence interval to be
+#' reported.
+#' @param var.s The estimated variance of the sample measurements. The default
+#' is to take the residual standard error from the calibration and to adjust it
+#' using \code{ws}, if applicable. This means that \code{var.s} overrides
+#' \code{ws}.
+#' @return A list containing the predicted x value, its standard error and a
+#' confidence interval.
+#' @note The function was validated with examples 7 and 8 from Massart et al.
+#' (1997).  Note that the behaviour of inverse.predict changed with chemCal
+#' version 0.2.1. Confidence intervals for x values obtained from calibrations
+#' with replicate measurements did not take the variation about the means into
+#' account.  Please refer to the vignette for details.
+#' @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, p. 200
+#' @importFrom stats optimize predict qt
+#' @examples
+#' 
+#' # This is example 7 from Chapter 8 in Massart et al. (1997)
+#' m <- lm(y ~ x, data = massart97ex1)
+#' inverse.predict(m, 15)        #  6.1 +- 4.9
+#' inverse.predict(m, 90)        # 43.9 +- 4.9
+#' inverse.predict(m, rep(90,5)) # 43.9 +- 3.2
+#' 
+#' # For reproducing the results for replicate standard measurements in example 8,
+#' # we need to do the calibration on the means when using chemCal > 0.2
+#' weights <- with(massart97ex3, {
+#'   yx <- split(y, x)
+#'   ybar <- sapply(yx, mean)
+#'   s <- round(sapply(yx, sd), digits = 2)
+#'   w <- round(1 / (s^2), digits = 3)
+#' })
+#' 
+#' massart97ex3.means <- aggregate(y ~ x, massart97ex3, mean)
+#' 
+#' m3.means <- lm(y ~ x, w = weights, data = massart97ex3.means)
+#' 
+#' inverse.predict(m3.means, 15, ws = 1.67)  # 5.9 +- 2.5
+#' inverse.predict(m3.means, 90, ws = 0.145) # 44.1 +- 7.9
+#' 
+#' 
+#' @export
 inverse.predict <- function(object, newdata, ...,
   ws = "auto", alpha = 0.05, var.s = "auto")
 {
   UseMethod("inverse.predict")
 }
 
+#' @export
 inverse.predict.default <- function(object, newdata, ...,
   ws = "auto", alpha = 0.05, var.s = "auto")
 {
   stop("Inverse prediction only implemented for univariate lm objects.")
 }
 
+#' @export
 inverse.predict.lm <- function(object, newdata, ...,
   ws = "auto", alpha = 0.05, var.s = "auto")
 {
@@ -31,6 +99,7 @@ inverse.predict.lm <- function(object, newdata, ...,
     ws = ws, alpha = alpha, var.s = var.s, w = w, xname = xname, yname = yname)
 }
 
+#' @export
 inverse.predict.rlm <- function(object, newdata, ...,
   ws = "auto", alpha = 0.05, var.s = "auto")
 {