Update kinfit and mkin to the latest version published on BerliOS.

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

14 files changed, 344 insertions, 23 deletions

diff --git a/man/DFOP.solution.Rd b/man/DFOP.solution.Rd
new file mode 100644
index 00000000..d30cf7f3
--- /dev/null
+++ b/man/DFOP.solution.Rd
@@ -0,0 +1,36 @@
+\name{DFOP.solution}

+\Rdversion{1.1}

+\alias{DFOP.solution}

+\title{

+Dual First-Order in Parallel kinetics

+}

+\description{

+  Function describing decline from a defined starting value using the sum

+  of two exponential decline functions.

+}

+\usage{

+DFOP.solution(t, parent.0, k1, k2, g)

+}

+\arguments{

+  \item{t}{ Time. }

+  \item{parent.0}{ Starting value for the response variable at time zero. }

+  \item{k1}{ First kinetic constant. }

+  \item{k2}{ Second kinetic constant. }

+  \item{g}{ Fraction of the starting value declining according to the

+    first kinetic constant.

+  }

+}

+\value{

+  The value of the response variable at time \code{t}.

+}

+\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} 

+}

+\examples{

+  \dontrun{plot(function(x) DFOP.solution(x, 100, 5, 0.5, 0.3), 0, 4, ylim=c(0,100))}

+}

+\keyword{ manip }

diff --git a/man/FOCUS_2006_datasets.Rd b/man/FOCUS_2006_datasets.Rd
index 04565f74..5053b880 100644
--- a/man/FOCUS_2006_datasets.Rd
+++ b/man/FOCUS_2006_datasets.Rd
@@ -11,7 +11,7 @@
 Datasets A to F from the FOCUS Kinetics report from 2006

 }

 \description{

-Data taken from an FOCUS (2006), p. 258.

+Data taken from FOCUS (2006), p. 258.

 }

 \usage{FOCUS_2006_datasets}

 \format{

diff --git a/man/FOMC.solution.Rd b/man/FOMC.solution.Rd
new file mode 100644
index 00000000..d04d34e1
--- /dev/null
+++ b/man/FOMC.solution.Rd
@@ -0,0 +1,49 @@
+\name{FOMC.solution}

+\Rdversion{1.1}

+\alias{FOMC.solution}

+\title{ First-Order Multi-Compartment kinetics }

+\description{

+  Function describing exponential decline from a defined starting value, with 

+  a decreasing rate constant. 

+

+  The form given here differs slightly from the original reference by Gustafson

+  and Holden (1990). The parameter \code{beta} corresponds to 1/beta in the

+  original equation.

+}

+\usage{

+FOMC.solution(t, parent.0, alpha, beta)

+}

+\arguments{

+  \item{t}{ Time. }

+  \item{parent.0}{ Starting value for the response variable at time zero. }

+  \item{alpha}{ 

+    Shape parameter determined by coefficient of variation of rate constant

+    values. }

+  \item{beta}{

+    Location parameter.

+}

+}

+\note{

+  The solution of the FOMC kinetic model reduces to the

+  \code{\link{SFO.solution}} for large values of \code{alpha} and

+  \code{beta} with 

+  \eqn{k = \frac{\beta}{\alpha}}{k = beta/alpha}.

+}

+\value{

+  The value of the response variable at time \code{t}.

+}

+\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} 

+

+  Gustafson DI and Holden LR (1990) Nonlinear pesticide dissipation in soil: A

+  new model based on spatial variability. \emph{Environmental Science and 

+  Technology} \bold{24}, 1032-1038

+}

+\examples{

+  \dontrun{plot(function(x) FOMC.solution(x, 100, 10, 2), 0, 2)}

+}

+\keyword{ manip }

diff --git a/man/HS.solution.Rd b/man/HS.solution.Rd
new file mode 100644
index 00000000..71f68a1e
--- /dev/null
+++ b/man/HS.solution.Rd
@@ -0,0 +1,34 @@
+\name{HS.solution}

+\Rdversion{1.1}

+\alias{HS.solution}

+\title{ Hockey-Stick kinetics }

+\description{

+  Function describing two exponential decline functions with a break point

+  between them.

+}

+\usage{

+HS.solution(t, parent.0, k1, k2, tb)

+}

+\arguments{

+  \item{t}{ Time. }

+  \item{parent.0}{ Starting value for the response variable at time zero. }

+  \item{k1}{ First kinetic constant. }

+  \item{k2}{ Second kinetic constant. }

+  \item{tb}{ Break point. Before this time, exponential decline according

+    to \code{k1} is calculated, after this time, exponential decline proceeds

+    according to \code{k2}. }

+}

+\value{

+  The value of the response variable at time \code{t}.

+}

+\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} 

+}

+\examples{

+  \dontrun{plot(function(x) HS.solution(x, 100, 2, 0.3, 0.5), 0, 2, ylim=c(0,100))}

+}

+\keyword{ manip }

diff --git a/man/SFO.solution.Rd b/man/SFO.solution.Rd
new file mode 100644
index 00000000..41a9ba96
--- /dev/null
+++ b/man/SFO.solution.Rd
@@ -0,0 +1,29 @@
+\name{SFO.solution}

+\Rdversion{1.1}

+\alias{SFO.solution}

+\title{ Single First-Order kinetics }

+\description{

+  Function describing exponential decline from a defined starting value.

+}

+\usage{

+  SFO.solution(t, parent.0, k)

+}

+\arguments{

+  \item{t}{ Time. }

+  \item{parent.0}{ Starting value for the response variable at time zero. }

+  \item{k}{ Kinetic constant. }

+}

+\value{

+  The value of the response variable at time \code{t}.

+}

+\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} 

+}

+\examples{

+  \dontrun{plot(function(x) SFO.solution(x, 100, 3), 0, 2)}

+}

+\keyword{ manip }

diff --git a/man/SFORB.solution.Rd b/man/SFORB.solution.Rd
new file mode 100644
index 00000000..a935f696
--- /dev/null
+++ b/man/SFORB.solution.Rd
@@ -0,0 +1,36 @@
+\name{SFORB.solution}

+\Rdversion{1.1}

+\alias{SFORB.solution}

+\title{ Single First-Order Reversible Binding kinetics }

+\description{

+  Function describing the solution of the differential equations describing

+  the kinetic model with first-order terms for a two-way transfer from a free

+  to a bound fraction, and a first-order degradation term for the free

+  fraction.  The initial condition is a defined amount in the free fraction and

+  no substance in the bound fraction.

+}

+\usage{

+  SFORB.solution(t, parent.0, k_12, k_21, k_1output)

+}

+\arguments{

+  \item{t}{ Time. }

+  \item{parent.0}{ Starting value for the response variable at time zero. }

+  \item{k_12}{ Kinetic constant describing transfer from free to bound. }

+  \item{k_21}{ Kinetic constant describing transfer from bound to free. }

+  \item{k_1output}{ Kinetic constant describing degradation of the free fraction. }

+}

+\value{

+  The value of the response variable, which is the sum of free and bound 

+  fractions at time \code{t}.

+}

+\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} 

+}

+\examples{

+  \dontrun{plot(function(x) SFORB.solution(x, 100, 0.5, 2, 3), 0, 2)}

+}

+\keyword{ manip }

diff --git a/man/mkin_long_to_wide.Rd b/man/mkin_long_to_wide.Rd
index 97791e6d..6fa18606 100644
--- a/man/mkin_long_to_wide.Rd
+++ b/man/mkin_long_to_wide.Rd
@@ -4,7 +4,7 @@
   Convert a dataframe from long to wide format.
 }
 \usage{
-mkin_long_to_wide(long_data, time = "time")
+mkin_long_to_wide(long_data, time = "time", outtime = "time")
 }
 \description{
   This function takes a dataframe in the long form as required by \code{\link{modCost}} 
@@ -17,7 +17,10 @@ mkin_long_to_wide(long_data, time = "time")
   \code{time} argument and one column of observed values named "value".
 }
   \item{time}{
-  The name of the time variable.
+  The name of the time variable in the long input data.
+}
+  \item{outtime}{
+  The name of the time variable in the wide output data.
 }
 }
 \value{
diff --git a/man/mkinerrmin.Rd b/man/mkinerrmin.Rd
index 4bbf96ab..654115b6 100644
--- a/man/mkinerrmin.Rd
+++ b/man/mkinerrmin.Rd
@@ -42,5 +42,4 @@ mkinerrmin(errdata, n.parms, alpha = 0.05)
   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 0ec2d218..d4139eb3 100644
--- a/man/mkinfit.Rd
+++ b/man/mkinfit.Rd
@@ -15,7 +15,10 @@ mkinfit(mkinmod, observed,
   state.ini = c(100, rep(0, length(mkinmod$diffs) - 1)), 
   lower = 0, upper = Inf, 
   fixed_parms = NULL, fixed_initials = names(mkinmod$diffs)[-1], 
-  plot = FALSE, quiet = FALSE, err = NULL, weight = "none", scaleVar = FALSE, ...)
+  eigen = FALSE,
+  plot = FALSE, quiet = FALSE, err = NULL, weight = "none", 
+  scaleVar = FALSE, 
+  atol = 1e-6, ...)
 }
 \arguments{
   \item{mkinmod}{
@@ -32,8 +35,11 @@ mkinfit(mkinmod, observed,
     \code{\link{modFit}}.
   }
   \item{parms.ini}{
-    A named vector if initial values for the parameters, including both parameters to
+    A named vector if initial values for the parameters, including parameters to
     be optimised and potentially also fixed parameters as indicated by \code{fixed_parms}.
+    The default is to set the initial values to 0.1. The setting of the initial values for 
+    the parameters has a strong impart on performance and it lies in the responsibilty of the 
+    user to set sensible initial values.   
   }
   \item{state.ini}{
     A named vector of initial values for the state variables of the model. In case the 
@@ -47,9 +53,10 @@ mkinfit(mkinmod, observed,
     negative values to not make sense for the models currently created by \code{\link{mkinmod}}.
   }
   \item{upper}{
-    Upper bounds for the parameters, passed to \code{\link{modFit}}. Defaults to \code{Inf}. Setting
-    non-infinite upper bounds has a strong impact on performance, and using a method like "L-BFGS-B" (by 
-    specifying an additional \code{method} argument) is recommended.
+    Upper bounds for the parameters, passed to \code{\link{modFit}}. Defaults to \code{Inf} 
+    except for formation fraction parameters. Setting non-infinite upper bounds has a strong 
+    impact on performance, and using a method like "L-BFGS-B" (by specifying an additional 
+    \code{method} argument) is recommended.
   }
   \item{fixed_parms}{
     The names of parameters that should not be optimised but rather kept at the values
@@ -59,6 +66,12 @@ mkinfit(mkinmod, observed,
     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{eigen}{
+    Should the solution of the system of differential equations be based on the 
+    spectral decomposition of the coefficient matrix in cases that this is
+    possible? Be aware that the results may differ from the results returned using
+    the ode solver.
+  }
   \item{plot}{
     Should the observed values and the numerical solutions be plotted at each stage
     of the optimisation?
@@ -77,13 +90,17 @@ mkinfit(mkinmod, observed,
     Will be passed to \code{\link{modCost}}. Default is not to scale Variables according
     to the number of observations.
   }
+  \item{atol}{
+    Absolute error tolerance, passed to \code{\link{ode}}. Default is 1e-6 as in 
+    \code{\link{lsoda}}.
+  }
   \item{\dots}{
     Further arguments that will be passed to \code{\link{modFit}}. 
   }
 }
 \value{
-    A list with "mkinfit" and "modFit" in the class attribute. Thus, at
-    present, a summary can be obtained by \code{\link{summary.modFit}}. 
+    A list with "mkinfit" and "modFit" in the class attribute. 
+    A summary can be obtained by \code{\link{summary.mkinfit}}. 
 }
 \author{
   Johannes Ranke <jranke@{harlan.com,uni-bremen.de}>
diff --git a/man/mkinmod.Rd b/man/mkinmod.Rd
index 7ec96277..7c117357 100644
--- a/man/mkinmod.Rd
+++ b/man/mkinmod.Rd
@@ -15,13 +15,16 @@ mkinmod(...)
   \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})

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

+    single first order with reversible binding "SFORB" are implemented for all

+    variables, while 

+    "FOMC", "DFOP" and "HS" can additionally be chosen for the first

+    variable 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{

@@ -31,6 +34,7 @@ mkinmod(...)
     \item{parms}{ A vector of parameter names occurring in the differential equations. }

     \item{map}{ A list containing named character vectors for each observed variable, specifying

       the modelling variables by which it is represented. }

+    \item{coefmat}{ The coefficient matrix, if the system of differential equations can be represented by one. }

 }

 \author{

   Johannes Ranke <jranke@{harlan.com,uni-bremen.de}>

diff --git a/man/mkinplot.Rd b/man/mkinplot.Rd
index 58959d77..b72675a9 100644
--- a/man/mkinplot.Rd
+++ b/man/mkinplot.Rd
@@ -10,7 +10,8 @@
 }
 \usage{
   mkinplot(fit, xlab = "Time", ylab = "Observed", 
-    xlim = range(fit$data$time), ylim = range(fit$data$observed, na.rm=TRUE), ...)
+    xlim = range(fit$data$time), ylim = range(fit$data$observed, na.rm=TRUE), 
+    legend = TRUE, ...)
 }
 \arguments{
   \item{fit}{
@@ -28,6 +29,9 @@
   \item{ylim}{
     plot range in y direction.
   }
+  \item{legend}{
+    legend specifying if a legend should be included in the plot.
+  }
   \item{\dots}{
    further arguments passed to \code{\link{plot}}.
 }
diff --git a/man/mkinresplot.Rd b/man/mkinresplot.Rd
new file mode 100644
index 00000000..0b48692c
--- /dev/null
+++ b/man/mkinresplot.Rd
@@ -0,0 +1,64 @@
+\name{mkinresplot}

+\alias{mkinresplot}

+\title{

+  Function to plot residuals stored in an mkin object

+}

+\description{

+  This function plots the residuals for the specified subset of the 

+  observed variables from an mkinfit object.

+}

+\usage{

+  mkinresplot(object, obs_vars = vector(), 

+    xlab = "Time [days]", ylab = "Residual [\% of applied radioactivity]", 

+    maxabs = "auto", legend = TRUE, lpos = "topright", ...)

+}

+\arguments{

+  \item{object}{

+    A fit represented in an \code{\link{mkinfit}} object.

+}

+  \item{obs_vars}{

+    A character vector of names of the observed variables for which residuals

+    should be plotted.

+}

+  \item{xlab}{

+    Label for the x axis. Defaults to "Time [days]".

+}

+  \item{ylab}{

+    Label for the y axis. Defaults to "Residual [\% of applied radioactivity]".

+}

+  \item{maxabs}{

+    Maximum absolute value of the residuals. This is used for the scaling of

+    the y axis and defaults to "auto".

+}

+  \item{legend}{

+    Should a legend be plotted? Defaults to "TRUE".

+}

+  \item{lpos}{ 

+    Where should the legend be placed? Default is "topright". Will be passed on to

+		\code{\link{legend}}. }

+  \item{\dots}{

+   further arguments passed to \code{\link{plot}}.

+}

+}

+\value{

+  Nothing is returned by this function, as it is called for its side effect, namely to produce a plot.

+}

+\author{

+  Katrin Lindenberger and Johannes Ranke

+}

+

+\seealso{

+ \code{\link{mkinplot}}, for a way to plot the data and the fitted lines of the

+ mkinfit object.  }

+\examples{

+data <- mkin_wide_to_long(schaefer07_complex_case, time = "time")

+model <- mkinmod(

+  parent = list(type = "SFO", to = c("A1", "B1", "C1"), sink = FALSE),

+  A1 = list(type = "SFO", to = "A2"),

+  B1 = list(type = "SFO"),

+  C1 = list(type = "SFO"),

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

+\dontrun{fit <- mkinfit(model, data, plot=TRUE)}

+\dontrun{mkinresplot(fit, "A1")}

+}

+\keyword{ hplot }

diff --git a/man/mkinstart.Rd b/man/mkinstart.Rd
new file mode 100644
index 00000000..ec1204f2
--- /dev/null
+++ b/man/mkinstart.Rd
@@ -0,0 +1,38 @@
+\name{mkinstart}

+\alias{mkinstart}

+\title{

+  Generate starting parameters for optimisations

+}

+\description{

+  This function is supposed to analyse a kinetic model and kinetic data in

+  order to generate suitable starting parameters for fitting the model.

+  It does not do anything really useful at the moment.

+}

+\usage{

+mkinstart(model, data, mode = "auto")

+}

+\arguments{

+  \item{model}{

+    A kinetic model of class \code{\link{mkinmod}}.

+}

+  \item{data}{

+    Kinetic data in wide format suitable for fitting with \code{\link{mkinfit}}.

+}

+  \item{mode}{

+    How the starting parameters should be generated. At the moment, only 

+    "auto" is supported, which internally uses \code{\link{kinfit}}. 

+}

+}

+\details{

+%%  ~~ If necessary, more details than the description above ~~

+}

+\value{

+  A named vector of starting parameters.

+}

+\author{

+  Johannes Ranke

+}

+\examples{

+   

+}

+\keyword{ manip }

diff --git a/man/summary.mkinfit.Rd b/man/summary.mkinfit.Rd
index 1c305899..8a8c6ab2 100644
--- a/man/summary.mkinfit.Rd
+++ b/man/summary.mkinfit.Rd
@@ -11,8 +11,8 @@
   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), ...)

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

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

 }

 

 \arguments{

@@ -26,7 +26,10 @@
   logical, indicating whether the data should be included in the summary. 

 }

   \item{distimes}{

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

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

+}

+  \item{ff}{

+  logical, indicating whether formation fractions should be included.

 }

   \item{cov}{

   logical, indicating whether parameter covariances should be calculated.

@@ -34,6 +37,10 @@ Passed to \code{\link{summary.modFit}}.  }
   \item{digits}{

   Number of digits to use for printing

 }

+  \item{tval}{

+  Should the test statistic of the t-test for parameter significance be

+  printed? Defaults to \code{TRUE}. Saves vertical space if set to \code{FALSE}.

+}

   \item{\dots}{

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

 }

@@ -47,6 +54,7 @@ Passed to \code{\link{summary.modFit}}.  }
   \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.}

+  \item{ff }{The estimated formation fractions derived from the fitted model.}

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

 }

 \references{

@@ -57,7 +65,7 @@ Passed to \code{\link{summary.modFit}}.  }
   \url{http://focus.jrc.ec.europa.eu/dk} 

 }

 \author{

-  Johannes Ranke <jranke@harlan.com>

+  Johannes Ranke <jranke@{harlan.com,uni-bremen.de}>

 }

 \examples{

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