3 files changed, 164 insertions, 0 deletions
diff --git a/man/FOCUS_2006_datasets.Rd b/man/FOCUS_2006_datasets.Rd
new file mode 100644
index 00000000..04565f74
--- /dev/null
+++ b/man/FOCUS_2006_datasets.Rd
@@ -0,0 +1,35 @@
+\name{FOCUS_2006_datasets}
+\Rdversion{1.1}
+\alias{FOCUS_2006_A}
+\alias{FOCUS_2006_B}
+\alias{FOCUS_2006_C}
+\alias{FOCUS_2006_D}
+\alias{FOCUS_2006_E}
+\alias{FOCUS_2006_F}
+\docType{data}
+\title{
+Datasets A to F from the FOCUS Kinetics report from 2006
+}
+\description{
+Data taken from an FOCUS (2006), p. 258.
+}
+\usage{FOCUS_2006_datasets}
+\format{
+  6 datasets with observations on the following variables.
+  \describe{
+    \item{\code{name}}{a factor containing the name of the observed variable}
+    \item{\code{time}}{a numeric vector containing time points}
+    \item{\code{value}}{a numeric vector containing concentrations in percent of applied radioactivity}
+  }
+}
+\source{
+  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{
+FOCUS_2006_C
+}
+\keyword{datasets}
diff --git a/man/mkinfit.Rd b/man/mkinfit.Rd
new file mode 100644
index 00000000..7ddc10c1
--- /dev/null
+++ b/man/mkinfit.Rd
@@ -0,0 +1,85 @@
+\name{mkinfit}
+\alias{mkinfit}
+\title{
+  Fit a kinetic model to data with one or more state variables.
+}
+\description{
+  This function uses the Flexible Modelling Environment package
+  \code{\link{FME}} to create a function calculating the model cost, which is
+  then minimised, using the specified initial or fixed parameters and starting
+  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, ...)
+}
+\arguments{
+  \item{mkinmod}{
+    A list of class \code{\link{mkinmod}}, containing the kinetic model to be fitted to the data.
+  }
+  \item{observed}{
+    The observed data. It has to be in the long format as described in
+    \code{\link{modFit}}, i.e. the first column must contain the name of the
+    observed variable for each data point. The second column must contain the
+    times of observation, named "time".  The third column must be named "value"
+    and contain the observed values. Optionally, a further column can contain
+    weights for each data point. If it is not named "err", its name must be
+    passed as a further argument named \code{err} which is then passed on to
+    \code{\link{modFit}}.
+  }
+  \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.
+}
+  \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.
+}
+  \item{plot}{
+    Should the observed values and the numerical solutions be plotted at each stage
+    of the optimisation?
+}
+  \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}}. 
+}
+\author{
+  Johannes Ranke <jranke@{harlan.com,uni-bremen.de}>
+}
+\examples{
+# One parent compound, one metabolite, both single first order.
+SFO_SFO <- mkinmod(spec = list(
+  parent = list(type = "SFO", to = "m1", sink = TRUE),
+  m1 = list(type = "SFO", to = NA, sink = TRUE)))
+# Fit the model to the FOCUS example dataset D using defaults
+fit <- mkinfit(SFO_SFO, FOCUS_2006_D)
+summary(fit)
+}
+\keyword{ models }
+\keyword{ optimize }
diff --git a/man/mkinmod.Rd b/man/mkinmod.Rd
new file mode 100644
index 00000000..4569b317
--- /dev/null
+++ b/man/mkinmod.Rd
@@ -0,0 +1,44 @@
+\name{mkinmod}
+\alias{mkinmod}
+\title{
+  Function to set up a kinetic model with one or more state variables.
+}
+\description{
+  The function takes a specification, consisting of a list of the observed variables
+  in the data. Each observed variable is again represented by a list, specifying the 
+  kinetic model type and reaction or transfer to other observed compartments.
+}
+\usage{
+mkinmod(spec = list(parent = list(type = "SFO", to = NA, sink = TRUE)))
+}
+\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. }
+  }
+}
+\value{
+  A list of class \code{mkinmod} for use with \code{\link{mkinfit}}, containing 
+    \item{diffs}{ A vector of string representations of differential equations,
+      one for each modelling variable. }
+    \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. }
+}
+\author{
+  Johannes Ranke <jranke@{harlan.com,uni-bremen.de}>
+}
+\examples{
+# One parent compound, one metabolite, both single first order.
+SFO_SFO <- mkinmod(spec = list(
+  parent = list(type = "SFO", to = "m1", sink = TRUE),
+  m1 = list(type = "SFO", to = NA, sink = TRUE)))
+}
+\keyword{ models }