Convert main vignette to Rmd/html, add_err(), fixes

1 files changed, 167 insertions, 0 deletions

diff --git a/vignettes/mkin.Rmd b/vignettes/mkin.Rmd
new file mode 100644
index 00000000..63d97c6b
--- /dev/null
+++ b/vignettes/mkin.Rmd
@@ -0,0 +1,167 @@
+---
+title: mkin - Kinetic evaluation of chemical degradation data
+author: Johannes Ranke
+date: "`r Sys.Date()`"
+output:
+  html_document:
+    toc: true
+    toc_float: true
+bibliography: references.bib
+vignette: >
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteIndexEntry{mkin - Kinetic evaluation of chemical degradation data}
+  \usepackage[utf8]{inputenc}
+---
+
+[Wissenschaftlicher Berater, Kronacher Str. 8, 79639 Grenzach-Wyhlen, Germany](http://www.jrwb.de)<br />
+[Privatdozent at the University of Bremen](http://chem.uft.uni-bremen.de/ranke)
+
+```{r, include = FALSE}
+require(knitr)
+opts_chunk$set(engine='R', tidy=FALSE)
+```
+
+# 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 `R` add-on package `mkin` [@pkg: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.
+
+# Background
+
+Many approaches are possible regarding the evaluation of chemical degradation
+data.  
+
+The now deprecated `kinfit` package [@pkg:kinfit] in `R` [@rcore2016]
+implements the approach recommended in the kinetics report provided by the
+FOrum for Co-ordination of pesticide fate models and their USe [@FOCUS2006;
+FOCUSkinetics2014] for simple data series for one parent compound in one
+compartment.
+
+The `mkin` package [@pkg:mkin] extends this approach to data series with
+transformation products, commonly termed metabolites, and to more than one
+compartment. It is also possible to include back reactions, so equilibrium
+reactions and equilibrium partitioning can be specified, although this
+oftentimes leads to an overparameterisation of the model.
+
+When mkin was first published, the most commonly used tools for
+fitting more complex kinetic degradation models to experimental data were
+KinGUI [@schaefer2007], a MATLAB based tool with a graphical user
+interface that was specifically tailored to the task and included some output
+as proposed by the FOCUS Kinetics Workgroup, and ModelMaker, a general purpose
+compartment based tool providing infrastructure for fitting dynamic simulation
+models based on differential equations to data.
+
+The code was first uploaded to the BerliOS platform. When this was taken down,
+the version control history was imported into the R-Forge site, where the code
+is still mirrored today (see *e.g.* 
+[the initial commit on 11 May 2010](http://cgit.jrwb.de/mkin/commit/?id=30cbb4092f6d2d3beff5800603374a0d009ad770).
+
+At that time, the R package `FME` (Flexible Modelling Environment) 
+[@soetaert2010] was already available, and provided a good basis for
+developing a package specifically tailored to the task. The remaining challenge
+was to make it as easy as possible for the users (including the author of this
+vignette) to specify the system of differential equations and to include the
+output requested by the FOCUS guidance, such as the relative standard deviation
+that has to be assumed for the residuals, such that the $\chi^2$
+goodness-of-fit test as defined by the FOCUS kinetics workgroup would pass
+using an significance level $\alpha$ of 0.05.
+
+Also, mkin introduced using analytical solutions for parent only kinetics for
+improved optimization speed. Later, Eigenvalue based solutions were
+introduced to mkin for the case of linear differential equations (*i.e.*
+where the FOMC or DFOP models were not used for the parent compound), greatly
+improving the optimization speed for these cases.
+
+The possibility to specify back-reactions and a biphasic model (SFORB) for
+metabolites were present in mkin from the very beginning.
+
+## Derived software tools
+
+Soon after the publication of mkin, two derived tools were published, namely
+KinGUII (available from Bayer Crop Science) and CAKE (commissioned to Tessella
+by Syngenta), which added a graphical user interface (GUI), and added fitting by
+iteratively reweighted least squares (IRLS) and characterisation of likely
+parameter distributions by Markov Chain Monte Carlo (MCMC) sampling.
+
+CAKE focuses on a smooth use experience, sacrificing some flexibility in the model
+definition, originally allowing only two primary metabolites in parallel.
+The current version 3.2 of CAKE release in March 2016 uses a basic scheme for
+up to six metabolites in a flexible arrangement.
+
+KinGUI offers quite an even more flexible widget for specifying complex kinetic
+models.  Back-reactions (non-instanteneous equilibria) were not present in the
+first version of KinGUII, and only simple first-order models could be specified
+for transformation products.  Later, starting from KinGUII version 2.1 published in ),
+back-reactions and biphasic modelling of metabolites were also available in
+KinGUII.
+
+A further graphical user interface (GUI) that has recently been brought to a decent 
+degree of maturity is the browser based GUI named `gmkin`. Please see its 
+[documentation page](http://kinfit.r-forge.r-project.org/gmkin_static) and 
+[manual](http://kinfit.r-forge.r-project.org/gmkin_static/vignettes/gmkin_manual.html)
+for further information.
+
+## Recent developments
+
+Currently (June 2016), the main features available in `mkin` which are
+not present in KinGUII or CAKE, are the speed increase by using compiled code when 
+a compiler is present, parallel model fitting on multicore machines using the
+`mmkin` function, and the estimation of parameter confidence intervals based on
+transformed parameters. These are explained in more detail below.
+
+# Internal parameter transformations
+
+For rate constants, the log
+transformation is used, as proposed by Bates and Watts [-@bates1988, p. 77,
+149]. Approximate intervals are constructed for the transformed rate
+constants [compare @bates1988, p. 135], *i.e.* for their logarithms.
+Confidence intervals for the rate constants are then obtained using the
+appropriate backtransformation using the exponential function.
+
+In the first version of `mkin` allowing for specifying models using 
+formation fractions, a home-made reparameterisation was used in order to ensure
+that the sum of formation fractions would not exceed unity. 
+
+This method is still used in the current version of KinGUII (v2.1 from April
+2014), with a modification that allows for fixing the pathway to sink to zero.
+CAKE uses penalties in the objective function in order to enforce this
+constraint.
+
+In 2012, an alternative reparameterisation of the formation fractions was
+proposed together with René Lehmann \citep{ranke2012}, based on isometric
+logratio transformation (ILR). The aim was to improve the validity of the
+linear approximation of the objective function during the parameter
+estimation procedure as well as in the subsequent calculation of parameter
+confidence intervals.
+
+In the first attempt at providing improved parameter confidence intervals
+introduced to \Rpackage{mkin} in 2013, confidence intervals obtained from 
+FME on the transformed parameters were simply all backtransformed one by one
+to yield asymetric confidence intervals for the backtransformed parameters.
+
+However, while there is a 1:1 relation between the rate constants in the model
+and the transformed parameters fitted in the model, the parameters obtained by the
+isometric logratio transformation are calculated from the set of formation
+fractions that quantify the paths to each of the compounds formed from a
+specific parent compound, and no such 1:1 relation exists.
+
+Therefore, parameter confidence intervals for formation fractions obtained with
+this method only appear valid for the case of a single transformation product, where 
+only one formation fraction is to be estimated, directly corresponding to one
+component of the ilr transformed parameter.
+
+The confidence intervals obtained by backtransformation for the cases where a 
+1:1 relation between transformed and original parameter exist are considered by 
+the author of this vignette to be more accurate than those obtained using a
+re-estimation of the Hessian matrix after backtransformation, as implemented 
+in the FME package.
+
+
+# References
+
+<!-- vim: set foldmethod=syntax: -->