diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 182 |
1 files changed, 21 insertions, 161 deletions
@@ -1,121 +1,23 @@ -# mkin +# gmkin -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. +The R package **gmkin** provides a browser based graphical user interface (GUI) for +fitting kinetic models to chemical degradation data based on R package +[mkin](http://github.com/jranke/mkin). The GUI is based on the +[gWidgetsWWW2](http://github.com/jverzani/gWidgetsWWW2) package developed by +John Verzani. The GUI elements are created by the JavaScript library +ExtJS which is bundled with gWidgetsWWW2. ## Installation -You can install the latest released version from -[CRAN](http://cran.r-project.org/package=mkin) from within R: - -```s -install.packages('mkin') -``` - -A development version is usually available from [R-Forge](http://r-forge.r-project.org/R/?group_id=615): - -```s -install.packages('mkin', repos = 'http://r-forge.r-project.org') -``` - -If R-Forge is lacking behind or if you prefer, you can install directly from -github using the `devtools` package. - ```s require(devtools) -install_github("mkin", "jranke", quick = TRUE) # quick = TRUE avoids vignette rebuilds +install_github("gWidgetsWWW2", "jverzani") ``` -## 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 - -A very simple usage example would be - - library("mkin") - 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) - ) - SFO <- mkinmod(parent = list(type = "SFO")) - SFO.fit <- mkinfit(SFO, example_data) - summary(SFO.fit) - plot(SFO.fit) - -For more examples 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. -* Model optimisation with - [`mkinfit`](http://kinfit.r-forge.r-project.org/mkin_static/mkinfit.html) - internally using the `modFit` function from the `FME` package, - which uses the least-squares Levenberg-Marquardt algorithm from - `minpack.lm` per 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 isotropic 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. - -## GUI - -There is a graphical user interface that I consider useful for real work. It -depends on the gWidgetsWWW2 package from John Verzani which also lives on -github. Installing gWidgetsWWW2 yields a lot of warnings concerning overly -long path names. This is because the JavaScript library ExtJS is installed +Installing gWidgetsWWW2 yields a lot of warnings concerning overly long path +names. This is because the JavaScript library ExtJS is installed along with it which has lots of files with long paths to be installed. - -```s -require(devtools) -install_github("gWidgetsWWW2", "jverzani") -``` - You start the GUI from your R terminal with latest mkin installed as shown below. You may also want to adapt the browser that R starts (using `options(browser="/usr/bin/firefox")` on linux, or setting the default browser @@ -138,57 +40,15 @@ save(FOCUS_2006_Z_gmkin, file = "FOCUS_2006_gmkin_Z.RData") ```  - -## 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 ther 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 on -CRAN](http://cran.r-project.org/src/contrib/Archive/kinfit/) 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. - -After this, Bayer has developed 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. - - -## Contribute -Contributions are welcome! Your [mkin fork](https://help.github.com/articles/fork-a-repo) is just a mouse click away... This git repository is now the -master branch, but I figured out how to merge changes in both directions, -thanks to [this blog entry](http://cameron.bracken.bz/git-with-r-forge) -by Cameron Bracken, so contributors from r-forge are welcome as well. +## Status and known issues + +- Starting the GUI takes some time. Once it is started, it is reasonably responsive. +- Do not delete the last dataset or the last model from the respective lists, + this is not supported. +- The fit list is not always updated when using Firefox version 28 on Windows. This + works with Firefox 29 and with Chrome. +- gmkin was developed in the hope that it will be useful. However, no warranty can be + given that it will meet your expectations. There may be bugs, so please be + careful, check your results for plausibility and use your own expertise to judge + yourself. |