Initial upload of the upcoming multicompartment version of kinfit.

Some functionality is still missing (chi2), some may never be implemented
(FOMC model), but in general it is much more powerful than kinfit, owing
to the powerful FME package.



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

15 files changed, 691 insertions, 0 deletions

diff --git a/DESCRIPTION b/DESCRIPTION
new file mode 100644
index 0000000..96f651e
--- /dev/null
+++ b/DESCRIPTION
@@ -0,0 +1,13 @@
+Package: mkin

+Type: Package

+Title: Routines for fitting kinetic models with one or more state variables to chemical degradation data

+Version: 0.5-1

+Date: 2010-05-11

+Author: Johannes Ranke

+Maintainer: Johannes Ranke <jranke@harlan.com>

+Description: Calculation routines based on the FOCUS Kinetics 

+ Report (2006)

+Depends: FME

+License: GPL

+LazyLoad: yes

+LazyData: yes

diff --git a/R/mkinfit.R b/R/mkinfit.R
new file mode 100644
index 0000000..9651fd6
--- /dev/null
+++ b/R/mkinfit.R
@@ -0,0 +1,66 @@
+mkinfit <- function(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,

+  ...)

+{

+  # Name the parameters if they are not named yet

+  if(is.null(names(parms.ini))) names(parms.ini) <- mkinmod$parms

+  # Create a function calculating the differentials specified by the model

+  mkindiff <- function(t, state, parms) {

+    diffs <- vector()

+    for (box in names(mkinmod$diffs))

+    {

+      diffname <- paste("d", box, sep="_")      

+      diffs[diffname] <- with(as.list(c(state, parms)),

+        eval(parse(text=mkinmod$diffs[[box]])))

+    }

+    return(list(c(diffs)))

+  } 

+

+  # Name the inital parameter values if they are not named yet

+  if(is.null(names(state.ini))) names(state.ini) <- names(mkinmod$diffs)

+

+  # TODO: Collect parameters to be optimised

+  parms.optim <- parms.ini[!fixed_parms]

+  parms.fixed <- parms.ini[fixed_parms]

+

+  state.ini.optim <- state.ini[!fixed_initials]

+  state.ini.optim.boxnames <- names(state.ini.optim)

+  names(state.ini.optim) <- paste(names(state.ini.optim), "0", sep="_")

+  state.ini.fixed <- state.ini[fixed_initials]

+

+  # Define the model cost function

+  cost <- function(P)

+  {

+    if(length(state.ini.optim) > 0) {

+      odeini <- c(P[1:length(state.ini.optim)], state.ini.fixed)

+      names(odeini) <- c(state.ini.optim.boxnames, names(state.ini.fixed))

+    } else odeini <- state.ini.fixed

+

+    odeparms <- c(P[(length(state.ini.optim) + 1):length(P)], parms.fixed)

+    # Solve the ODE

+    out <- ode(

+      y = odeini,

+      times = unique(observed$time),

+      func = mkindiff, 

+      parms = odeparms)

+     

+    # Output transformation for models with ghost compartments like SFORB

+    out_transformed <- data.frame(time = out[,"time"])

+    for (var in names(mkinmod$map)) {

+      if(length(mkinmod$map[[var]]) == 1) {

+        out_transformed[var] <- out[, var]

+      } else {

+        out_transformed[var] <- rowSums(out[, mkinmod$map[[var]]])

+      }

+    }    

+    

+    return(modCost(out_transformed, observed, y = "value",

+      err = err, weight = weight, scaleVar = scaleVar))

+  }

+  modFit(cost, c(state.ini.optim, parms.optim), ...)

+}

diff --git a/R/mkinmod.R b/R/mkinmod.R
new file mode 100644
index 0000000..7e64f87
--- /dev/null
+++ b/R/mkinmod.R
@@ -0,0 +1,76 @@
+mkinmod <- function(spec = list(parent = list(type = "SFO", to = NA, sink = TRUE)))

+{

+  if(!is.list(spec)) stop("spec must be a list of model specifications for each observed variable")

+

+  # The returned model will be a list of two character vectors, containing

+  # differential equations and parameter names

+  parms <- vector()

+  diffs <- vector()

+  map <- list()

+

+  # Establish list of differential equations

+  for (varname in names(spec))

+  {

+    if(!spec[[varname]]$type %in% c("SFO", "SFORB")) stop("Available types are SFO and SFORB only")

+    new_parms <- vector()

+

+    # New (sub)compartments (boxes) needed for the model type

+    new_boxes <- switch(spec[[varname]]$type,

+      SFO = varname,

+      SFORB = paste(varname, c("free", "bound"), sep="_")

+    )

+    map[[varname]] <- new_boxes

+

+    # Start a new differential equation for each new box

+    new_diffs <- paste("d_", new_boxes, " =", sep="")

+

+    # Construct terms for transfer to sink and add if appropriate

+    if(spec[[varname]]$sink) {

+      k_compound_sink <- paste("k", new_boxes[[1]], "sink", sep="_")

+      sink_term <- paste("-", k_compound_sink, "*", new_boxes[[1]])

+      # Only add sink term to first (or only) box for SFO and SFORB models

+      if(spec[[varname]]$type %in% c("SFO", "SFORB")) {

+        new_diffs[[1]] <- paste(new_diffs[[1]], sink_term)

+      }

+      new_parms <- k_compound_sink

+    }

+   

+    # Add reversible binding if appropriate

+    if(spec[[varname]]$type == "SFORB") {

+      k_free_bound <- paste("k", varname, "free", "bound", sep="_")      

+      k_bound_free <- paste("k", varname, "bound", "free", sep="_")      

+      reversible_binding_terms <- c(

+        paste("-", k_free_bound, "*", new_boxes[[1]], "+", k_bound_free, "*", new_boxes[[2]]),

+        paste("+", k_free_bound, "*", new_boxes[[1]], "-", k_bound_free, "*", new_boxes[[2]]))

+      new_diffs <- paste(new_diffs, reversible_binding_terms)

+      new_parms <- c(new_parms, k_free_bound, k_bound_free)

+    } 

+

+    # Add observed variable to model

+    parms <- c(parms, new_parms)

+    names(new_diffs) <- new_boxes

+    diffs <- c(diffs, new_diffs)

+  }

+

+  # Transfer between compartments

+  for (varname in names(spec)) {

+    to <- spec[[varname]]$to

+    if(!is.na(to)) {

+      origin_box <- switch(spec[[varname]]$type,

+        SFO = varname,

+        SFORB = paste(varname, "free", sep="_"))

+      for (target in to) {

+        target_box <- switch(spec[[target]]$type,

+          SFO = target,

+          SFORB = paste(target, "free", sep="_"))

+      }

+      k_from_to <- paste("k", origin_box, target_box, sep="_")

+      diffs[[origin_box]] <- paste(diffs[[origin_box]], "-", k_from_to, "*", origin_box)

+      diffs[[target_box]] <- paste(diffs[[target_box]], "+", k_from_to, "*", origin_box)

+      parms <- c(parms, k_from_to)

+    }

+  }

+  model <- list(diffs = diffs, parms = parms, map = map)

+  class(model) <- "mkinmod"

+  return(model)

+}

diff --git a/data/FOCUS_2006_datasets.RData b/data/FOCUS_2006_datasets.RData
new file mode 100644
index 0000000..eb9e526
--- /dev/null
+++ b/data/FOCUS_2006_datasets.RData
diff --git a/inst/doc/header.tex b/inst/doc/header.tex
new file mode 100644
index 0000000..9d6ec49
--- /dev/null
+++ b/inst/doc/header.tex
@@ -0,0 +1,31 @@
+\usepackage{booktabs}

+\usepackage{amsfonts}

+\usepackage{latexsym}

+\usepackage{amsmath}

+\usepackage{amssymb}

+\usepackage{graphicx}

+\usepackage{parskip}

+\usepackage[round]{natbib}

+\usepackage{amstext}

+\usepackage{hyperref}

+\usepackage[latin1]{inputenc}

+

+\newcommand{\Rpackage}[1]{{\normalfont\fontseries{b}\selectfont #1}}

+\newcommand{\Robject}[1]{\texttt{#1}}

+\newcommand{\Rclass}[1]{\textit{#1}}

+\newcommand{\Rcmd}[1]{\texttt{#1}}

+

+\newcommand{\RR}{\textsf{R}}

+

+\RequirePackage[T1]{fontenc}

+\RequirePackage{graphicx,ae,fancyvrb}

+\IfFileExists{upquote.sty}{\RequirePackage{upquote}}{}

+\usepackage{relsize}

+

+\DefineVerbatimEnvironment{Sinput}{Verbatim}{baselinestretch=1.05}

+\DefineVerbatimEnvironment{Soutput}{Verbatim}{fontfamily=courier,

+                                              baselinestretch=1.05,

+                                              fontshape=it,

+                                              fontsize=\relsize{-1}}

+\DefineVerbatimEnvironment{Scode}{Verbatim}{}  

+\newenvironment{Schunk}{}{}

diff --git a/inst/doc/mkin.Rnw b/inst/doc/mkin.Rnw
new file mode 100644
index 0000000..84ede0f
--- /dev/null
+++ b/inst/doc/mkin.Rnw
@@ -0,0 +1,155 @@
+%%\VignetteIndexEntry{Routines for fitting kinetic models with one or more state variables to chemical degradation data}

+%%VignetteDepends{FME}

+%%\usepackage{Sweave}

+\documentclass[12pt,a4paper]{article}

+\usepackage{a4wide}

+%%\usepackage[lists,heads]{endfloat}

+\input{header}

+\hypersetup{  

+  pdftitle = {mkin - Routines for fitting kinetic models with one or more state variables to chemical degradation data},

+  pdfsubject = {Manuscript},

+  pdfauthor = {Johannes Ranke},

+  colorlinks = {true},

+  linkcolor = {blue},

+  citecolor = {blue},

+  urlcolor = {red},

+  hyperindex = {true},

+  linktocpage = {true},

+}

+\SweaveOpts{engine=R, eps=FALSE, keep.source = TRUE}

+<<setup, echo = FALSE, results = hide>>=

+options(prompt = "R> ")

+options(SweaveHooks = list(

+  cex = function() par(cex.lab = 1.3, cex.axis = 1.3)))

+@

+\begin{document}

+\title{mkin -\\

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

+\author{\textbf{Johannes Ranke} \\

+%EndAName

+Product Safety \\

+Harlan Laboratories Ltd. \\

+Zelgliweg 1, CH--4452 Itingen, Switzerland}

+\maketitle

+

+\begin{abstract}

+In the regulatory evaluation of chemical substances like plant protection

+products (pesticides), biocides and other chemicals, degradation data play an

+important role. For the evaluation of pesticide degradation experiments, 

+detailed guidance has been developed, based on nonlinear optimisation. 

+The \RR{} add-on package \Rpackage{mkin} implements fitting some of the models

+recommended in this guidance from within R and calculates some statistical

+measures for data series within one or more compartments, for parent and

+metabolites.

+\end{abstract}

+

+

+\thispagestyle{empty} \setcounter{page}{0}

+

+\clearpage

+

+\tableofcontents

+

+\textbf{Key words}: Kinetics, FOCUS, nonlinear optimisation

+

+\section{Introduction}

+\label{intro}

+

+Many approaches are possible regarding the evaluation of chemical degradation

+data.  The \Rpackage{kinfit} package \citep{pkg:kinfit} in \RR{}

+\citep{rcore2010} implements the approach recommended in the kinetics report

+provided by the FOrum for Co-ordination of pesticide fate models and their

+USe \citep{FOCUS2006} for simple data series for one parent compound in one

+compartment.

+

+The \Rpackage{mkin} package \citep{pkg:mkin} extends this approach to data series

+with metabolites and more than one compartment and includes the possibility 

+for back reactions.

+

+\section{Example}

+\label{exam}

+

+In the following, requirements for data formatting are explained. Then the

+procedure for fitting the four kinetic models recommended by the FOCUS group

+to an example dataset for parent only given in the FOCUS kinetics report is

+illustrated.  The explanations are kept rather verbose in order to lower the

+barrier for \RR{} newcomers.

+

+\subsection{Data format}

+

+The following listing shows example dataset C from the FOCUS kinetics

+report as distributed with the \Rpackage{kinfit} package

+

+<<FOCUS_2006_C_data, echo=TRUE, eval=TRUE>>=

+library("mkin")

+FOCUS_2006_C

+@

+

+Note that the data needs to be in the format of a data frame containing a

+variable \Robject{name} specifying the observed variable, indicating the

+compound name and, if applicable, the compartment, a variable \Robject{time}

+containing sampling times, and a numeric variable \Robject{value} specifying

+the observed value of the variable. If a further variable \Robject{error} 

+is present, this will be used to give different weights to the data points 

+(the higher the error, the lower the weight, see the help page of the 

+\Robject{modCost} function of the \Rpackage{FME} package \citep{soetaert10}).

+Replicate measurements are not recorded in extra columns but simply appended,

+leading to multiple occurrences of the sampling times \Robject{time}.

+

+Small to medium size dataset can be conveniently entered directly as \RR{} code

+as shown in the following listing

+

+<<data_format, echo=TRUE>>=

+example_data <- data.frame(

+  time = c(0, 1, 3, 7, 14, 28, 63, 91, 119),

+  parent = c(85.1, 57.9, 29.9, 14.6, 9.7, 6.6, 4, 3.9, 0.6)

+)

+@

+

+\subsection{Model definition}

+

+The next task is to define the model to be fitted to the data. In order to

+facilitate this task, a convenience function \Robject{mkinmod} is available.

+

+<<model_definition, echo=TRUE>>=

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

+SFORB <- mkinmod(spec = list(parent = list(type = "SFORB", to = NA, sink = TRUE)))

+SFO_SFO <- mkinmod(spec = list(

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

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

+SFORB_SFO <- mkinmod(spec = list(

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

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

+@

+

+\subsection{Fitting the model}

+

+Then the model parameters should be fitted to the data. The function

+\Robject{mkinfit} internally creates a cost function using \Robject{modCost}

+from the \Rpackage{FME} package and the produces a fit using \Robject{modFit}

+from the same package.

+

+<<model_fitting, echo=TRUE>>=

+# Do not show significance stars as they interfere with vignette generation

+options(show.signif.stars = FALSE)

+SFO.fit <- mkinfit(SFO, FOCUS_2006_C)

+summary(SFO.fit)

+SFORB.fit <- mkinfit(SFORB, FOCUS_2006_C)

+summary(SFORB.fit)

+SFO_SFO.fit <- mkinfit(SFO_SFO, FOCUS_2006_D)

+summary(SFO_SFO.fit)

+SFO_SFO.fit.2 <- mkinfit(SFO_SFO, FOCUS_2006_D, 

+  fixed_initials = c(FALSE, FALSE), fixed_parms = c(FALSE, TRUE, FALSE))

+summary(SFO_SFO.fit.2)

+SFO_SFO.fit.3 <- mkinfit(SFO_SFO, FOCUS_2006_D, 

+  fixed_initials = c(FALSE, FALSE), fixed_parms = c(FALSE, TRUE, FALSE), lower = -0.0000001)

+summary(SFO_SFO.fit.3)

+SFORB_SFO.fit <- mkinfit(SFORB_SFO, FOCUS_2006_D)

+summary(SFORB_SFO.fit)

+@

+

+\bibliographystyle{plainnat}

+\bibliography{references}

+

+\end{document}

+% vim: set foldmethod=syntax:

diff --git a/inst/doc/mkin.pdf b/inst/doc/mkin.pdf
new file mode 100644
index 0000000..95c8a69
--- /dev/null
+++ b/inst/doc/mkin.pdf
diff --git a/inst/doc/references.bib b/inst/doc/references.bib
new file mode 100644
index 0000000..b158eeb
--- /dev/null
+++ b/inst/doc/references.bib
@@ -0,0 +1,55 @@
+@Manual{pkg:kinfit,

+    title = {kinfit: {R}outines for fitting simple kinetic models to chemical degradation data},

+    author = {Johannes Ranke},

+    year = {2010},

+    url = {http://CRAN.R-project.org}

+}

+

+@Manual{pkg:mkin,

+    title = {mkin: {R}outines for fitting kinetic models with one or more state variables to chemical degradation data},

+    author = {Johannes Ranke},

+    year = {2010},

+    url = {http://CRAN.R-project.org}

+}

+

+@Article{soetaert10,

+    title = {Inverse Modelling, Sensitivity and Monte Carlo Analysis in {R} Using Package {FME}},

+    author = {Karline Soetaert and Thomas Petzoldt},

+    journal = {Journal of Statistical Software},

+    year = {2010},

+    volume = {33},

+    number = {3},

+    pages = {1--28},

+    url = {http://www.jstatsoft.org/v33/i03/}

+}

+

+@Manual{          rcore2010,

+  title         = {\textsf{R}: A Language and Environment for Statistical

+                  Computing},

+  author        = {{R Development Core Team}},

+  organization  = {R Foundation for Statistical Computing},

+  address       = {Vienna, Austria},

+  year          = 2010,

+  note          = {{ISBN} 3-900051-07-0},

+  url           = {http://www.R-project.org}

+}

+

+@Manual{          FOCUS2006,

+  title         = {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},

+  note          = {EC Document Reference Sanco/10058/2005 version 2.0},

+  author        = {{FOCUS Work Group on Degradation Kinetics}},

+  year          = {2006},

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

+}

+

+@Inproceedings{   schaefer2007,

+  title         = {{KinGUI}: a new kinetic software tool for evaluations according to FOCUS degradation kinetics},

+  author       = {D. Sch\"{a}fer and M. Mikolasch and P. Rainbird and B. Harvey},

+  booktitle    = {Proceedings of the XIII Symposium Pesticide Chemistry},

+  editor       = {Del Re A. A. M. and Capri E. and Fragoulis G. and Trevisan M.},

+  year          = {2007},

+  address       = {Piacenza},

+  pages         = {916--923}

+}

diff --git a/inst/doc/run.bat b/inst/doc/run.bat
new file mode 100644
index 0000000..c28c666
--- /dev/null
+++ b/inst/doc/run.bat
@@ -0,0 +1,5 @@
+R.exe -e "Sweave('mkin.Rnw', stylepath=FALSE)"

+pdflatex.exe mkin

+bibtex.exe mkin

+pdflatex.exe mkin

+pdflatex.exe mkin

diff --git a/inst/unitTests/Makefile b/inst/unitTests/Makefile
new file mode 100644
index 0000000..8d13225
--- /dev/null
+++ b/inst/unitTests/Makefile
@@ -0,0 +1,15 @@
+TOP=../..
+PKG=${shell cd ${TOP};pwd}
+SUITE=doRUnit.R
+R=R
+
+all: inst test
+
+inst: # Install package
+	cd ${TOP}/..;\
+	${R} CMD INSTALL ${PKG}
+
+test: # Run unit tests
+	export RCMDCHECK=FALSE;\
+	cd ${TOP}/tests;\
+	${R} --vanilla --slave < ${SUITE}
diff --git a/inst/unitTests/runit.mkinmod.R b/inst/unitTests/runit.mkinmod.R
new file mode 100644
index 0000000..b6ca6b8
--- /dev/null
+++ b/inst/unitTests/runit.mkinmod.R
@@ -0,0 +1,53 @@
+test.mkinmod.SFO <- function()

+{  

+  SFO.diffs <- c(

+    parent = "d_parent = - k_parent_sink * parent"

+  )

+  SFO.parms <- c("k_parent_sink")

+  SFO.map <- list(parent = "parent")

+  SFO <- list(diffs = SFO.diffs, parms = SFO.parms, map = SFO.map)

+  class(SFO) <- "mkinmod"

+  SFO.mkinmod <- mkinmod(spec = list(

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

+  )

+  checkIdentical(SFO, SFO.mkinmod)

+}

+

+test.mkinmod.SFORB <- function()

+{  

+  SFORB.diffs <- c(

+    parent_free = paste(

+      "d_parent_free = - k_parent_free_sink * parent_free", 

+        "- k_parent_free_bound * parent_free",

+        "+ k_parent_bound_free * parent_bound"),

+    parent_bound = paste(

+      "d_parent_bound =",

+        "+ k_parent_free_bound * parent_free",

+        "- k_parent_bound_free * parent_bound")

+  )

+  SFORB.parms <- c("k_parent_free_sink", "k_parent_free_bound", "k_parent_bound_free")

+  SFORB.map <- list(parent = c("parent_free", "parent_bound"))

+  SFORB <- list(diffs = SFORB.diffs, parms = SFORB.parms, map = SFORB.map)

+  class(SFORB) <- "mkinmod"

+  SFORB.mkinmod <- mkinmod(spec = list(

+    parent = list(type = "SFORB", to = NA, sink=TRUE))

+  )

+  checkIdentical(SFORB, SFORB.mkinmod)

+}

+

+test.mkinmod.SFO_SFO <- function()

+{  

+  SFO_SFO.diffs <- c(

+    parent = "d_parent = - k_parent_sink * parent - k_parent_m1 * parent",

+    m1 = "d_m1 = - k_m1_sink * m1 + k_parent_m1 * parent"

+  )

+  SFO_SFO.parms <- c("k_parent_sink", "k_m1_sink", "k_parent_m1")

+  SFO_SFO.map <- list(parent = "parent", m1 = "m1")

+  SFO_SFO <- list(diffs = SFO_SFO.diffs, parms = SFO_SFO.parms, map = SFO_SFO.map)

+  class(SFO_SFO) <- "mkinmod"

+  SFO_SFO.mkinmod <- mkinmod(spec = list(

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

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

+  )

+  checkIdentical(SFO_SFO, SFO_SFO.mkinmod)

+}

diff --git a/man/FOCUS_2006_datasets.Rd b/man/FOCUS_2006_datasets.Rd
new file mode 100644
index 0000000..04565f7
--- /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 0000000..7ddc10c
--- /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 0000000..4569b31
--- /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 }

diff --git a/tests/doRUnit.R b/tests/doRUnit.R
new file mode 100644
index 0000000..e2ad4cd
--- /dev/null
+++ b/tests/doRUnit.R
@@ -0,0 +1,58 @@
+if(require("RUnit", quietly=TRUE)) {
+ 
+  ## --- Setup ---
+ 
+  pkg <- "mkin" # <-- Change to package name!
+  if(Sys.getenv("RCMDCHECK") == "FALSE") {
+    ## Path to unit tests for standalone running under Makefile (not R CMD check)
+    ## PKG/tests/../inst/unitTests
+    path <- file.path(getwd(), "..", "inst", "unitTests")
+  } else {
+    ## Path to unit tests for R CMD check
+    ## PKG.Rcheck/tests/../PKG/unitTests
+    path <- system.file(package=pkg, "unitTests")
+  }
+  cat("\nRunning unit tests\n")
+  print(list(pkg=pkg, getwd=getwd(), pathToUnitTests=path))
+ 
+  library(package=pkg, character.only=TRUE)
+ 
+  ## If desired, load the name space to allow testing of private functions
+  ## if (is.element(pkg, loadedNamespaces()))
+  ##     attach(loadNamespace(pkg), name=paste("namespace", pkg, sep=":"), pos=3)
+  ##
+  ## or simply call PKG:::myPrivateFunction() in tests
+ 
+  ## --- Testing ---
+ 
+  ## Define tests
+  testSuite <- defineTestSuite(name=paste(pkg, " Unit Tests"),
+                                          dirs=path)
+  ## Run
+  tests <- runTestSuite(testSuite)
+ 
+  ## Default report name
+  pathReport <- file.path(path, "report")
+ 
+  ## Report to stdout and text files
+  cat("------------------- UNIT TEST SUMMARY ---------------------\n\n")
+  printTextProtocol(tests, showDetails=FALSE)
+  printTextProtocol(tests, showDetails=FALSE,
+                    fileName=paste(pathReport, "Summary.txt", sep=""))
+  printTextProtocol(tests, showDetails=TRUE,
+                    fileName=paste(pathReport, ".txt", sep=""))
+ 
+  ## Report to HTML file
+  printHTMLProtocol(tests, fileName=paste(pathReport, ".html", sep=""))
+ 
+  ## Return stop() to cause R CMD check stop in case of
+  ##  - failures i.e. FALSE to unit tests or
+  ##  - errors i.e. R errors
+  tmp <- getErrors(tests)
+  if(tmp$nFail > 0 | tmp$nErr > 0) {
+    stop(paste("\n\nunit testing failed (#test failures: ", tmp$nFail,
+               ", #R errors: ",  tmp$nErr, ")\n\n", sep=""))
+  }
+} else {
+  warning("cannot run unit tests -- package RUnit is not available")
+}