diff options
Diffstat (limited to 'inst')
| -rw-r--r-- | inst/doc/header.tex | 31 | ||||
| -rw-r--r-- | inst/doc/mkin.Rnw | 155 | ||||
| -rw-r--r-- | inst/doc/mkin.pdf | bin | 0 -> 172301 bytes | |||
| -rw-r--r-- | inst/doc/references.bib | 55 | ||||
| -rw-r--r-- | inst/doc/run.bat | 5 | ||||
| -rw-r--r-- | inst/unitTests/Makefile | 15 | ||||
| -rw-r--r-- | inst/unitTests/runit.mkinmod.R | 53 |
7 files changed, 314 insertions, 0 deletions
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 Binary files differnew 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)
+}
|