From 1e1025009d488e942fd2ab49eb70997537664f1f Mon Sep 17 00:00:00 2001 From: jranke Date: Tue, 12 Nov 2013 01:34:29 +0000 Subject: Merged README work from master branch git-svn-id: svn+ssh://svn.r-forge.r-project.org/svnroot/kinfit/pkg/mkin@159 edb9625f-4e0d-4859-8d74-9fd3b1da38cb --- README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 39bf23b9..fb070eac 100644 --- a/README.md +++ b/README.md @@ -30,10 +30,54 @@ 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 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. +* 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. + ## Credits `mkin` would not be possible without the underlying software stack consisting @@ -61,4 +105,9 @@ 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 +<<<<<<< HEAD actively developed. +======= +actively developed, so the different tools will hopefully be able to learn +from each other in the future as well. +>>>>>>> master -- cgit v1.2.1