Get rid of the branched svn layout I never used

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

8 files changed, 453 insertions, 0 deletions

diff --git a/man/calplot.lm.Rd b/man/calplot.lm.Rd
new file mode 100644
index 0000000..b60a032
--- /dev/null
+++ b/man/calplot.lm.Rd
@@ -0,0 +1,69 @@
+\name{calplot}
+\alias{calplot}
+\alias{calplot.default}
+\alias{calplot.lm}
+\title{Plot calibration graphs from univariate linear models}
+\description{
+	Produce graphics of calibration data, the fitted model as well
+  as confidence, and, for unweighted regression, prediction bands. 
+}
+\usage{
+  calplot(object, xlim = c("auto", "auto"), ylim = c("auto", "auto"),
+    xlab = "Concentration", ylab = "Response", alpha=0.05, varfunc = NULL)
+}
+\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}.
+  }
+  \item{xlim}{
+    The limits of the plot on the x axis.
+  }
+  \item{ylim}{
+    The limits of the plot on the y axis.
+  }
+  \item{xlab}{
+    The label of the x axis.
+  }
+  \item{ylab}{
+    The label of the y axis.
+  }
+  \item{alpha}{
+    The error tolerance level for the confidence and prediction bands. Note that this 
+    includes both tails of the Gaussian distribution, unlike the alpha and beta parameters
+    used in \code{\link{lod}} (see note below).
+  }
+  \item{varfunc}{
+    The variance function for generating the weights in the model.
+    Currently, this argument is ignored (see note below).
+  }
+}
+\value{
+  A plot of the calibration data, of your fitted model as well as lines showing
+  the confidence limits. Prediction limits are only shown for models from
+  unweighted regression.
+} 
+\note{
+  Prediction bands for models from weighted linear regression require weights
+  for the data, for which responses should be predicted. Prediction intervals
+  using weights e.g. from a variance function are currently not supported by
+  the internally used function \code{\link{predict.lm}}, therefore,
+  \code{calplot} does not draw prediction bands for such models.
+  
+  It is possible to compare the \code{\link{calplot}} prediction bands with the
+  \code{\link{lod}} values if the \code{lod()} alpha and beta parameters are
+  half the value of the \code{calplot()} alpha parameter.
+  
+}
+\examples{
+data(massart97ex3)
+m <- lm(y ~ x, data = massart97ex3)
+calplot(m)
+}
+\author{
+  Johannes Ranke 
+  \email{jranke@uni-bremen.de} 
+  \url{http://www.uft.uni-bremen.de/chemie/ranke}
+}
+\keyword{regression}
diff --git a/man/chemCal-package.Rd b/man/chemCal-package.Rd
new file mode 100644
index 0000000..fb09cb1
--- /dev/null
+++ b/man/chemCal-package.Rd
@@ -0,0 +1,16 @@
+\name{chemCal-package}
+\alias{chemCal-package}
+\docType{package}
+\title{
+  Calibration functions for analytical chemistry
+}
+\description{
+  See \url{../DESCRIPTION}
+}
+\details{
+  There is a package vignette located in \url{../doc/chemCal.pdf}.
+}
+\author{
+  Author and Maintainer: Johannes Ranke <jranke@uni-bremen.de>
+}
+\keyword{manip}
diff --git a/man/din32645.Rd b/man/din32645.Rd
new file mode 100644
index 0000000..cacbf07
--- /dev/null
+++ b/man/din32645.Rd
@@ -0,0 +1,61 @@
+\name{din32645}
+\docType{data}
+\alias{din32645}
+\title{Calibration data from DIN 32645}
+\description{
+  Sample dataset to test the package.
+}
+\usage{data(din32645)}
+\format{
+  A dataframe containing 10 rows of x and y values.
+}
+\examples{
+data(din32645)
+m <- lm(y ~ x, data = din32645)
+calplot(m)
+
+## Prediction of x with confidence interval
+(prediction <- inverse.predict(m, 3500, alpha = 0.01))
+
+# This should give 0.07434 according to test data from Dintest, which 
+# was collected from Procontrol 3.1 (isomehr GmbH) in this case
+round(prediction$Confidence,5)
+
+## Critical value:
+(crit <- lod(m, alpha = 0.01, beta = 0.5))
+
+# According to DIN 32645, we should get 0.07 for the critical value
+# (decision limit, "Nachweisgrenze")
+round(crit$x, 2)
+# and according to Dintest test data, we should get 0.0698 from
+round(crit$x, 4)
+
+## Limit of detection (smallest detectable value given alpha and beta)
+# In German, the smallest detectable value is the "Erfassungsgrenze", and we
+# should get 0.14 according to DIN, which we achieve by using the method 
+# described in it:
+lod.din <- lod(m, alpha = 0.01, beta = 0.01, method = "din")
+round(lod.din$x, 2)
+
+## Limit of quantification
+# This accords to the test data coming with the test data from Dintest again, 
+# except for the last digits of the value cited for Procontrol 3.1 (0.2121)
+(loq <- loq(m, alpha = 0.01))
+round(loq$x,4)
+
+# A similar value is obtained using the approximation 
+# LQ = 3.04 * LC (Currie 1999, p. 120)
+3.04 * lod(m,alpha = 0.01, beta = 0.5)$x
+}
+\references{
+  DIN 32645 (equivalent to ISO 11843), Beuth Verlag, Berlin, 1994
+
+  Dintest. Plugin for MS Excel for evaluations of calibration data. Written
+  by Georg Schmitt, University of Heidelberg. 
+  \url{http://www.rzuser.uni-heidelberg.de/~df6/download/dintest.htm}
+
+  Currie, L. A. (1997) Nomenclature in evaluation of analytical methods including
+  detection and quantification capabilities (IUPAC Recommendations 1995). 
+  Analytica Chimica Acta 391, 105 - 126.
+}
+\keyword{datasets}
diff --git a/man/inverse.predict.Rd b/man/inverse.predict.Rd
new file mode 100644
index 0000000..347d670
--- /dev/null
+++ b/man/inverse.predict.Rd
@@ -0,0 +1,69 @@
+\name{inverse.predict}
+\alias{inverse.predict}
+\alias{inverse.predict.lm}
+\alias{inverse.predict.rlm}
+\alias{inverse.predict.default}
+\title{Predict x from y for a linear calibration}
+\usage{inverse.predict(object, newdata, \dots,
+  ws, alpha=0.05, var.s = "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}.
+  }
+  \item{newdata}{ 
+    A vector of observed y values for one sample.
+  }
+  \item{\dots}{
+    Placeholder for further arguments that might be needed by 
+    future implementations.
+  }
+  \item{ws}{ 
+    The weight attributed to the sample. This argument is obligatory
+    if \code{object} has weights.
+  }
+  \item{alpha}{
+    The error tolerance level for the confidence interval to be reported.
+  }
+  \item{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}.
+  }
+}
+\value{
+  A list containing the predicted x value, its standard error and a
+  confidence interval.
+}
+\description{
+  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.
+}
+\note{
+  The function was validated with examples 7 and 8 from Massart et al. (1997).
+}
+\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
+}
+\examples{
+# This is example 7 from Chapter 8 in Massart et al. (1997)
+data(massart97ex1)
+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
+}
+\keyword{manip}
diff --git a/man/lod.Rd b/man/lod.Rd
new file mode 100644
index 0000000..04aac1f
--- /dev/null
+++ b/man/lod.Rd
@@ -0,0 +1,88 @@
+\name{lod}
+\alias{lod}
+\alias{lod.lm}
+\alias{lod.rlm}
+\alias{lod.default}
+\title{Estimate a limit of detection (LOD)}
+\usage{
+  lod(object, \dots, alpha = 0.05, beta = 0.05, method = "default", tol = "default")
+}
+\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{\dots}{
+    Placeholder for further arguments that might be needed by 
+    future implementations.
+  }
+  \item{alpha}{
+    The error tolerance for the decision limit (critical value).
+  }
+  \item{beta}{
+    The error tolerance beta for the detection limit.
+  }
+  \item{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.
+  }
+  \item{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.
+  }
+}
+\value{
+  A list containig the corresponding x and y values of the estimated limit of
+  detection of a model used for calibration.  
+}
+\description{
+  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).
+}
+\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.
+}
+\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.
+}
+\examples{
+data(din32645)
+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)
+}
+\seealso{
+  Examples for \code{\link{din32645}}  
+}
+\keyword{manip}
diff --git a/man/loq.Rd b/man/loq.Rd
new file mode 100644
index 0000000..082cf34
--- /dev/null
+++ b/man/loq.Rd
@@ -0,0 +1,82 @@
+\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.loq = "auto",
+    var.loq = "auto", tol = "default")
+}
+\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. If weights are specified
+    in the model, either \code{w.loq} or \code{var.loq} have to 
+    be specified.
+  }
+  \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.loq}{
+    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.
+  }
+  \item{var.loq}{
+    The approximate variance at the LOQ. The default value is 
+    calculated from the model.
+  }
+  \item{tol}{
+    The default tolerance for the LOQ 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.
+  }
+}
+\value{
+  The estimated limit of quantification for a model used for calibration.
+}
+\description{
+  The limit of quantification is the x value, where the relative error
+  of the quantification given the calibration model reaches a prespecified
+  value 1/k. Thus, it is 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
+  (DIN 32645, equivalent to ISO 11843). c(L) is internally estimated by
+  \code{\link{inverse.predict}}, and L is obtained by iteration. 
+}
+\note{
+  - IUPAC recommends to base the LOQ on the standard deviation of the signal
+    where x = 0. 
+  - The calculation of a LOQ based on weighted regression is non-standard
+    and therefore not tested. Feedback is welcome.
+}
+\examples{
+data(massart97ex3)
+attach(massart97ex3)
+m <- lm(y ~ x)
+loq(m)
+
+# We can get better by using replicate measurements
+loq(m, n = 3)
+}
+\seealso{
+  Examples for \code{\link{din32645}}  
+}
+\keyword{manip}
diff --git a/man/massart97ex1.Rd b/man/massart97ex1.Rd
new file mode 100644
index 0000000..44e1b85
--- /dev/null
+++ b/man/massart97ex1.Rd
@@ -0,0 +1,17 @@
+\name{massart97ex1}
+\docType{data}
+\alias{massart97ex1}
+\title{Calibration data from Massart et al. (1997), example 1}
+\description{
+  Sample dataset from p. 175 to test the package.
+}
+\usage{data(massart97ex1)}
+\format{
+  A dataframe containing 6 observations of x and y data.
+}
+\source{
+  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 8.
+}
+\keyword{datasets}
diff --git a/man/massart97ex3.Rd b/man/massart97ex3.Rd
new file mode 100644
index 0000000..efdcf02
--- /dev/null
+++ b/man/massart97ex3.Rd
@@ -0,0 +1,51 @@
+\name{massart97ex3}
+\docType{data}
+\alias{massart97ex3}
+\title{Calibration data from Massart et al. (1997), example 3}
+\description{
+  Sample dataset from p. 188 to test the package.
+}
+\usage{data(massart97ex3)}
+\format{
+  A dataframe containing 6 levels of x values with 5
+  observations of y for each level.
+}
+\examples{
+data(massart97ex3)
+attach(massart97ex3)
+yx <- split(y, x)
+ybar <- sapply(yx, mean)
+s <- round(sapply(yx, sd), digits = 2)
+w <- round(1 / (s^2), digits = 3)
+weights <- w[factor(x)]
+m <- lm(y ~ x, w = weights)
+calplot(m)
+
+# The following concords with the book p. 200
+inverse.predict(m, 15, ws = 1.67)  # 5.9 +- 2.5
+inverse.predict(m, 90, ws = 0.145) # 44.1 +- 7.9
+
+# The LOD is only calculated for models from unweighted regression
+# with this version of chemCal
+m0 <- lm(y ~ x) 
+lod(m0)
+
+# Limit of quantification from unweighted regression
+loq(m0)
+
+# For calculating the limit of quantification from a model from weighted
+# regression, we need to supply weights, internally used for inverse.predict
+# If we are not using a variance function, we can use the weight from
+# the above example as a first approximation (x = 15 is close to our
+# loq approx 14 from above).
+loq(m, w.loq = 1.67)
+# The weight for the loq should therefore be derived at x = 7.3 instead
+# of 15, but the graphical procedure of Massart (p. 201) to derive the 
+# variances on which the weights are based is quite inaccurate anyway. 
+}
+\source{
+  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 8.
+}
+\keyword{datasets}