From c1144753adfa0809003085009ebd85f8af9beda8 Mon Sep 17 00:00:00 2001 From: jranke Date: Tue, 10 Apr 2012 21:50:22 +0000 Subject: - 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 --- vignettes/mkin.Rnw | 164 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 vignettes/mkin.Rnw (limited to 'vignettes/mkin.Rnw') diff --git a/vignettes/mkin.Rnw b/vignettes/mkin.Rnw new file mode 100644 index 00000000..1eebd44a --- /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} +<>= +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 + +<>= +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 + +<>= +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. + +<>= +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}. + +<>= +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: -- cgit v1.2.1