diff options
Diffstat (limited to 'README.Rmd')
| -rw-r--r-- | README.Rmd | 212 |
1 files changed, 212 insertions, 0 deletions
diff --git a/README.Rmd b/README.Rmd new file mode 100644 index 00000000..a4723052 --- /dev/null +++ b/README.Rmd @@ -0,0 +1,212 @@ +# mkin + +The R package **mkin** provides calculation routines for the analysis of +chemical degradation data, including <b>m</b>ulticompartment <b>kin</b>etics 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](http://cran.r-project.org/package=mkin) from within R: + +```{r, eval = FALSE} +install.packages("mkin") +``` + +If looking for the latest features, you can install directly from +[github](http://github.com/jranke/mkin), e.g. using the `devtools` package. +Using `quick = TRUE` skips docs, multiple-architecture builds, demos, and +vignettes, to make installation as fast and painless as possible. + +```{r, eval = FALSE} +require(devtools) +install_github("jranke/mkin", quick = TRUE) +``` + +## 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 + +The simplest usage example that I can think of, using model shorthand notation +(available since mkin 0.9-32) and a built-in dataset is + +```{r} +library(mkin) +fit <- mkinfit("SFO", FOCUS_2006_C, quiet = TRUE) +plot(fit, show_residuals = TRUE) +``` + +```{r, eval = FALSE} +# Output not shown in this README to avoid distraction +summary(fit) +``` + +A still very simple usage example including the definition of the same data in R +code would be + +```{r} +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) +) +fit2 <- mkinfit("FOMC", example_data, quiet = TRUE) +plot(fit2, show_residuals = TRUE) +``` + +A fairly complex usage example using another built-in dataset: + +```{r echo = FALSE} +# Somehow knitr does not find the signature() function +require(methods) +``` + +```{r} +data <- mkin_wide_to_long(schaefer07_complex_case, time = "time") + +model <- mkinmod( + parent = mkinsub("SFO", c("A1", "B1", "C1"), sink = FALSE), + A1 = mkinsub("SFO", "A2"), + B1 = mkinsub("SFO"), + C1 = mkinsub("SFO"), + A2 = mkinsub("SFO"), use_of_ff = "max") + +fit3 <- mkinfit(model, data, method.modFit = "Port") + +plot(fit3, show_residuals = TRUE) +#summary(fit3) # Commented out to avoid distraction from README content +mkinparplot(fit3) +``` + +For more examples and to see results, have a look at the examples provided in the +[`mkinfit`](http://kinfit.r-forge.r-project.org/mkin_static/mkinfit.html) +documentation or the package vignettes referenced from the +[mkin package documentation page](http://kinfit.r-forge.r-project.org/mkin_static/index.html) + +## Features + +* Highly flexible model specification using + [`mkinmod`](http://kinfit.r-forge.r-project.org/mkin_static/mkinmod.html), + 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. +* Model solution (forward modelling) in the function + [`mkinpredict`](http://kinfit.r-forge.r-project.org/mkin_static/mkinpredict.html) + 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`). + These have decreasing efficiency, and are automatically chosen + by default. +* As of mkin 0.9-36, model solution for models with more than one observed + variable is based on the + [`ccSolve`](https://github.com/karlines/ccSolve) package, if installed. + This is even faster than eigenvalue based solution, at least in the example + shown in the [vignette `compiled_models`](http://rawgit.com/jranke/mkin/master/vignettes/compiled_models.html) +* Model optimisation with + [`mkinfit`](http://kinfit.r-forge.r-project.org/mkin_static/mkinfit.html) + internally using the `modFit` function from the `FME` package, + but using the Port routine `nlminb` per default. +* By default, kinetic rate constants and kinetic formation fractions are + transformed internally using + [`transform_odeparms`](http://kinfit.r-forge.r-project.org/mkin_static/transform_odeparms.html) + 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. +* 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. +* I recently added iteratively reweighted least squares in a similar way + it is done 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, + either IORE kinetics or SFORB kinetics can be used for the metabolite, + adding one respectively two parameters to the system. + +## GUI + +There is a graphical user interface that I consider useful for real work. Please +refer to its [documentation page](http://kinfit.r-forge.r-project.org/gmkin_static) +for installation instructions and a manual. + +## News + +Yes, there is a . + +## Credits and historical remarks + +`mkin` would not be possible without the underlying software stack consisting +of R and the packages [deSolve](http://cran.r-project.org/package=deSolve), +[minpack.lm](http://cran.r-project.org/package=minpack.lm) and +[FME](http://cran.r-project.org/package=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](http://focus.jrc.ec.europa.eu/dk), +as detailed in their guidance document from 2006, slightly updated in 2011. + +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](http://kinfit.r-forge.r-project.org/kinfit_static/index.html) was +[started in 2008](https://r-forge.r-project.org/scm/viewvc.php?view=rev&root=kinfit&revision=2) and +[first published](http://cran.r-project.org/src/contrib/Archive/kinfit/) on +CRAN on 01 May 2010. + +The first `mkin` code was +[published on 11 May 2010](https://r-forge.r-project.org/scm/viewvc.php?view=rev&root=kinfit&revision=8) and the +[first CRAN version](http://cran.r-project.org/src/contrib/Archive/mkin) +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](http://projects.tessella.com/cake), where you can also +find a zip archive of the R scripts derived from `mkin`, published under the GPL +license. + +Finally, there is +[KineticEval](http://github.com/zhenglei-gao/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](https://help.github.com/articles/fork-a-repo) 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](http://r-forge.r-project.org/R/?group_id=615) are welcome as well. +Generally, the source code of the latest CRAN version should be available there. |