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

1 files changed, 155 insertions, 0 deletions

diff --git a/inst/doc/mkin.Rnw b/inst/doc/mkin.Rnw
new file mode 100644
index 00000000..84ede0f5
--- /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: