diff options
| -rw-r--r-- | .Rbuildignore | 1 | ||||
| -rw-r--r-- | GNUmakefile | 4 | ||||
| -rw-r--r-- | README.Rmd | 217 | ||||
| -rw-r--r-- | README.md | 95 | ||||
| -rw-r--r-- | figure/unnamed-chunk-3-1.png | bin | 7626 -> 0 bytes | |||
| -rw-r--r-- | figure/unnamed-chunk-5-1.png | bin | 8055 -> 0 bytes | |||
| -rw-r--r-- | figure/unnamed-chunk-6-1.png | bin | 28887 -> 0 bytes | |||
| -rw-r--r-- | figure/unnamed-chunk-6-2.png | bin | 6533 -> 0 bytes | |||
| -rw-r--r-- | figure/unnamed-chunk-7-1.png | bin | 28887 -> 0 bytes | |||
| -rw-r--r-- | figure/unnamed-chunk-7-2.png | bin | 6533 -> 0 bytes |
10 files changed, 18 insertions, 299 deletions
diff --git a/.Rbuildignore b/.Rbuildignore index d9977a5f..2e8532cf 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -17,7 +17,6 @@ vignettes/*.synctex.gz ^vignettes/FOCUS_Z.tex$ ^vignettes/*_cache$ ^vignettes/*_files$ -^figure/* ^Rplots.pdf$ test.log check.log diff --git a/GNUmakefile b/GNUmakefile index ac2c4577..80b88eb4 100644 --- a/GNUmakefile +++ b/GNUmakefile @@ -31,9 +31,6 @@ pkgfiles = \ all: build -README.md: README.Rmd - "$(RBIN)/Rscript" -e 'require(knitr); knit("README.Rmd")' - $(TGZ): $(pkgfiles) cd ..;\ "$(RBIN)/R" CMD build $(PKGSRC) 2>&1 | tee $(PKGNAME)/build.log @@ -86,7 +83,6 @@ vignettes: vignettes/mkin.pdf vignettes/FOCUS_D.html vignettes/FOCUS_L.html vign sd: install rm -rf $(SDDIR)/* - cp -r figure $(SDDIR) @echo Now execute @echo "\n library(staticdocs); build_site(site_path = '$(SDDIR)')\n" $(RBIN)/R diff --git a/README.Rmd b/README.Rmd deleted file mode 100644 index a3d191d1..00000000 --- a/README.Rmd +++ /dev/null @@ -1,217 +0,0 @@ -# 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, message = FALSE} -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, message = FALSE} -# Somehow knitr does not find the signature() function -require(methods) -``` - -```{r, message = FALSE} -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", quiet = TRUE) - -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 inline package. 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). - The autogeneration of C code was - inspired by the [`ccSolve`](https://github.com/karlines/ccSolve) package. Thanks - to Karline Soetaert for her work on that. -* 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. -* 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. -* 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 ChangeLog, for the latest [CRAN release](http://cran.r-project.org/web/packages/mkin/NEWS.html) -and one for the [github master branch](https://github.com/jranke/mkin/blob/master/NEWS.md). - -## 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. @@ -36,73 +36,13 @@ detailed guidance and helpful tools have been developed as detailed in ## 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 -# 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 -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", quiet = TRUE) - -plot(fit3, show_residuals = TRUE) -``` - - - -```r -#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) +For a start, have a look a the code examples provided for +[`plot.mkinfit`](http://kinfit.r-forge.r-project.org/mkin_static/plot.mkinfit.html) +and +[`plot.mmkin`](http://kinfit.r-forge.r-project.org/mkin_static/plot.mmmkin.html), and +at the package vignettes +[`FOCUS L`](http://kinfit.r-forge.r-project.org/mkin_static/vignettes/FOCUS_L.html) and +[`FOCUS D`](http://kinfit.r-forge.r-project.org/mkin_static/vignettes/FOCUS_D.html). ## Features @@ -111,18 +51,18 @@ documentation or the package vignettes referenced from the 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`](http://kinfit.r-forge.r-project.org/mkin_static/plot.mmkin.html) * 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 inline package. 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). +* If a C compiler is installed, the kinetic models are compiled from automatically + generated C code, see + [vignette `compiled_models`](http://kinfit.r-forge.r-project.org/mkin_static/vignettes/compiled_models.html). The autogeneration of C code was inspired by the [`ccSolve`](https://github.com/karlines/ccSolve) package. Thanks to Karline Soetaert for her work on that. @@ -151,14 +91,15 @@ documentation or the package vignettes referenced from the 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 +* 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, - either IORE kinetics or SFORB kinetics can be used for the metabolite, - adding one respectively two parameters to the system. + either IORE kinetics (often producing failures of the integration algorithm) + or SFORB kinetics (working nicely) can be used for the metabolite, adding one + respectively two parameters to the system. ## GUI diff --git a/figure/unnamed-chunk-3-1.png b/figure/unnamed-chunk-3-1.png Binary files differdeleted file mode 100644 index c74f9dcc..00000000 --- a/figure/unnamed-chunk-3-1.png +++ /dev/null diff --git a/figure/unnamed-chunk-5-1.png b/figure/unnamed-chunk-5-1.png Binary files differdeleted file mode 100644 index 331cd54e..00000000 --- a/figure/unnamed-chunk-5-1.png +++ /dev/null diff --git a/figure/unnamed-chunk-6-1.png b/figure/unnamed-chunk-6-1.png Binary files differdeleted file mode 100644 index e1feaf07..00000000 --- a/figure/unnamed-chunk-6-1.png +++ /dev/null diff --git a/figure/unnamed-chunk-6-2.png b/figure/unnamed-chunk-6-2.png Binary files differdeleted file mode 100644 index b4058df9..00000000 --- a/figure/unnamed-chunk-6-2.png +++ /dev/null diff --git a/figure/unnamed-chunk-7-1.png b/figure/unnamed-chunk-7-1.png Binary files differdeleted file mode 100644 index e1feaf07..00000000 --- a/figure/unnamed-chunk-7-1.png +++ /dev/null diff --git a/figure/unnamed-chunk-7-2.png b/figure/unnamed-chunk-7-2.png Binary files differdeleted file mode 100644 index b4058df9..00000000 --- a/figure/unnamed-chunk-7-2.png +++ /dev/null |
