From 64e1da1517abd57936bc8bd7410bb0c43c6b2a0a Mon Sep 17 00:00:00 2001 From: Johannes Ranke Date: Tue, 12 Nov 2013 01:20:20 +0100 Subject: Some more meat to the README --- README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/README.md b/README.md index e418796..764fe79 100644 --- a/README.md +++ b/README.md @@ -3,3 +3,60 @@ The R package **mkin** provides calculation routines for the analysis of chemical degradation data, including **m**ulticompartment **kin**etics as needed for modelling the formation and decline of transformation products. + +## 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") +``` + +## Usage + +For a start, have a look at the examples provided in the +[mkinfit Documentation](http://kinfit.r-forge.r-project.org/mkin_static/mkinfit.html) +or the package vignettes referenced from the +[mkin package documentation page](http://kinfit.r-forge.r-project.org/mkin_static/mkinfit.html) + +## Credits + +`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. + +Also, it was inspired by the first version of KinGUI developed by BayerCropScience, which is based +on the MatLab runtime environment. + +Bayer has developed a successor named KinGUII which is based on mkin, but which added, amongst other +refinements, a graphical user interface (GUI, which is not open source, 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. + +Syngenta has sponsored the development of an mkin based GUI application called CAKE, which +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, I just noticed the github repositories +[StudyKin](http://github.com/zhenglei-gao/StudyKin) and +[KineticEval](http://github.com/zhenglei-gao/KineticEval), the latter of which appears to be +actively developed. -- cgit v1.2.1 From 66766071b638ef892a8f54741806c302c7b3ff94 Mon Sep 17 00:00:00 2001 From: Johannes Ranke Date: Tue, 12 Nov 2013 01:28:30 +0100 Subject: Fixed link and improved text of the github README --- README.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 764fe79..39bf23b 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ install_github("mkin", "jranke") For a start, have a look at the examples provided in the [mkinfit Documentation](http://kinfit.r-forge.r-project.org/mkin_static/mkinfit.html) or the package vignettes referenced from the -[mkin package documentation page](http://kinfit.r-forge.r-project.org/mkin_static/mkinfit.html) +[mkin package documentation page](http://kinfit.r-forge.r-project.org/mkin_static/index.html) ## Credits @@ -41,22 +41,24 @@ 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. -Also, it was inspired by the first version of KinGUI developed by BayerCropScience, which is based -on the MatLab runtime environment. - -Bayer has developed a successor named KinGUII which is based on mkin, but which added, amongst other -refinements, a graphical user interface (GUI, which is not open source, 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. - -Syngenta has sponsored the development of an mkin based GUI application called CAKE, which -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 +Also, it was inspired by the first version of KinGUI developed by +BayerCropScience, which is based on the MatLab runtime environment. + +Bayer has developed a successor 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. + +Syngenta has sponsored the development of an `mkin` (and KinGUII?) based GUI +application called CAKE, which 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, I just noticed the github repositories +Finally, I just (2013-11-11) noticed the github repositories [StudyKin](http://github.com/zhenglei-gao/StudyKin) and [KineticEval](http://github.com/zhenglei-gao/KineticEval), the latter of which appears to be actively developed. -- cgit v1.2.1 From 84f79c961d11a987ade0b95bfbd1eed193861d36 Mon Sep 17 00:00:00 2001 From: Johannes Ranke Date: Tue, 12 Nov 2013 02:17:27 +0100 Subject: Add the feature section to the README --- README.md | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 39bf23b..16f5330 100644 --- a/README.md +++ b/README.md @@ -30,10 +30,51 @@ install_github("mkin", "jranke") ## Usage For a start, have a look at the examples provided in the -[mkinfit Documentation](http://kinfit.r-forge.r-project.org/mkin_static/mkinfit.html) +[`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 reverse 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 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 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 fracitons). +* 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 will not occur in + a single experiment with a single defined radiolabel position). +* Summary and plotting functions. The summary is in fact a full report + that should give enough information to be able to approximately + reproduce the fit with other tools. +* 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 optimisation step has converged. + + ## Credits `mkin` would not be possible without the underlying software stack consisting -- cgit v1.2.1 From 78ff1460c4e5b399bbab20f7b5b7f504dda8a6cd Mon Sep 17 00:00:00 2001 From: Johannes Ranke Date: Tue, 12 Nov 2013 02:28:31 +0100 Subject: Some more work on the README --- README.md | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 16f5330..5e639e5 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ or the package vignettes referenced from the * Highly flexible model specification using [`mkinmod`](http://kinfit.r-forge.r-project.org/mkin_static/mkinmod.html), - including reverse reactions and using the single first-order + 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 @@ -50,29 +50,33 @@ or the package vignettes referenced from the using a numeric solver from the `deSolve` package (default is `lsoda`). These have decreasing efficiency, and are automatically chosen by default. -* Model optimisation using the `modFit` function from the `FME` package, +* 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 so their estimators can more reasonably be expected to follow + 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 + 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 fracitons). + 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 will not occur in + 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 is in fact a full report - that should give enough information to be able to approximately - reproduce the fit with other tools. +* 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. * 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 + `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 optimisation step has converged. + in a second stage after the primary optimisation algorithm has converged. ## Credits @@ -102,4 +106,5 @@ license. Finally, I just (2013-11-11) noticed the github repositories [StudyKin](http://github.com/zhenglei-gao/StudyKin) and [KineticEval](http://github.com/zhenglei-gao/KineticEval), the latter of which appears to be -actively developed. +actively developed, so the different tools will hopefully be able to learn +from each other in the future as well. -- cgit v1.2.1 From 1410eaff939bd84a3ddc306b6660f3fde6855339 Mon Sep 17 00:00:00 2001 From: Johannes Ranke Date: Tue, 12 Nov 2013 02:53:40 +0100 Subject: More history in the README --- README.md | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 5e639e5..ed1d263 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ or the package vignettes referenced from the in a second stage after the primary optimisation algorithm has converged. -## Credits +## 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), @@ -89,17 +89,27 @@ of R and the packages [deSolve](http://cran.r-project.org/package=deSolve), Also, it was inspired by the first version of KinGUI developed by BayerCropScience, which is based on the MatLab runtime environment. -Bayer has developed a successor 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. - -Syngenta has sponsored the development of an `mkin` (and KinGUII?) based GUI -application called CAKE, which 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 +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. -- cgit v1.2.1