Much more complete version that was just submitted to CRAN.

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

7 files changed, 265 insertions, 32 deletions

diff --git a/man/mkin_long_to_wide.Rd b/man/mkin_long_to_wide.Rd
new file mode 100644
index 0000000..97791e6
--- /dev/null
+++ b/man/mkin_long_to_wide.Rd
@@ -0,0 +1,32 @@
+\name{mkin_long_to_wide}
+\alias{mkin_long_to_wide}
+\title{
+  Convert a dataframe from long to wide format.
+}
+\usage{
+mkin_long_to_wide(long_data, time = "time")
+}
+\description{
+  This function takes a dataframe in the long form as required by \code{\link{modCost}} 
+  and converts it into a dataframe with one independent variable and several 
+  dependent variables as columns.
+}
+\arguments{
+  \item{long_data}{
+  The dataframe must contain one variable with the time values specified by the 
+  \code{time} argument and one column of observed values named "value".
+}
+  \item{time}{
+  The name of the time variable.
+}
+}
+\value{
+  Dataframe in wide format.
+}
+\author{
+  Johannes Ranke
+}
+\examples{
+mkin_long_to_wide(FOCUS_2006_D)
+}
+\keyword{ manip }
diff --git a/man/mkin_wide_to_long.Rd b/man/mkin_wide_to_long.Rd
new file mode 100644
index 0000000..d3dd200
--- /dev/null
+++ b/man/mkin_wide_to_long.Rd
@@ -0,0 +1,32 @@
+\name{mkin_wide_to_long}
+\alias{mkin_wide_to_long}
+\title{
+  Convert a dataframe with observations over time into long format.
+}
+\usage{
+mkin_wide_to_long(wide_data, time = "t")
+}
+\description{
+  This function simply takes a dataframe with one independent variable and several 
+  dependent variable and converts it into the long form as required by \code{\link{modCost}}.
+}
+\arguments{
+  \item{wide_data}{
+  The dataframe must contain one variable with the time values specified by the 
+  \code{time} argument and usually more than one column of observed values.
+}
+  \item{time}{
+  The name of the time variable.
+}
+}
+\value{
+  Dataframe in long format as needed for \code{\link{modCost}}.
+}
+\author{
+  Johannes Ranke
+}
+\examples{
+wide <- data.frame(t = c(1,2,3), x = c(1,4,7), y = c(3,4,5))
+mkin_wide_to_long(wide)
+}
+\keyword{ manip }
diff --git a/man/mkinerrmin.Rd b/man/mkinerrmin.Rd
new file mode 100644
index 0000000..4bbf96a
--- /dev/null
+++ b/man/mkinerrmin.Rd
@@ -0,0 +1,46 @@
+\name{mkinerrmin}

+\Rdversion{1.1}

+\alias{mkinerrmin}

+\title{

+Calculate the minimum error to assume in order to pass the variance test

+}

+\description{

+This function uses \code{\link{optimize}} in order to iteratively find the

+smallest relative error still resulting in passing the chi-squared test

+as defined in the FOCUS kinetics report from 2006.

+}

+\usage{

+mkinerrmin(errdata, n.parms, alpha = 0.05)

+}

+\arguments{

+  \item{errdata}{

+    A data frame with mean observed values in column named \code{value_mean}

+    and predicted values in column \code{value_pred}.

+}

+  \item{n.parms}{

+    The number of optimized parameters to be taken into account for the data series.

+}

+  \item{alpha}{

+    The confidence level chosen for the chi-squared test.

+}

+}

+\value{

+  A list with the following components:

+  \item{err.min}{The relative error, expressed as a fraction.}

+  \item{n.optim}{The number of optimised parameters attributed to the data series.}

+  \item{df}{The number of remaining degrees of freedom for the chi2 error level calculations.

+    Note that mean values are used for the chi2 statistic and therefore every time point with 

+    observed values in the series only counts one time.}

+}

+\details{

+    This function is used internally by \code{\link{mkinfit}}.

+}

+\references{ 

+  FOCUS (2006) \dQuote{Guidance Document on Estimating Persistence and

+  Degradation Kinetics from Environmental Fate Studies on Pesticides in EU

+  Registration} Report of the FOCUS Work Group on Degradation Kinetics,

+  EC Document Reference Sanco/10058/2005 version 2.0, 434 pp,

+  \url{http://focus.jrc.ec.europa.eu/dk} 

+}

+\author{ Johannes Ranke }

+\keyword{ manip }

diff --git a/man/mkinfit.Rd b/man/mkinfit.Rd
index 7ddc10c..640207c 100644
--- a/man/mkinfit.Rd
+++ b/man/mkinfit.Rd
@@ -10,7 +10,7 @@
   values.
 }
 \usage{
-mkinfit(mkinmod, observed, parms.ini = rep(0.1, length(mkinmod$parms)), state.ini = c(100, rep(0, length(mkinmod$diffs) - 1)), fixed_parms = rep(FALSE, length(mkinmod$parms)), fixed_initials = c(FALSE, rep(TRUE, length(mkinmod$diffs) - 1)), plot = NULL, err = NULL, weight = "none", scaleVar = FALSE, ...)
+mkinfit(mkinmod, observed, parms.ini = rep(0.1, length(mkinmod$parms)), state.ini = c(100, rep(0, length(mkinmod$diffs) - 1)), fixed_parms = NULL, fixed_initials = names(mkinmod$diffs)[-1], plot = FALSE, quiet = FALSE, err = NULL, weight = "none", scaleVar = FALSE, ...)
 }
 \arguments{
   \item{mkinmod}{
@@ -29,56 +29,59 @@ mkinfit(mkinmod, observed, parms.ini = rep(0.1, length(mkinmod$parms)), state.in
   \item{parms.ini}{
     A named vector if initial values for the parameters, including both parameters to
     be optimised and potentially also fixed parameters as indicated by \code{fixed_parms}.
-}
+  }
   \item{state.ini}{
     A named vector of initial values for the state variables of the model. In case the 
     observed variables are represented by more than one model variable, the names will
     differ from the names of the observed variables (see \code{map} component of 
     \code{\link{mkinmod}}). The default is to set the initial value of the first model
     variable to 100 and all others to 0.
-}
+  }
   \item{fixed_parms}{
-    A vector of booleans specifying which parameters are not to be optimised. The default
-    is to include all model parameters in the optimisation.
-}
+    The names of parameters that should not be optimised but rather kept at the values
+    specified in \code{parms.ini}.
+  }
   \item{fixed_initials}{
-    A vector of booleans specifying which initial values to include in the optimisation.
-    The default is to optimise the initial value of the first model variable and to
-    keep all other initial values fixed.
-}
+    The names of model variables for which the initial state at time 0 should be excluded
+    from the optimisation. Defaults to all state variables except for the first one.
+  }
   \item{plot}{
     Should the observed values and the numerical solutions be plotted at each stage
     of the optimisation?
-}
+  }
+  \item{quiet}{
+    Suppress printing out the current model cost after each improvement?
+  }
   \item{err }{either \code{NULL}, or the name of the column with the
     \emph{error} estimates, used to weigh the residuals (see details of
     \code{\link{modCost}}); if \code{NULL}, then the residuals are not weighed.
-}
+  }
   \item{weight}{only if \code{err}=\code{NULL}: how to weigh the
     residuals, one of "none", "std", "mean", see details of \code{\link{modCost}}.
-}
+  }
   \item{scaleVar}{
     Will be passed to \code{\link{modCost}}. Default is not to scale Variables according
     to the number of observations.
-}
+  }
   \item{\dots}{
     Further arguments that will be passed to \code{\link{modFit}}. 
-}
+  }
 }
 \value{
-    A list of class \code{\link{modFit}}. Thus, at present, a summary can be obtained
-    by \code{\link{summary.modFit}}. 
+    A list with "mkinfit" and "modFit" in the class attribute. Thus, at
+    present, a summary can be obtained by \code{\link{summary.modFit}}. 
 }
 \author{
   Johannes Ranke <jranke@{harlan.com,uni-bremen.de}>
 }
 \examples{
 # One parent compound, one metabolite, both single first order.
-SFO_SFO <- mkinmod(spec = list(
+SFO_SFO <- mkinmod(
   parent = list(type = "SFO", to = "m1", sink = TRUE),
-  m1 = list(type = "SFO", to = NA, sink = TRUE)))
+  m1 = list(type = "SFO"))
 # Fit the model to the FOCUS example dataset D using defaults
 fit <- mkinfit(SFO_SFO, FOCUS_2006_D)
+str(fit)
 summary(fit)
 }
 \keyword{ models }
diff --git a/man/mkinmod.Rd b/man/mkinmod.Rd
index 4569b31..7ec9627 100644
--- a/man/mkinmod.Rd
+++ b/man/mkinmod.Rd
@@ -9,19 +9,19 @@
   kinetic model type and reaction or transfer to other observed compartments.

 }

 \usage{

-mkinmod(spec = list(parent = list(type = "SFO", to = NA, sink = TRUE)))

+mkinmod(...)

 }

 \arguments{

-  \item{spec}{

-    A list of observed variables to be modelled. Each observed variable has to be 

-    represented by a list with the following entries:

-    \code{type}{ The type of kinetics to use for the variable. Currently, only

-      single first order kinetics "SFO" or single first order with reversible binding

-      "SFORB" are implemented. }

-    \code{to}{ A vector of names of variables to which a transfer is to be assumed

-      in the model. }

-    \code{sink}{ Boolean, specifying if transformation to unspecified compounds (sink) 

-      is to be assumed in the model. }

+  \item{...}{

+    For each observed variable, a list has to be specified as an argument, containing

+    at least a component \code{type}, specifying the type of kinetics to use

+    for the variable. Currently, only single first order kinetics "SFO" or

+    single first order with reversible binding "SFORB" are implemented, as well as

+    "FOMC" for the first compartment which is assumed to be the source compartment.

+    Optional components of each argument are \code{to}, a vector of names of

+    variables to which a transfer is to be assumed in the model, and

+    \code{sink}, a logical specifying if transformation to unspecified

+    compounds (sink) is to be assumed in the model (defaults to \code{TRUE})

   }

 }

 \value{

@@ -36,9 +36,14 @@ mkinmod(spec = list(parent = list(type = "SFO", to = NA, sink = TRUE)))
   Johannes Ranke <jranke@{harlan.com,uni-bremen.de}>

 }

 \examples{

+# There are different ways to specify the SFO model

+SFO.1 <- mkinmod(parent = list(type = "SFO", to = NULL, sink = TRUE))

+SFO.2 <- mkinmod(parent = list(type = "SFO"))

+all.equal(SFO.1, SFO.2)

+

 # One parent compound, one metabolite, both single first order.

-SFO_SFO <- mkinmod(spec = list(

+SFO_SFO <- mkinmod(

   parent = list(type = "SFO", to = "m1", sink = TRUE),

-  m1 = list(type = "SFO", to = NA, sink = TRUE)))

+  m1 = list(type = "SFO"))

 }

 \keyword{ models }

diff --git a/man/mkinplot.Rd b/man/mkinplot.Rd
new file mode 100644
index 0000000..58959d7
--- /dev/null
+++ b/man/mkinplot.Rd
@@ -0,0 +1,50 @@
+\name{mkinplot}
+\alias{mkinplot}
+\title{
+  Plot the observed data and the fitted model of an mkinfit.
+}
+\description{
+  Solves the differential equations with the optimised and fixed parameters
+  from a previous successful call to \code{\link{mkinfit}} and plots 
+  the observed data together with the numerical solution of the fitted model.
+}
+\usage{
+  mkinplot(fit, xlab = "Time", ylab = "Observed", 
+    xlim = range(fit$data$time), ylim = range(fit$data$observed, na.rm=TRUE), ...)
+}
+\arguments{
+  \item{fit}{
+    an object of class \code{\link{mkinfit}}.
+  }
+  \item{xlab}{
+    label for the x axis.
+  }
+  \item{ylab}{
+    label for the y axis.
+  }
+  \item{xlim}{
+    plot range in x direction.
+  }
+  \item{ylim}{
+    plot range in y direction.
+  }
+  \item{\dots}{
+   further arguments passed to \code{\link{plot}}.
+}
+}
+\value{
+  The function is called for its side effect.
+}
+\examples{
+# One parent compound, one metabolite, both single first order.
+SFO_SFO <- mkinmod(
+  parent = list(type = "SFO", to = "m1", sink = TRUE),
+  m1 = list(type = "SFO"))
+# Fit the model to the FOCUS example dataset D using defaults
+fit <- mkinfit(SFO_SFO, FOCUS_2006_D)
+\dontrun{mkinplot(fit)}
+}
+\author{
+  Johannes Ranke
+}
+\keyword{ hplot }
diff --git a/man/summary.mkinfit.Rd b/man/summary.mkinfit.Rd
new file mode 100644
index 0000000..1c30589
--- /dev/null
+++ b/man/summary.mkinfit.Rd
@@ -0,0 +1,65 @@
+\name{summary.mkinfit}

+\alias{summary.mkinfit}

+\alias{print.summary.mkinfit}

+\title{

+  Summary method for class "mkinfit".

+}

+\description{

+  Lists model equations, the summary as returned by \code{\link{summary.modFit}},

+  the chi2 error levels calculated according to FOCUS guidance (2006) as far

+  as defined therein, and optionally the data, consisting of observed, predicted

+  and residual values.

+}

+\usage{

+\method{summary}{mkinfit}(object, data = TRUE, distimes = TRUE, cov = FALSE, ...)

+\method{print}{summary.mkinfit}(x, digits = max(3, getOption("digits") - 3), ...)

+}

+

+\arguments{

+  \item{object}{

+  an object of class \code{\link{mkinfit}}.

+}

+  \item{x}{

+  an object of class \code{summary.mkinfit}.

+}

+  \item{data}{

+  logical, indicating whether the data should be included in the summary. 

+}

+  \item{distimes}{

+  logical, indicating whether DT50 and DT90 values shoule be included.

+}

+  \item{cov}{

+  logical, indicating whether parameter covariances should be calculated.

+Passed to \code{\link{summary.modFit}}.  }

+  \item{digits}{

+  Number of digits to use for printing

+}

+  \item{\dots}{

+  optional arguments passed to methods like \code{print}.

+}

+}

+\value{

+  The summary function returns a list with the same components as

+  \code{\link{summary.modFit}}, and the additional components

+  \item{diffs }{The differential equations used in the model}

+  \item{data }{The data (see Description above).}

+  \item{start }{The starting values and bounds, if applicable, for optimised parameters.}

+  \item{fixed }{The values of fixed parameters.}

+  \item{errmin }{The chi2 error levels for each observed variable.}

+  \item{disstimes }{The DT50 and DT90 values for each observed variable.}

+  The print method is called for its side effect, i.e. printing the summary.

+}

+\references{

+  FOCUS (2006) \dQuote{Guidance Document on Estimating Persistence and

+  Degradation Kinetics from Environmental Fate Studies on Pesticides in EU

+  Registration} Report of the FOCUS Work Group on Degradation Kinetics,

+  EC Document Reference Sanco/10058/2005 version 2.0, 434 pp,

+  \url{http://focus.jrc.ec.europa.eu/dk} 

+}

+\author{

+  Johannes Ranke <jranke@harlan.com>

+}

+\examples{

+  summary(mkinfit(mkinmod(parent = list(type = "SFO")), FOCUS_2006_A))

+}

+\keyword{ utilities }