From d8d6012e98fb4c7f158bcc7c173407c2b5f3e42e Mon Sep 17 00:00:00 2001 From: ranke Date: Sat, 22 Aug 2015 09:03:10 +0000 Subject: 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 --- man/calplot.lm.Rd | 69 +++++++++++++++++++++++++++++++++++++++ man/chemCal-package.Rd | 16 +++++++++ man/din32645.Rd | 61 ++++++++++++++++++++++++++++++++++ man/inverse.predict.Rd | 69 +++++++++++++++++++++++++++++++++++++++ man/lod.Rd | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++ man/loq.Rd | 82 ++++++++++++++++++++++++++++++++++++++++++++++ man/massart97ex1.Rd | 17 ++++++++++ man/massart97ex3.Rd | 51 +++++++++++++++++++++++++++++ 8 files changed, 453 insertions(+) create mode 100644 man/calplot.lm.Rd create mode 100644 man/chemCal-package.Rd create mode 100644 man/din32645.Rd create mode 100644 man/inverse.predict.Rd create mode 100644 man/lod.Rd create mode 100644 man/loq.Rd create mode 100644 man/massart97ex1.Rd create mode 100644 man/massart97ex3.Rd (limited to 'man') 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 +} +\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} -- cgit v1.2.1