aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorJohannes Ranke <jranke@uni-bremen.de>2021-02-15 14:08:13 +0100
committerJohannes Ranke <jranke@uni-bremen.de>2021-02-15 15:20:53 +0100
commita9427a09abdf7ce9aaeae7c7190f90c8f2e5ef52 (patch)
treea9ecf25af6657e70d8f1faabd88fb6e2f6334b07 /README.md
parentb4582fc7d3f1d395bfd9d870137b705469d9eab2 (diff)
Improve README, introductory vignette and some other docsv1.0.3
Also bump version to 1.0.3.
Diffstat (limited to 'README.md')
-rw-r--r--README.md99
1 files changed, 68 insertions, 31 deletions
diff --git a/README.md b/README.md
index 973dbc89..af8ea24b 100644
--- a/README.md
+++ b/README.md
@@ -45,40 +45,19 @@ version is found in the ['dev' subdirectory](https://pkgdown.jrwb.de/mkin/dev/).
## Features
+### General
+
* Highly flexible model specification using
[`mkinmod`](https://pkgdown.jrwb.de/mkin/reference/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.
-* As of version 0.9-39, fitting of several models to several datasets, optionally in
- parallel, is supported, see for example
- [`plot.mmkin`](https://pkgdown.jrwb.de/mkin/reference/plot.mmkin.html).
* Model solution (forward modelling) in the function
[`mkinpredict`](https://pkgdown.jrwb.de/mkin/reference/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`).
-* If a C compiler is installed, the kinetic models are compiled from automatically
- generated C code, see
- [vignette `compiled_models`](https://pkgdown.jrwb.de/mkin/articles/web_only/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.
-* By default, kinetic rate constants and kinetic formation fractions are
- transformed internally using
- [`transform_odeparms`](https://pkgdown.jrwb.de/mkin/reference/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 log-ratio 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
@@ -86,23 +65,59 @@ version is found in the ['dev' subdirectory](https://pkgdown.jrwb.de/mkin/dev/).
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.
-* When a metabolite decline phase is not described well by SFO kinetics,
- SFORB kinetics can be used for the metabolite.
-* Three different error models can be selected using the argument `error_model`
- to the [`mkinfit`](https://pkgdown.jrwb.de/mkin/reference/mkinfit.html)
- function.
* The 'variance by variable' error model which is often fitted using
Iteratively Reweighted Least Squares (IRLS) should now be specified as
`error_model = "obs"`.
-* A two-component error model similar to the one proposed by
+
+### Unique in mkin
+
+* Three different error models can be selected using the argument `error_model`
+ to the [`mkinfit`](https://pkgdown.jrwb.de/mkin/reference/mkinfit.html)
+ function. A two-component error model similar to the one proposed by
[Rocke and Lorenzato](https://pkgdown.jrwb.de/mkin/reference/sigma_twocomp.html)
can be selected using the argument `error_model = "tc"`.
+* Model comparisons using the Akaike Information Criterion (AIC) are supported which
+ can also be used for non-constant variance. In such cases the FOCUS
+ chi-squared error level is not meaningful.
+* By default, kinetic rate constants and kinetic formation fractions are
+ transformed internally using
+ [`transform_odeparms`](https://pkgdown.jrwb.de/mkin/reference/transform_odeparms.html)
+ so their estimators can more reasonably be expected to follow
+ a normal distribution.
+* 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 cannot
+ occur in a single experiment with a single defined radiolabel position.
+* When a metabolite decline phase is not described well by SFO kinetics,
+ SFORB kinetics can be used for the metabolite. Mathematically, the SFORB model
+ is equivalent to the DFOP model used by other tools for biphasic metabolite curves.
+ However, the SFORB model has the advantage that there is a mechanistic
+ interpretation of the model parameters.
* Nonlinear mixed-effects models can be created from fits of the same degradation
model to different datasets for the same compound by using the
[nlme.mmkin](https://pkgdown.jrwb.de/mkin/reference/nlme.mmkin.html) method.
Note that the convergence of the nlme fits depends on the quality of the data.
Convergence is better for simple models and data for many groups (e.g. soils).
+### Performance
+
+* Parallel fitting of several models to several datasets is supported, see for
+ example
+ [`plot.mmkin`](https://pkgdown.jrwb.de/mkin/reference/plot.mmkin.html).
+* If a C compiler is installed, the kinetic models are compiled from automatically
+ generated C code, see
+ [vignette `compiled_models`](https://pkgdown.jrwb.de/mkin/articles/web_only/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.
+* Even if no compiler is installed, many degradation models still give
+ [very good performance](https://pkgdown.jrwb.de/mkin/articles/web_only/benchmarks.html),
+ as current versions of mkin also have [analytical solutions for some models
+ with one metabolite](https://jrwb.de/performance-improvements-mkin/), and if
+ SFO or SFORB are used for the parent compound, Eigenvalue based solutions of
+ the degradation model are available.
+
## GUI
There is a graphical user interface that may be useful. Please
@@ -111,8 +126,8 @@ for installation instructions and a manual.
## News
-There is a ChangeLog, for the latest [CRAN release](https://cran.r-project.org/package=mkin/news/news.html)
-and one for the [github master branch](https://github.com/jranke/mkin/blob/master/NEWS.md).
+There is a list of changes for the latest [CRAN release](https://cran.r-project.org/package=mkin/news/news.html)
+and one for each github branch, e.g. [the main branch](https://github.com/jranke/mkin/blob/master/NEWS.md).
## Credits and historical remarks
@@ -167,6 +182,28 @@ Finally, there is
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.
+Thanks to René Lehmann, formerly working at the Umweltbundesamt, for the nice
+cooperation cooperation on parameter transformations, especially the isometric
+log-ratio transformation that is now used for formation fractions in case
+there are more than two transformation targets.
+
+Many inspirations for improvements of mkin resulted from doing kinetic evaluations
+of degradation data for my clients while working at Harlan Laboratories and
+at Eurofins Regulatory AG, and now as an independent consultant.
+
+Funding was received from the Umweltbundesamt in the course of the projects
+
+- Grant Number 112407 (Testing and validation of modelling software as an alternative
+to ModelMaker 4.0, 2014-2015)
+- Project Number 56703 (Optimization of gmkin for routine use in the Umweltbundesamt, 2015)
+- Project Number 112407 (Testing the feasibility of using an error model
+ according to Rocke and Lorenzato for more realistic parameter estimates in
+ the kinetic evaluation of degradation data, 2018-2019)
+- Project Number 120667 (Development of objective criteria for the evaluation
+ of the visual fit in the kinetic evaluation of degradation data, 2019-2020)
+- Project 146839 (Checking the feasibility of using mixed-effects models for
+ the derivation of kinetic modelling parameters from degradation studies, 2020-2021)
+
## References
<table>

Contact - Imprint