mkin

- -

The R package mkin provides calculation routines for the analysis of -chemical degradation data, including multicompartment kinetics as -needed for modelling the formation and decline of transformation products, or -if several compartments are involved.

- -

Installation

- -

You can install the latest released version from -CRAN from within R:

- -

install.packages("mkin")
-

- -

Background

- -

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 and helpful tools have been developed as detailed in -'Credits and historical remarks' below.

- -

Usage

- -

For a start, have a look a the code examples provided for -plot.mkinfit -and -plot.mmkin, and -at the package vignettes -FOCUS L and -FOCUS D.

- -

Documentation

- -

The HTML documentation is -maintained at the R-Forge project site.

- -

Features

- -

Highly flexible model specification using -mkinmod, -including equilibrium reactions and using the single first-order -reversible binding (SFORB) model, which will automatically create -two latent state variables for the observed variable.
As of version 0.9-39, fitting of several models to several datasets, optionally in -parallel, is supported, see for example -plot.mmkin.
Model solution (forward modelling) in the function -mkinpredict -is performed either using the analytical solution for the case of -parent only degradation, an eigenvalue based solution if only simple -first-order (SFO) or SFORB kinetics are used in the model, or -using a numeric solver from the deSolve package (default is lsoda).
If a C compiler is installed, the kinetic models are compiled from automatically -generated C code, see
-vignette compiled_models. -The autogeneration of C code was -inspired by the ccSolve package. Thanks -to Karline Soetaert for her work on that.
By default, kinetic rate constants and kinetic formation fractions are -transformed internally using -transform_odeparms -so their estimators can more reasonably be expected to follow -a normal distribution. This has the side effect that no constraints -are needed in the optimisation. Thanks to René Lehmann for the nice -cooperation on this, especially the isometric logration transformation -that is now used for the formation fractions.
A side effect of this is that when parameter estimates are backtransformed -to match the model definition, confidence intervals calculated from -standard errors are also backtransformed to the correct scale, and will -not include meaningless values like negative rate constants or -formation fractions adding up to more than 1, which can not occur in -a single experiment with a single defined radiolabel position.
The usual one-sided t-test for significant difference from zero is nevertheless -shown based on estimators for the untransformed parameters.
Summary and plotting functions. The summary of an mkinfit object is in -fact a full report that should give enough information to be able to -approximately reproduce the fit with other tools.
The chi-squared error level as defined in the FOCUS kinetics guidance -(see below) is calculated for each observed variable.
Iteratively reweighted least squares fitting is implemented in a similar way -as in KinGUII and CAKE (see below). Simply add the argument -reweight = "obs" to your call to mkinfit and a separate variance -componenent for each of the observed variables will be optimised -in a second stage after the primary optimisation algorithm has converged.
When a metabolite decline phase is not described well by SFO kinetics, -SFORB kinetics can be used for the metabolite.

- -

GUI

- -

There is a graphical user interface that I consider useful for real work. Please -refer to its documentation page -for installation instructions and a manual.

- -

News

- -

Yes, there is a ChangeLog, for the latest CRAN release -and one for the github master branch.

- -

Credits and historical remarks

- -

mkin would not be possible without the underlying software stack consisting -of R and the packages deSolve -and FME, to say the least.

- -

It could not have been written without me being introduced to regulatory fate -modelling of pesticides by Adrian Gurney during my time at Harlan Laboratories -Ltd (formerly RCC Ltd). mkin greatly profits from and largely follows -the work done by the -FOCUS Degradation Kinetics Workgroup, -as detailed in their guidance document from 2006, slightly updated in 2011 and -2014.

- -

Also, it was inspired by the first version of KinGUI developed by -BayerCropScience, which is based on the MatLab runtime environment.

- -

The companion package -kinfit (now deprecated) was -started in 2008 and -first published on -CRAN on 01 May 2010.

- -

The first mkin code was -published on 11 May 2010 and the -first CRAN version -on 18 May 2010.

- -

In 2011, Bayer Crop Science started to distribute an R based successor to KinGUI named -KinGUII whose R code is based on mkin, but which added, amongst other -refinements, a closed source graphical user interface (GUI), iteratively -reweighted least squares (IRLS) optimisation of the variance for each of the -observed variables, and Markov Chain Monte Carlo (MCMC) simulation -functionality, similar to what is available e.g. in the FME package.

- -

Somewhat in parallel, Syngenta has sponsored the development of an mkin and -KinGUII based GUI application called CAKE, which also adds IRLS and MCMC, is -more limited in the model formulation, but puts more weight on usability. -CAKE is available for download from the CAKE -website, where you can also -find a zip archive of the R scripts derived from mkin, published under the GPL -license.

- -

Finally, there is -KineticEval, which contains -a further development of the scripts used for KinGUII, so the different tools -will hopefully be able to learn from each other in the future as well.

- -

Development

- -

Contributions are welcome! Your -mkin fork is just a mouse click -away… The master branch on github should always be in good shape, I implement -new features in separate branches now. If you prefer subversion, project -members for the -r-forge project are welcome as well. -Generally, the source code of the latest CRAN version should be available there. -You can also browse the source code at cgit.jrwb.de/mkin.

- - -

Help topics

- -

Main functions

Essential functionality

- - -

- mkinmod
Function to set up a kinetic model with one or more state variables -
- mkinfit
Fit a kinetic model to data with one or more state variables -
- mmkin
Fit one or more kinetic models with one or more state variables to one or more datasets -

Show results

Functions working on mkinfit objects

- - -

- plot.mkinfit(plot_sep)
Plot the observed data and the fitted model of an mkinfit object -
- summary.mkinfit(print.summary.mkinfit)
Summary method for class "mkinfit" -
- mkinresplot
Function to plot residuals stored in an mkin object -
- mkinparplot
Function to plot the confidence intervals obtained using -
- endpoints
Function to calculate endpoints for further use from kinetic models fitted with mkinfit -
- mkinerrmin
Calculate the minimum error to assume in order to pass the variance test -

Work with mmkin objects

Functions working with aggregated results

- - -

- [.mmkin
Subsetting method for mmkin objects
- plot.mmkin
Plot model fits (observed and fitted) and the residuals for a row or column of an mmkin object -

Datasets and known results

- - -

- FOCUS_2006_datasets(FOCUS_2006_A, FOCUS_2006_B, FOCUS_2006_C, FOCUS_2006_D, FOCUS_2006_E, FOCUS_2006_F)
Datasets A to F from the FOCUS Kinetics report from 2006 -
- FOCUS_2006_SFO_ref_A_to_F
Results of fitting the SFO model to Datasets A to F of FOCUS (2006) -
- FOCUS_2006_FOMC_ref_A_to_F
Results of fitting the FOMC model to Datasets A to F of FOCUS (2006) -
- FOCUS_2006_HS_ref_A_to_F
Results of fitting the HS model to Datasets A to F of FOCUS (2006) -
- FOCUS_2006_DFOP_ref_A_to_B
Results of fitting the DFOP model to Datasets A to B of FOCUS (2006) -
- mccall81_245T
Datasets on aerobic soil metabolism of 2,4,5-T in six soils -
- schaefer07_complex_case(schaefer07_complex_results)
Metabolism data set used for checking the software quality of KinGUI -
- synthetic_data_for_UBA_2014
Synthetic datasets for one parent compound with two metabolites -

Helper functions

- - -

- mkin_wide_to_long
Convert a dataframe with observations over time into long format -
- mkin_long_to_wide
Convert a dataframe from long to wide format -
- mkinsub
Function to set up a kinetic submodel for one state variable -
- mkinds
A dataset class for mkin
- print.mkinds
Print mkinds objects -
- print.mkinmod
Print mkinmod objects -
- mkinpredict
Produce predictions from a kinetic model using specific parameters -
- transform_odeparms(backtransform_odeparms)
Functions to transform and backtransform kinetic parameters for fitting -
- ilr(invilr)
Function to perform isometric log-ratio transformation -
- geometric_mean
Calculate the geometric mean

Analytical solutions

Parent only model solutions

- - -

- SFO.solution
Single First-Order kinetics
- FOMC.solution
First-Order Multi-Compartment kinetics
- DFOP.solution
Double First-Order in Parallel kinetics -
- SFORB.solution
Single First-Order Reversible Binding kinetics
- HS.solution
Hockey-Stick kinetics
- IORE.solution
Indeterminate order rate equation kinetics

Deprecated functions

Functions that have been superseeded

- - -

- mkinplot
Plot the observed data and the fitted model of an mkinfit object -

Other

- - -

- add_err
Add normally distributed errors to simulated kinetic degradation data -

- -

Vignettes

- -

Dependencies

Depends: minpack.lm, rootSolve, inline, parallel
Imports: stats, graphics, methods, FME, deSolve, R6
Suggests: knitr, testthat, microbenchmark, ggplot2

Authors

Johannes Ranke [aut, cre, cph]
Katrin Lindenberger [ctb]
René Lehmann [ctb]
Eurofins Regulatory AG [cph]

- -