- Fitting and summaries now work with the new parameter transformations.

- The SFORB models with metabolites is broken (see TODO)
- Moved the vignette to the location recommended since R 2.14
- Added the missing documentation
- Commented out the schaefer_complex_case test, as this version of
  mkin is not able to fit a model without sink and therefore 
  mkin estimated parameters are quite different




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

1 files changed, 164 insertions, 0 deletions

diff --git a/vignettes/mkin.Rnw b/vignettes/mkin.Rnw
new file mode 100644
index 0000000..1eebd44
--- /dev/null
+++ b/vignettes/mkin.Rnw
@@ -0,0 +1,164 @@
+% $Id: mkin.Rnw 66 2010-09-03 08:50:26Z jranke $

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

+Eurofins Regulatory AG\\

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

+and\\

+University of Bremen\\

+}

+\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{mkin} 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(

+  name = rep("parent", 9),

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

+  value = 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(parent = list(type = "SFO"))

+SFORB <- mkinmod(parent = list(type = "SFORB"))

+SFO_SFO <- mkinmod(

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

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

+SFORB_SFO <- mkinmod(

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

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

+@

+

+The model definitions given above define sets of linear first-order ordinary

+differential equations. In these cases, a coefficient matrix is also returned.

+

+Other models that include time on the right-hand side of the differential 

+equation are the first-order multi-compartment (FOMC) model and the

+Hockey-Stick (HS) model. At present, only the FOMC model can only be used, and

+only for the parent compound.

+

+\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. In cases of linear first-order differential 

+equations, the solution used for calculating the cost function is based

+on the fundamental system of the coefficient matrix, as proposed by 

+\citet{bates88}.

+

+<<model_fitting, echo=TRUE>>=

+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, plot=TRUE)

+summary(SFO_SFO.fit, data=FALSE)

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

+#  parms.ini = c(f_parent_to_m1 = 0.5, k_m1 = 0.2), 

+#  plot=TRUE)

+#summary(SFORB_SFO.fit, data=FALSE)

+@

+

+\bibliographystyle{plainnat}

+\bibliography{references}

+

+\end{document}

+% vim: set foldmethod=syntax: