- Document endpoints() function

- Fix unit tests that were broken by introduction of 
  the endpoints function
- Small documentation fixes
- Format output of backtransformed parameters
- Integrate snippet for making static documentation
  using staticdocs by Hadley Wickham



git-svn-id: svn+ssh://svn.r-forge.r-project.org/svnroot/kinfit/pkg/mkin@41 edb9625f-4e0d-4859-8d74-9fd3b1da38cb

9 files changed, 86 insertions, 48 deletions

diff --git a/DESCRIPTION b/DESCRIPTION
index bce90d0a..b1cad781 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -2,8 +2,8 @@ Package: mkin
 Type: Package
 Title: Routines for fitting kinetic models with one or more state
   variables to chemical degradation data
-Version: 0.9-03
-Date: 2012-05-16
+Version: 0.9-04
+Date: 2012-06-26
 Author: Johannes Ranke, Katrin Lindenberger, René Lehmann
 Maintainer: Johannes Ranke <jranke@uni-bremen.de>
 Description: Calculation routines based on the FOCUS Kinetics Report (2006).
@@ -18,4 +18,4 @@ License: GPL
 LazyLoad: yes
 LazyData: yes
 Encoding: UTF-8
-URL: http://cran.r-project.org, http://r-forge.r-project.org/projects/kinfit
+URL: http://cran.r-project.org, http://kinfit.r-forge.r-project.org
diff --git a/R/mkinfit.R b/R/mkinfit.R
index d3ee5e7b..3100b30f 100644
--- a/R/mkinfit.R
+++ b/R/mkinfit.R
@@ -228,21 +228,25 @@ summary.mkinfit <- function(object, data = TRUE, distimes = TRUE, ...) {
   param <- cbind(param, se)

   dimnames(param) <- list(pnames, c("Estimate", "Std. Error"))

 

+  bparam <- as.matrix(object$parms.all)

+  dimnames(bparam) <- list(pnames, c("Estimate"))

+

   ans <- list(

-          version = as.character(packageVersion("mkin")),

-          Rversion = paste(R.version$major, R.version$minor, sep="."),

+    version = as.character(packageVersion("mkin")),

+    Rversion = paste(R.version$major, R.version$minor, sep="."),

 	  date.fit = object$date,

 	  date.summary = date(),

 	  use_of_ff = object$mkinmod$use_of_ff,

-          residuals = object$residuals,

-          residualVariance = resvar,

-          sigma = sqrt(resvar),

-          modVariance = modVariance,

-          df = c(p, rdf), cov.unscaled = covar,

-          cov.scaled = covar * resvar,

-          info = object$info, niter = object$iterations,

-          stopmess = message,

-          par = param)

+    residuals = object$residuals,

+    residualVariance = resvar,

+    sigma = sqrt(resvar),

+    modVariance = modVariance,

+    df = c(p, rdf), cov.unscaled = covar,

+    cov.scaled = covar * resvar,

+    info = object$info, niter = object$iterations,

+    stopmess = message,

+    par = param,

+    bpar = bparam)

 

   ans$diffs <- object$mkinmod$diffs

   if(data) ans$data <- object$data

@@ -285,7 +289,7 @@ print.summary.mkinfit <- function(x, digits = max(3, getOption("digits") - 3), .
   printCoefmat(x$par, digits = digits, ...)

 

   cat("\nBacktransformed parameters:\n")

-  print(as.data.frame(list(Estimate = x$parms.all)))

+  printCoefmat(x$bpar, digits = digits, ...)

 

   cat("\nResidual standard error:",

       format(signif(x$sigma, digits)), "on", rdf, "degrees of freedom\n")

diff --git a/inst/GUI/README b/inst/GUI/README
new file mode 100644
index 00000000..aa83ea6c
--- /dev/null
+++ b/inst/GUI/README
@@ -0,0 +1 @@
+These code fragments do not provide a GUI for mkin. They are purely experimental.
diff --git a/inst/unitTests/runit.mkinfit.R b/inst/unitTests/runit.mkinfit.R
index e2fc8c3f..26007e78 100644
--- a/inst/unitTests/runit.mkinfit.R
+++ b/inst/unitTests/runit.mkinfit.R
@@ -30,11 +30,11 @@ test.FOCUS_2006_SFO <- function()
   median.A.SFO <- as.numeric(lapply(subset(FOCUS_2006_SFO_ref_A_to_F, dataset == "A", 

                    c(M0, k, DT50, DT90)), "median"))

 

-  fit.A.SFO.1.r <- as.numeric(c(fit.A.SFO.1$parms.all, fit.A.SFO.1$distimes))

+  fit.A.SFO.1.r <- as.numeric(c(fit.A.SFO.1$parms.all, endpoints(fit.A.SFO.1)$distimes))

   dev.A.SFO.1 <- abs(round(100 * ((median.A.SFO - fit.A.SFO.1.r)/median.A.SFO), digits=1))

   checkIdentical(dev.A.SFO.1 < 1, rep(TRUE, length(dev.A.SFO.1)))

 

-  fit.A.SFO.2.r <- as.numeric(c(fit.A.SFO.2$parms.all, fit.A.SFO.2$distimes))

+  fit.A.SFO.2.r <- as.numeric(c(fit.A.SFO.2$parms.all, endpoints(fit.A.SFO.2)$distimes))

   dev.A.SFO.2 <- abs(round(100 * ((median.A.SFO - fit.A.SFO.2.r)/median.A.SFO), digits=1))

   checkIdentical(dev.A.SFO.2 < 1, rep(TRUE, length(dev.A.SFO.2)))

 

@@ -44,11 +44,11 @@ test.FOCUS_2006_SFO <- function()
   median.C.SFO <- as.numeric(lapply(subset(FOCUS_2006_SFO_ref_A_to_F, dataset == "C", 

                    c(M0, k, DT50, DT90)), "median"))

 

-  fit.C.SFO.1.r <- as.numeric(c(fit.C.SFO.1$parms.all, fit.C.SFO.1$distimes))

+  fit.C.SFO.1.r <- as.numeric(c(fit.C.SFO.1$parms.all, endpoints(fit.C.SFO.1)$distimes))

   dev.C.SFO.1 <- abs(round(100 * ((median.C.SFO - fit.C.SFO.1.r)/median.C.SFO), digits=1))

   checkIdentical(dev.C.SFO.1 < 1, rep(TRUE, length(dev.C.SFO.1)))

 

-  fit.C.SFO.2.r <- as.numeric(c(fit.C.SFO.2$parms.all, fit.C.SFO.2$distimes))

+  fit.C.SFO.2.r <- as.numeric(c(fit.C.SFO.2$parms.all, endpoints(fit.C.SFO.2)$distimes))

   dev.C.SFO.2 <- abs(round(100 * ((median.C.SFO - fit.C.SFO.2.r)/median.C.SFO), digits=1))

   checkIdentical(dev.C.SFO.2 < 1, rep(TRUE, length(dev.C.SFO.2)))

 } # }}}

@@ -66,7 +66,7 @@ test.FOCUS_2006_FOMC <- function()
   median.A.FOMC <- as.numeric(lapply(subset(FOCUS_2006_FOMC_ref_A_to_F, dataset == "A", 

                    c(M0, alpha, beta, DT50, DT90)), "median"))

 

-  fit.A.FOMC.r <- as.numeric(c(fit.A.FOMC$parms.all, fit.A.FOMC$distimes))

+  fit.A.FOMC.r <- as.numeric(c(fit.A.FOMC$parms.all, endpoints(fit.A.FOMC)$distimes))

   dev.A.FOMC <- abs(round(100 * ((median.A.FOMC - fit.A.FOMC.r)/median.A.FOMC), digits=1))

   dev.A.FOMC <- dev.A.FOMC[c(1, 4, 5)]

   checkIdentical(dev.A.FOMC < 1, rep(TRUE, length(dev.A.FOMC)))

@@ -77,7 +77,7 @@ test.FOCUS_2006_FOMC <- function()
   median.B.FOMC <- as.numeric(lapply(subset(FOCUS_2006_FOMC_ref_A_to_F, dataset == "B", 

                    c(M0, alpha, beta, DT50, DT90)), "median"))

 

-  fit.B.FOMC.r <- as.numeric(c(fit.B.FOMC$parms.all, fit.B.FOMC$distimes))

+  fit.B.FOMC.r <- as.numeric(c(fit.B.FOMC$parms.all, endpoints(fit.B.FOMC)$distimes))

   dev.B.FOMC <- abs(round(100 * ((median.B.FOMC - fit.B.FOMC.r)/median.B.FOMC), digits=1))

   dev.B.FOMC <- dev.B.FOMC[c(1, 4, 5)]

   checkIdentical(dev.B.FOMC < 1, rep(TRUE, length(dev.B.FOMC)))

@@ -88,7 +88,7 @@ test.FOCUS_2006_FOMC <- function()
   median.C.FOMC <- as.numeric(lapply(subset(FOCUS_2006_FOMC_ref_A_to_F, dataset == "C", 

                    c(M0, alpha, beta, DT50, DT90)), "median"))

 

-  fit.C.FOMC.r <- as.numeric(c(fit.C.FOMC$parms.all, fit.C.FOMC$distimes))

+  fit.C.FOMC.r <- as.numeric(c(fit.C.FOMC$parms.all, endpoints(fit.C.FOMC)$distimes))

   dev.C.FOMC <- abs(round(100 * ((median.C.FOMC - fit.C.FOMC.r)/median.C.FOMC), digits=1))

   dev.C.FOMC <- dev.C.FOMC[c(1, 4, 5)]

   checkIdentical(dev.C.FOMC < 1, rep(TRUE, length(dev.C.FOMC)))

@@ -106,7 +106,7 @@ test.FOCUS_2006_DFOP <- function()
   median.A.DFOP <- as.numeric(lapply(subset(FOCUS_2006_DFOP_ref_A_to_B, dataset == "A", 

                    c(M0, k1, k2, f, DT50, DT90)), "median"))

 

-  fit.A.DFOP.r <- as.numeric(c(fit.A.DFOP$parms.all, fit.A.DFOP$distimes))

+  fit.A.DFOP.r <- as.numeric(c(fit.A.DFOP$parms.all, endpoints(fit.A.DFOP)$distimes))

   dev.A.DFOP <- abs(round(100 * ((median.A.DFOP - fit.A.DFOP.r)/median.A.DFOP), digits=1))

   # about 6.7% deviation for parameter f, the others are < 0.1%

   checkIdentical(dev.A.DFOP < c(1, 1, 1, 10, 1, 1), rep(TRUE, length(dev.A.DFOP)))

@@ -117,7 +117,7 @@ test.FOCUS_2006_DFOP <- function()
   median.B.DFOP <- as.numeric(lapply(subset(FOCUS_2006_DFOP_ref_A_to_B, dataset == "B", 

                    c(M0, k1, k2, f, DT50, DT90)), "median"))

 

-  fit.B.DFOP.r <- as.numeric(c(fit.B.DFOP$parms.all, fit.B.DFOP$distimes))

+  fit.B.DFOP.r <- as.numeric(c(fit.B.DFOP$parms.all, endpoints(fit.B.DFOP)$distimes))

   dev.B.DFOP <- abs(round(100 * ((median.B.DFOP - fit.B.DFOP.r)/median.B.DFOP), digits=1))

   # about 0.6% deviation for parameter f, the others are <= 0.1%

   checkIdentical(dev.B.DFOP < 1, rep(TRUE, length(dev.B.DFOP)))

@@ -135,7 +135,7 @@ test.FOCUS_2006_HS <- function()
   median.A.HS <- as.numeric(lapply(subset(FOCUS_2006_HS_ref_A_to_F, dataset == "A", 

                    c(M0, k1, k2, tb, DT50, DT90)), "median"))

 

-  fit.A.HS.r <- as.numeric(c(fit.A.HS$parms.all, fit.A.HS$distimes))

+  fit.A.HS.r <- as.numeric(c(fit.A.HS$parms.all, endpoints(fit.A.HS)$distimes))

   dev.A.HS <- abs(round(100 * ((median.A.HS - fit.A.HS.r)/median.A.HS), digits=1))

   # about 6.7% deviation for parameter f, the others are < 0.1%

   checkIdentical(dev.A.HS < 1, rep(TRUE, length(dev.A.HS)))

@@ -146,7 +146,7 @@ test.FOCUS_2006_HS <- function()
   median.B.HS <- as.numeric(lapply(subset(FOCUS_2006_HS_ref_A_to_F, dataset == "B", 

                    c(M0, k1, k2, tb, DT50, DT90)), "median"))

 

-  fit.B.HS.r <- as.numeric(c(fit.B.HS$parms.all, fit.B.HS$distimes))

+  fit.B.HS.r <- as.numeric(c(fit.B.HS$parms.all, endpoints(fit.B.HS)$distimes))

   dev.B.HS <- abs(round(100 * ((median.B.HS - fit.B.HS.r)/median.B.HS), digits=1))

   # < 10% deviation for M0, k1, DT50 and DT90, others are problematic

   dev.B.HS <- dev.B.HS[c(1, 2, 5, 6)]

@@ -158,7 +158,7 @@ test.FOCUS_2006_HS <- function()
   median.C.HS <- as.numeric(lapply(subset(FOCUS_2006_HS_ref_A_to_F, dataset == "C", 

                    c(M0, k1, k2, tb, DT50, DT90)), "median"))

 

-  fit.A.HS.r <- as.numeric(c(fit.A.HS$parms.all, fit.A.HS$distimes))

+  fit.A.HS.r <- as.numeric(c(fit.A.HS$parms.all, endpoints(fit.A.HS)$distimes))

   dev.A.HS <- abs(round(100 * ((median.A.HS - fit.A.HS.r)/median.A.HS), digits=1))

   # deviation <= 0.1%

   checkIdentical(dev.A.HS < 1, rep(TRUE, length(dev.A.HS)))

@@ -178,9 +178,9 @@ test.FOCUS_2006_SFORB <- function()
 

   fit.A.SFORB.1.r <- as.numeric(c(

                       parent_0 = fit.A.SFORB.1$parms.all[[1]], 

-                      k1 = fit.A.SFORB.1$SFORB[[1]],

-                      k2 = fit.A.SFORB.1$SFORB[[2]],

-                      fit.A.SFORB.1$distimes))

+                      k1 = endpoints(fit.A.SFORB.1)$SFORB[[1]],

+                      k2 = endpoints(fit.A.SFORB.1)$SFORB[[2]],

+                      endpoints(fit.A.SFORB.1)$distimes))

   dev.A.SFORB.1 <- abs(round(100 * ((median.A.SFORB - fit.A.SFORB.1.r)/median.A.SFORB), digits=1))

   # The first Eigenvalue is a lot different from k1 in the DFOP fit

   # The explanation is that the dataset is simply SFO

@@ -189,9 +189,9 @@ test.FOCUS_2006_SFORB <- function()
 

   fit.A.SFORB.2.r <- as.numeric(c(

                       parent_0 = fit.A.SFORB.2$parms.all[[1]], 

-                      k1 = fit.A.SFORB.2$SFORB[[1]],

-                      k2 = fit.A.SFORB.2$SFORB[[2]],

-                      fit.A.SFORB.2$distimes))

+                      k1 = endpoints(fit.A.SFORB.2)$SFORB[[1]],

+                      k2 = endpoints(fit.A.SFORB.2)$SFORB[[2]],

+                      endpoints(fit.A.SFORB.2)$distimes))

   dev.A.SFORB.2 <- abs(round(100 * ((median.A.SFORB - fit.A.SFORB.2.r)/median.A.SFORB), digits=1))

   # The first Eigenvalue is a lot different from k1 in the DFOP fit

   # The explanation is that the dataset is simply SFO

@@ -207,17 +207,17 @@ test.FOCUS_2006_SFORB <- function()
 

   fit.B.SFORB.1.r <- as.numeric(c(

                       parent_0 = fit.B.SFORB.1$parms.all[[1]], 

-                      k1 = fit.B.SFORB.1$SFORB[[1]],

-                      k2 = fit.B.SFORB.1$SFORB[[2]],

-                      fit.B.SFORB.1$distimes))

+                      k1 = endpoints(fit.B.SFORB.1)$SFORB[[1]],

+                      k2 = endpoints(fit.B.SFORB.1)$SFORB[[2]],

+                      endpoints(fit.B.SFORB.1)$distimes))

   dev.B.SFORB.1 <- abs(round(100 * ((median.B.SFORB - fit.B.SFORB.1.r)/median.B.SFORB), digits=1))

   checkIdentical(dev.B.SFORB.1 < 1, rep(TRUE, length(dev.B.SFORB.1)))

 

   fit.B.SFORB.2.r <- as.numeric(c(

                       parent_0 = fit.B.SFORB.2$parms.all[[1]], 

-                      k1 = fit.B.SFORB.2$SFORB[[1]],

-                      k2 = fit.B.SFORB.2$SFORB[[2]],

-                      fit.B.SFORB.2$distimes))

+                      k1 = endpoints(fit.B.SFORB.2)$SFORB[[1]],

+                      k2 = endpoints(fit.B.SFORB.2)$SFORB[[2]],

+                      endpoints(fit.B.SFORB.2)$distimes))

   dev.B.SFORB.2 <- abs(round(100 * ((median.B.SFORB - fit.B.SFORB.2.r)/median.B.SFORB), digits=1))

   checkIdentical(dev.B.SFORB.2 < 1, rep(TRUE, length(dev.B.SFORB.2)))

 } # }}}

@@ -244,10 +244,10 @@ test.FOCUS_2006_D_SFO_SFO <- function()
   FOCUS_2006_D_results_schaefer07_means <- c(

     parent_0 = 99.65, DT50_parent = 7.04, DT50_m1 = 131.34)

 

-  r.1.e <- c(fit.1.e$parms.all[[1]], fit.1.e$distimes[[1]])

-  r.1.d <- c(fit.1.d$parms.all[[1]], fit.1.d$distimes[[1]])

-  r.2.e <- c(fit.2.e$parms.all[[1]], fit.2.e$distimes[[1]])

-  r.2.d <- c(fit.2.d$parms.all[[1]], fit.2.d$distimes[[1]])

+  r.1.e <- c(fit.1.e$parms.all[[1]], endpoints(fit.1.e)$distimes[[1]])

+  r.1.d <- c(fit.1.d$parms.all[[1]], endpoints(fit.1.d)$distimes[[1]])

+  r.2.e <- c(fit.2.e$parms.all[[1]], endpoints(fit.2.e)$distimes[[1]])

+  r.2.d <- c(fit.2.d$parms.all[[1]], endpoints(fit.2.d)$distimes[[1]])

 

   dev.1.e <- 100 * (r.1.e - FOCUS_2006_D_results_schaefer07_means)/r.1.e 

   checkIdentical(as.numeric(abs(dev.1.e)) < 1, rep(TRUE, 3))

diff --git a/man/endpoints.Rd b/man/endpoints.Rd
new file mode 100644
index 00000000..21316cf2
--- /dev/null
+++ b/man/endpoints.Rd
@@ -0,0 +1,33 @@
+\name{endpoints}
+\alias{endpoints}
+\title{
+Function to calculate endpoints for further use from kinetic models fitted with mkinfit
+}
+\description{
+This function calculates DT50 and DT90 values as well as formation fractions from kinetic models
+fitted with mkinfit. If the SFORB model was specified for one of the parents or metabolites, 
+the Eigenvalues are returned. These are equivalent to the rate constantes of the DFOP model, but 
+with the advantage that the SFORB model can also be used for metabolites.
+}
+\usage{
+endpoints(fit, pseudoDT50 = FALSE)
+}
+\arguments{
+  \item{fit}{
+  An object of class \code{\link{mkinfit}}.
+}
+  \item{pseudoDT50}{
+  Should pseudoDT50 values for FOMC, DFOP and SFORB models be reported, as 
+  recommended by the FOCUS group? Currently not implemented.
+}
+}
+\note{
+  The function is used internally by \code{\link{summary.mkinfit}}.
+}
+\value{
+  A list with the components mentioned above.
+}
+\author{
+  Johannes Ranke
+}
+\keyword{ manip }
diff --git a/man/ilr.Rd b/man/ilr.Rd
index 8bf7a728..cedb49ca 100644
--- a/man/ilr.Rd
+++ b/man/ilr.Rd
@@ -38,7 +38,7 @@ ilr(c(10, 1, 0.1))
 ilr(c(3, 3, 3))
 # Almost equal entries give small numbers
 ilr(c(0.3, 0.4, 0.3))
-# Only the ration between the numbers counts, not their sum
+# Only the ratio between the numbers counts, not their sum
 invilr(ilr(c(0.7, 0.29, 0.01)))
 invilr(ilr(2.1 * c(0.7, 0.29, 0.01)))
 # Inverse transformation of larger numbers gives unequal elements
diff --git a/man/schaefer07_complex_case.Rd b/man/schaefer07_complex_case.Rd
index f2f024a2..ed4f6941 100644
--- a/man/schaefer07_complex_case.Rd
+++ b/man/schaefer07_complex_case.Rd
@@ -24,7 +24,7 @@
   }

   The results are a data frame with 14 results for different parameter values

 }

-\source{

+\references{

   Schäfer D, Mikolasch M, Rainbird P and Harvey B (2007). KinGUI: a new kinetic

   software tool for evaluations according to FOCUS degradation kinetics. In: Del

   Re AAM, Capri E, Fragoulis G and Trevisan M (Eds.). Proceedings of the XIII

diff --git a/vignettes/mkin.Rnw b/vignettes/mkin.Rnw
index f674db7e..2965bc5a 100644
--- a/vignettes/mkin.Rnw
+++ b/vignettes/mkin.Rnw
@@ -26,11 +26,11 @@ options(SweaveHooks = list(
 \begin{document}

 \title{mkin -\\

 Routines for fitting kinetic models with one or more state variables to chemical degradation data}

-\author{\textbf{Johannes Ranke} \\

+\author{\textbf{Johannes Ranke} \\[0.5cm]

 %EndAName

 Eurofins Regulatory AG\\

-Weidenweg 15, CH--4310 Rheinfelden, Switzerland\\{1cm}

-and\\

+Weidenweg 15, CH--4310 Rheinfelden, Switzerland\\[0.5cm]

+and\\[0.5cm]

 University of Bremen\\

 }

 \maketitle

diff --git a/vignettes/mkin.pdf b/vignettes/mkin.pdf
index f963d1e6..523d7195 100644
--- a/vignettes/mkin.pdf
+++ b/vignettes/mkin.pdf