- inverse.predict now has a var.s argument instead of the never

  tested ss argument. This is documented in the updated vignette
- loq() now has w.loq and var.loq arguments, and stops with a message
  if neither are specified and the model has weights.
- calplot doesn't stop any more for weighted regression models, but
  only refrains from drawing prediction bands
- Added method = "din" to lod(), now that I actually have it (DIN 32645) and
  was able to see which approximation is used therein.
- removed the demos, as the examples and tests are already partially 
  duplicated
- The vignette is more of a collection of various notes, but should 
  certainly be helpful for the user.
- Version bump to 0.1-xxx



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

8 files changed, 107 insertions, 79 deletions

diff --git a/inst/doc/Makefile b/inst/doc/Makefile
index 9c5cd3a..8eca69e 100644
--- a/inst/doc/Makefile
+++ b/inst/doc/Makefile
@@ -1,6 +1,6 @@
 # Makefile for Sweave documents containing both Latex and R code
 # Author:	Johannes Ranke <jranke@uni-bremen.de>
-# Last Change: 2006 Mai 24
+# Last Change: 2006 Jun 23
 # based on the Makefile of Nicholas Lewin-Koh
 # in turn based on work of Rouben Rostmaian
 # SVN: $Id: Makefile.rnoweb 62 2006-05-24 08:30:59Z ranke $
diff --git a/inst/doc/chemCal-001.pdf b/inst/doc/chemCal-001.pdf
index 9ca7c06..9e77bb2 100644
--- a/inst/doc/chemCal-001.pdf
+++ b/inst/doc/chemCal-001.pdf
@@ -2,8 +2,8 @@
 %���ρ�\r
 1 0 obj
 <<
-/CreationDate (D:20060524104614)
-/ModDate (D:20060524104614)
+/CreationDate (D:20060623173000)
+/ModDate (D:20060623173000)
 /Title (R Graphics Output)
 /Producer (R 2.3.1)
 /Creator (R)
diff --git a/inst/doc/chemCal-002.pdf b/inst/doc/chemCal-002.pdf
index 262f50a..44ab8b6 100644
--- a/inst/doc/chemCal-002.pdf
+++ b/inst/doc/chemCal-002.pdf
@@ -2,8 +2,8 @@
 %���ρ�\r
 1 0 obj
 <<
-/CreationDate (D:20060524104614)
-/ModDate (D:20060524104614)
+/CreationDate (D:20060623173002)
+/ModDate (D:20060623173002)
 /Title (R Graphics Output)
 /Producer (R 2.3.1)
 /Creator (R)
diff --git a/inst/doc/chemCal.Rnw b/inst/doc/chemCal.Rnw
index afa5ad7..8cdc97c 100644
--- a/inst/doc/chemCal.Rnw
+++ b/inst/doc/chemCal.Rnw
@@ -8,15 +8,29 @@
 \begin{document}
 \maketitle
 
-When calibrating an analytical method, the first task is to generate
-a suitable model. If we want to use the \texttt{chemCal} functions, we
-will have to restrict ourselves to univariate, possibly weighted
-\footnote{
-For the weighted case, the function \texttt{predict.lm} would have to be 
-adapted (Bug report PR\#8877), in order to allow for weights for the x values
-used to predict the y values. This affects the functions \texttt{calplot}
-and \texttt{lod}.
-}, linear regression so far.
+The \texttt{chemCal} package was first designed in the course of a lecture and lab
+course on "analytics of organic trace contaminants" at the University of Bremen
+from October to December 2004. In the fall 2005, an email exchange with 
+Ron Wehrens led to the belief that it would be desirable to implement the
+inverse prediction method given in \cite{massart97} since it also covers the
+case of weighted regression. Studies of the IUPAC orange book and of DIN 32645
+as well as publications by Currie and the Analytical Method Committee of the 
+Royal Society of Chemistry and a nice paper by Castillo and Castells provided
+further understanding of the matter.
+
+At the moment, the package consists of four functions, working on univariate
+linear models of class \texttt{lm} or \texttt{rlm}, plus to datasets for
+validation.
+
+A \href{http://bugs.r-project.org/cgi-bin/R/wishlst-fulfilled?id=8877;user=guest}{bug
+report (PR\#8877)} and the following e-mail exchange on the r-devel mailing list about
+prediction intervals from weighted regression entailed some further studies
+on this subject. However, I did not encounter any proof or explanation of the
+formula cited below yet, so I can't really confirm that Massart's method is correct.
+
+When calibrating an analytical method, the first task is to generate a suitable
+model. If we want to use the \texttt{chemCal} functions, we will have to restrict
+ourselves to univariate, possibly weighted, linear regression so far.
 
 Once such a model has been created, the calibration can be graphically
 shown by using the \texttt{calplot} function:
@@ -24,8 +38,7 @@ shown by using the \texttt{calplot} function:
 <<echo=TRUE,fig=TRUE>>=
 library(chemCal)
 data(massart97ex3)
-attach(massart97ex3)
-m0 <- lm(y ~ x)
+m0 <- lm(y ~ x, data = massart97ex3)
 calplot(m0)
 @
 
@@ -41,28 +54,26 @@ Therefore, in Example 8 in \cite{massart97} weighted regression
 is proposed which can be reproduced by
 
 <<>>=
-yx <- split(y,x)
-ybar <- sapply(yx,mean)
-s <- round(sapply(yx,sd),digits=2)
-w <- round(1/(s^2),digits=3)
+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)
+m <- lm(y ~ x, w = weights)
 @
 
-Unfortunately, \texttt{calplot} does not work on weighted linear models,
-as noted in the footnote above.
-
 If we now want to predict a new x value from measured y values,
 we use the \texttt{inverse.predict} function:
 
 <<>>=
-inverse.predict(m,15,ws=1.67)
+inverse.predict(m, 15, ws=1.67)
 inverse.predict(m, 90, ws = 0.145)
 @
 
 The weight \texttt{ws} assigned to the measured y value has to be 
-given by the user in the case of weighted regression. By default, 
-the mean of the weights used in the linear regression is used.
+given by the user in the case of weighted regression, or alternatively,
+the approximate variance \texttt{var.s} at this location.
 
 \section*{Theory for \texttt{inverse.predict}}
 Equation 8.28 in \cite{massart97} gives a general equation for predicting the
@@ -104,6 +115,10 @@ s_{\hat{x_s}} = \frac{1}{b_1} \sqrt{\frac{{s_s}^2}{w_s m} +
             {{b_1}^2 \left( \sum{w_i} \sum{w_i {x_i}^2} - {\left( \sum{ w_i x_i } \right)}^2 \right) } \right) }
 \end{equation}
 
+where I interpret $\frac{{s_s}^2}{w_s}$ as an estimator of the variance at location
+$\hat{x_s}$, which can be replaced by a user-specified value using the argument
+\texttt{var.s} of the function \texttt{inverse.predict}.
+
 \begin{thebibliography}{1}
 \bibitem{massart97}
 Massart, L.M, Vandenginste, B.G.M., Buydens, L.M.C., De Jong, S., Lewi, P.J.,
diff --git a/inst/doc/chemCal.aux b/inst/doc/chemCal.aux
index 0eb51cc..20bfc98 100644
--- a/inst/doc/chemCal.aux
+++ b/inst/doc/chemCal.aux
@@ -14,4 +14,5 @@
 \citation{massart97}
 \citation{massart97}
 \citation{massart97}
+\citation{massart97}
 \bibcite{massart97}{1}
diff --git a/inst/doc/chemCal.log b/inst/doc/chemCal.log
index 237b975..fc0ba0f 100644
--- a/inst/doc/chemCal.log
+++ b/inst/doc/chemCal.log
@@ -1,4 +1,4 @@
-This is pdfeTeX, Version 3.141592-1.21a-2.2 (Web2C 7.5.4) (format=pdflatex 2006.4.8)  24 MAY 2006 10:46
+This is pdfeTeX, Version 3.141592-1.21a-2.2 (Web2C 7.5.4) (format=pdflatex 2006.5.30)  23 JUN 2006 17:30
 entering extended mode
 **chemCal.tex
 (./chemCal.tex
@@ -297,65 +297,62 @@ LaTeX Font Info:    External font `cmex10' loaded for size
 (Font)              <8> on input line 11.
 LaTeX Font Info:    External font `cmex10' loaded for size
 (Font)              <6> on input line 11.
-LaTeX Font Info:    Try loading font information for T1+aett on input line 13.
+LaTeX Font Info:    Try loading font information for T1+aett on input line 12.
  (/usr/share/texmf-tetex/tex/latex/ae/t1aett.fd
 File: t1aett.fd 1997/11/16 Font definitions for T1/aett.
 )
-LaTeX Font Info:    External font `cmex10' loaded for size
-(Font)              <7> on input line 15.
-LaTeX Font Info:    External font `cmex10' loaded for size
-(Font)              <5> on input line 15.
-
 <chemCal-001.pdf, id=7, 433.62pt x 433.62pt>
 File: chemCal-001.pdf Graphic file (type pdf)
  <use chemCal-001.pdf> [1
 
-{/var/lib/texmf/fonts/map/pdftex/updmap/pdftex.map} <./chemCal-001.pdf>]
-<chemCal-002.pdf, id=47, 433.62pt x 433.62pt>
+{/var/lib/texmf/fonts/map/pdftex/updmap/pdftex.map}]
+<chemCal-002.pdf, id=31, 433.62pt x 433.62pt>
 File: chemCal-002.pdf Graphic file (type pdf)
- <use chemCal-002.pdf>
-LaTeX Font Info:    Try loading font information for TS1+aett on input line 75.
+ <use chemCal-002.pdf> [2 <./chemCal-001.pdf>]
+LaTeX Font Info:    Try loading font information for TS1+aett on input line 86.
 
-LaTeX Font Info:    No file TS1aett.fd. on input line 75.
+LaTeX Font Info:    No file TS1aett.fd. on input line 86.
 
 
 LaTeX Font Warning: Font shape `TS1/aett/m/n' undefined
 (Font)              using `TS1/cmr/m/n' instead
-(Font)              for symbol `textasciigrave' on input line 75.
+(Font)              for symbol `textasciigrave' on input line 86.
 
-[2 <./chemCal-002.pdf>]
+[3 <./chemCal-002.pdf>]
 
 LaTeX Font Warning: Font shape `T1/aett/bx/n' undefined
-(Font)              using `T1/aett/m/n' instead on input line 106.
+(Font)              using `T1/aett/m/n' instead on input line 117.
 
-[3] [4] (./chemCal.aux)
+LaTeX Font Info:    External font `cmex10' loaded for size
+(Font)              <7> on input line 119.
+LaTeX Font Info:    External font `cmex10' loaded for size
+(Font)              <5> on input line 119.
+[4] [5] (./chemCal.aux)
 
 LaTeX Font Warning: Some font shapes were not available, defaults substituted.
 
  ) 
 Here is how much of TeX's memory you used:
- 3772 strings out of 94500
- 51588 string characters out of 1175772
+ 3756 strings out of 94499
+ 51475 string characters out of 1175813
  97245 words of memory out of 1000000
- 6857 multiletter control sequences out of 10000+50000
- 29608 words of font info for 66 fonts, out of 500000 for 2000
+ 6853 multiletter control sequences out of 10000+50000
+ 22302 words of font info for 54 fonts, out of 500000 for 2000
  580 hyphenation exceptions out of 8191
- 35i,8n,21p,255b,279s stack positions out of 1500i,500n,5000p,200000b,5000s
+ 35i,7n,21p,255b,283s stack positions out of 1500i,500n,5000p,200000b,5000s
 PDF statistics:
- 95 PDF objects out of 300000
+ 93 PDF objects out of 300000
  12 named destinations out of 131072
  27 words of extra memory for PDF output out of 65536
-</usr/share/texmf-tetex/fonts/type1/bluesky/cm/cmex10.pfb></usr/share/texmf-t
-etex/fonts/type1/bluesky/cm/cmsy10.pfb></usr/share/texmf-tetex/fonts/type1/blue
-sky/cm/cmmi5.pfb></usr/share/texmf-tetex/fonts/type1/bluesky/cm/cmmi7.pfb></usr
-/share/texmf-tetex/fonts/type1/bluesky/cm/cmmi10.pfb></usr/share/texmf-tetex/fo
-nts/type1/bluesky/cm/cmtt12.pfb></usr/share/texmf-tetex/fonts/type1/bluesky/cm/
-cmbx12.pfb> </var/cache/fonts/pk/ljfour/jknappen/tc/tcrm1000.600pk></usr/share/
-texmf-tetex/fonts/type1/bluesky/cm/cmtt8.pfb></usr/share/texmf-tetex/fonts/type
-1/bluesky/cm/cmr8.pfb></usr/share/texmf-tetex/fonts/type1/bluesky/cm/cmr6.pfb><
-/usr/share/texmf-tetex/fonts/type1/bluesky/cm/cmsltt10.pfb></usr/share/texmf-te
-tex/fonts/type1/bluesky/cm/cmr7.pfb></usr/share/texmf-tetex/fonts/type1/bluesky
-/cm/cmtt10.pfb></usr/share/texmf-tetex/fonts/type1/bluesky/cm/cmr10.pfb></usr/s
-hare/texmf-tetex/fonts/type1/bluesky/cm/cmr12.pfb></usr/share/texmf-tetex/fonts
-/type1/bluesky/cm/cmr17.pfb>
-Output written on chemCal.pdf (4 pages, 133895 bytes).
+</usr/share/texmf-tetex/fonts/type1/bluesky/cm/cmr5.pfb></usr/share/texmf-tet
+ex/fonts/type1/bluesky/cm/cmex10.pfb></usr/share/texmf-tetex/fonts/type1/bluesk
+y/cm/cmsy10.pfb></usr/share/texmf-tetex/fonts/type1/bluesky/cm/cmmi5.pfb></usr/
+share/texmf-tetex/fonts/type1/bluesky/cm/cmmi7.pfb></usr/share/texmf-tetex/font
+s/type1/bluesky/cm/cmr7.pfb></usr/share/texmf-tetex/fonts/type1/bluesky/cm/cmmi
+10.pfb></usr/share/texmf-tetex/fonts/type1/bluesky/cm/cmtt12.pfb></usr/share/te
+xmf-tetex/fonts/type1/bluesky/cm/cmbx12.pfb> </var/cache/fonts/pk/ljfour/jknapp
+en/tc/tcrm1000.600pk></usr/share/texmf-tetex/fonts/type1/bluesky/cm/cmsltt10.pf
+b></usr/share/texmf-tetex/fonts/type1/bluesky/cm/cmtt10.pfb></usr/share/texmf-t
+etex/fonts/type1/bluesky/cm/cmr10.pfb></usr/share/texmf-tetex/fonts/type1/blues
+ky/cm/cmr12.pfb></usr/share/texmf-tetex/fonts/type1/bluesky/cm/cmr17.pfb>
+Output written on chemCal.pdf (5 pages, 123681 bytes).
diff --git a/inst/doc/chemCal.pdf b/inst/doc/chemCal.pdf
index 45a50eb..027e053 100644
--- a/inst/doc/chemCal.pdf
+++ b/inst/doc/chemCal.pdf
diff --git a/inst/doc/chemCal.tex b/inst/doc/chemCal.tex
index e26172f..0469848 100644
--- a/inst/doc/chemCal.tex
+++ b/inst/doc/chemCal.tex
@@ -9,15 +9,29 @@
 \begin{document}
 \maketitle
 
-When calibrating an analytical method, the first task is to generate
-a suitable model. If we want to use the \texttt{chemCal} functions, we
-will have to restrict ourselves to univariate, possibly weighted
-\footnote{
-For the weighted case, the function \texttt{predict.lm} would have to be 
-adapted (Bug report PR\#8877), in order to allow for weights for the x values
-used to predict the y values. This affects the functions \texttt{calplot}
-and \texttt{lod}.
-}, linear regression so far.
+The \texttt{chemCal} package was first designed in the course of a lecture and lab
+course on "analytics of organic trace contaminants" at the University of Bremen
+from October to December 2004. In the fall 2005, an email exchange with 
+Ron Wehrens led to the belief that it would be desirable to implement the
+inverse prediction method given in \cite{massart97} since it also covers the
+case of weighted regression. Studies of the IUPAC orange book and of DIN 32645
+as well as publications by Currie and the Analytical Method Committee of the 
+Royal Society of Chemistry and a nice paper by Castillo and Castells provided
+further understanding of the matter.
+
+At the moment, the package consists of four functions, working on univariate
+linear models of class \texttt{lm} or \texttt{rlm}, plus to datasets for
+validation.
+
+A \href{http://bugs.r-project.org/cgi-bin/R/wishlst-fulfilled?id=8877;user=guest}{bug
+report (PR\#8877)} and the following e-mail exchange on the r-devel mailing list about
+prediction intervals from weighted regression entailed some further studies
+on this subject. However, I did not encounter any proof or explanation of the
+formula cited below yet, so I can't really confirm that Massart's method is correct.
+
+When calibrating an analytical method, the first task is to generate a suitable
+model. If we want to use the \texttt{chemCal} functions, we will have to restrict
+ourselves to univariate, possibly weighted, linear regression so far.
 
 Once such a model has been created, the calibration can be graphically
 shown by using the \texttt{calplot} function:
@@ -26,8 +40,7 @@ shown by using the \texttt{calplot} function:
 \begin{Sinput}
 > library(chemCal)
 > data(massart97ex3)
-> attach(massart97ex3)
-> m0 <- lm(y ~ x)
+> m0 <- lm(y ~ x, data = massart97ex3)
 > calplot(m0)
 \end{Sinput}
 \end{Schunk}
@@ -49,6 +62,7 @@ is proposed which can be reproduced by
 
 \begin{Schunk}
 \begin{Sinput}
+> attach(massart97ex3)
 > yx <- split(y, x)
 > ybar <- sapply(yx, mean)
 > s <- round(sapply(yx, sd), digits = 2)
@@ -58,9 +72,6 @@ is proposed which can be reproduced by
 \end{Sinput}
 \end{Schunk}
 
-Unfortunately, \texttt{calplot} does not work on weighted linear models,
-as noted in the footnote above.
-
 If we now want to predict a new x value from measured y values,
 we use the \texttt{inverse.predict} function:
 
@@ -100,8 +111,8 @@ $`Confidence Limits`
 \end{Schunk}
 
 The weight \texttt{ws} assigned to the measured y value has to be 
-given by the user in the case of weighted regression. By default, 
-the mean of the weights used in the linear regression is used.
+given by the user in the case of weighted regression, or alternatively,
+the approximate variance \texttt{var.s} at this location.
 
 \section*{Theory for \texttt{inverse.predict}}
 Equation 8.28 in \cite{massart97} gives a general equation for predicting the
@@ -143,6 +154,10 @@ s_{\hat{x_s}} = \frac{1}{b_1} \sqrt{\frac{{s_s}^2}{w_s m} +
             {{b_1}^2 \left( \sum{w_i} \sum{w_i {x_i}^2} - {\left( \sum{ w_i x_i } \right)}^2 \right) } \right) }
 \end{equation}
 
+where I interpret $\frac{{s_s}^2}{w_s}$ as an estimator of the variance at location
+$\hat{x_s}$, which can be replaced by a user-specified value using the argument
+\texttt{var.s} of the function \texttt{inverse.predict}.
+
 \begin{thebibliography}{1}
 \bibitem{massart97}
 Massart, L.M, Vandenginste, B.G.M., Buydens, L.M.C., De Jong, S., Lewi, P.J.,