- Took loq and lod apart again. lod is now an implemantation of Massart, loq is

  an own variant of DIN 32645 (relative error on x axis).
- Partly make functions work on models where x and y are named different
  from "x" and "y" (loq to be done).




git-svn-id: http://kriemhild.uft.uni-bremen.de/svn/chemCal@11 5fad18fb-23f0-0310-ab10-e59a3bee62b4

3 files changed, 110 insertions, 37 deletions

diff --git a/man/inverse.predict.Rd b/man/inverse.predict.Rd
index 8c2be9c..5be0250 100644
--- a/man/inverse.predict.Rd
+++ b/man/inverse.predict.Rd
@@ -57,14 +57,14 @@
   p. 200
 }
 \examples{
-data(massart97ex3)
-attach(massart97ex3)
-yx <- split(y,factor(x))
-s <- round(sapply(yx,sd),digits=2)
-w <- round(1/(s^2),digits=3)
-weights <- w[factor(x)]
-m <- lm(y ~ x,w=weights)
+  data(massart97ex3)
+  attach(massart97ex3)
+  yx <- split(y,factor(x))
+  s <- round(sapply(yx,sd),digits=2)
+  w <- round(1/(s^2),digits=3)
+  weights <- w[factor(x)]
+  m <- lm(y ~ x,w=weights)
 
-inverse.predict(m,15,ws = 1.67)
+  inverse.predict(m,15,ws = 1.67)
 }
 \keyword{manip}
diff --git a/man/lod.Rd b/man/lod.Rd
index e6ce345..15f9603 100644
--- a/man/lod.Rd
+++ b/man/lod.Rd
@@ -3,14 +3,9 @@
 \alias{lod.lm}
 \alias{lod.rlm}
 \alias{lod.default}
-\alias{loq}
-\alias{loq.lm}
-\alias{loq.rlm}
-\alias{loq.default}
-\title{Estimate a limit of detection (LOD) or quantification (LOQ)}
+\title{Estimate a limit of detection (LOD)}
 \usage{
-  lod(object, \dots, alpha = 0.05, k = 1, n = 1, w = "auto")
-  loq(object, \dots, alpha = 0.05, k = 3, n = 1, w = "auto")
+  lod(object, \dots, alpha = 0.05, beta = 0.05)
 }
 \arguments{
   \item{object}{
@@ -19,40 +14,42 @@
     with model formula \code{y ~ x} or \code{y ~ x - 1}, 
     optionally from a weighted regression.
   }
-  \item{alpha}{
-    The error tolerance for the prediction of x values in the calculation.
-  }
   \item{\dots}{
     Placeholder for further arguments that might be needed by 
     future implementations.
   }
-  \item{k}{ 
-    The inverse of the maximum relative error tolerated at the
-    desired LOD/LOQ.
-  }
-  \item{n}{
-    The number of replicate measurements for which the LOD/LOQ should be
-    specified.
+  \item{alpha}{
+    The error tolerance for the decision limit (critical value).
   }
-  \item{w}{
-    The weight that should be attributed to the LOD/LOQ. Defaults
-    to one for unweighted regression, and to the mean of the weights
-    for weighted regression. See \code{\link{massart97ex3}} for 
-    an example how to take advantage of knowledge about the variance function.
+  \item{beta}{
+    The error tolerance beta for the detection limit.
   }
 }
 \value{
-  The estimated limit of detection for a model used for calibration.
-}
+  A list containig the corresponding x and y values of the estimated limit of
+  detection of a model used for calibration.  }
 \description{
-  A useful operationalisation of a lower limit L of a measurement method is
-  simply the solution of the equation
-    \deqn{L = k c(L)}{L = k * c(L)}
-  where c(L) is half of the lenght of the confidence interval at the limit L.
+  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).
+}
+\references{
+  J. Inczedy, T. Lengyel, and A.M. Ure (2002) International Union of Pure and
+  Applied Chemistry Compendium of Analytical Nomenclature: Definitive Rules.
+  Web edition.
 }
 \examples{
   data(din32645)
   m <- lm(y ~ x, data = din32645)
-  lod(m)
+  # The decision limit (critical value) is obtained by using beta = 0.5:
+  lod(m, alpha = 0.01, beta = 0.5) # approx. Nachweisgrenze in Dintest 2002
+  lod(m, alpha = 0.01, beta = 0.01) 
+  # In the latter case (Erfassungsgrenze), we get a slight deviation from 
+  # Dintest 2002 test data.
 }
 \keyword{manip}
diff --git a/man/loq.Rd b/man/loq.Rd
new file mode 100644
index 0000000..1030399
--- /dev/null
+++ b/man/loq.Rd
@@ -0,0 +1,76 @@
+\name{loq}
+\alias{loq}
+\alias{loq.lm}
+\alias{loq.rlm}
+\alias{loq.default}
+\title{Estimate a limit of quantification (LOQ)}
+\usage{
+  loq(object, \dots, alpha = 0.05, k = 3, n = 1, w = "auto")
+}
+\arguments{
+  \item{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.
+  }
+  \item{alpha}{
+    The error tolerance for the prediction of x values in the calculation.
+  }
+  \item{\dots}{
+    Placeholder for further arguments that might be needed by 
+    future implementations.
+  }
+  \item{k}{ 
+    The inverse of the maximum relative error tolerated at the
+    desired LOQ.
+  }
+  \item{n}{
+    The number of replicate measurements for which the LOQ should be
+    specified.
+  }
+  \item{w}{
+    The weight that should be attributed to the LOQ. Defaults
+    to one for unweighted regression, and to the mean of the weights
+    for weighted regression. See \code{\link{massart97ex3}} for 
+    an example how to take advantage of knowledge about the 
+    variance function.
+  }
+}
+\value{
+  The estimated limit of quantification for a model used for calibration.
+}
+\description{
+  A useful operationalisation of a limit of quantification is simply the
+  solution of the equation
+    \deqn{L = k c(L)}{L = k * c(L)}
+  where c(L) is half of the length of the confidence interval at the limit L as
+  estimated by \code{\link{inverse.predict}}. By virtue of this formula, the 
+  limit of detection is the x value, where the relative error
+  of the quantification with the given calibration model is 1/k.
+}
+\examples{
+  data(massart97ex3)
+  attach(massart97ex3)
+  m0 <- lm(y ~ x)
+  loq(m0)
+
+  # Now we use a weighted regression
+  yx <- split(y,factor(x))
+  s <- round(sapply(yx,sd),digits=2)
+  w <- round(1/(s^2),digits=3)
+  weights <- w[factor(x)]
+  mw <- lm(y ~ x,w=weights)
+  loq(mw)
+
+  # In order to define the weight at the loq, we can use
+  # the variance function 1/y for the model
+  mwy <- lm(y ~ x, w = 1/y)
+
+  # Let's do this with one iteration only
+  loq(mwy, w = 1 / predict(mwy,list(x = loq(mwy))))
+
+  # We can get better by doing replicate measurements
+  loq(mwy, n = 3, w = 1 / predict(mwy,list(x = loq(mwy))))
+}
+\keyword{manip}