Merge branch 'main' into custom_lsoda_call

1 files changed, 39 insertions, 28 deletions

diff --git a/README.md b/README.md
index ad522aea..6a42dec0 100644
--- a/README.md
+++ b/README.md
@@ -5,10 +5,13 @@
 [![Build Status](https://travis-ci.com/jranke/mkin.svg?branch=main)](https://app.travis-ci.com/github/jranke/mkin)
 [![codecov](https://codecov.io/github/jranke/mkin/branch/main/graphs/badge.svg)](https://codecov.io/github/jranke/mkin)
 
-The R package **mkin** provides calculation routines for the analysis of
+The [R](https://r-project.org) 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 degradation compartments are involved.
+if several degradation compartments are involved. It provides stable functionality
+for kinetic evaluations according to the FOCUS guidance (see below for details).
+In addition, it provides functionality to do hierarchical kinetics based on
+nonlinear mixed-effects models.
 
 ## Installation
 
@@ -24,8 +27,10 @@ install.packages("mkin")
 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.
+detailed guidance and various helpful tools have been developed as detailed in
+'Credits and historical remarks' below. This package aims to provide a one
+stop solution for degradation kinetics, addressing modellers that are willing
+to, or even prefer to work with R.
 
 ## Usage
 
@@ -50,16 +55,17 @@ version is found in the ['dev' subdirectory](https://pkgdown.jrwb.de/mkin/dev/).
 
 * 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.
+  including equilibrium reactions and using the single first-order reversible
+  binding (SFORB) model, which will automatically create two state variables
+  for the observed variable.
 * 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`).
-* The usual one-sided t-test for significant difference from zero is nevertheless
+  parent only degradation or some simple models involving a single transformation
+  product, , 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`).
+* The usual one-sided t-test for significant difference from zero is
   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
@@ -77,8 +83,8 @@ version is found in the ['dev' subdirectory](https://pkgdown.jrwb.de/mkin/dev/).
   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
+* 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
@@ -92,21 +98,21 @@ version is found in the ['dev' subdirectory](https://pkgdown.jrwb.de/mkin/dev/).
   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
+  is equivalent to the DFOP model. However, the SFORB model has the advantage
+  that there is a mechanistic interpretation of the model parameters.
+* Nonlinear mixed-effects models (hierarchical 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) and
-  [saem.mmkin](https://pkgdown.jrwb.de/mkin/reference/saem.html) and
+  [saem.mmkin](https://pkgdown.jrwb.de/mkin/reference/saem.html)
   methods. 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). The saem method uses the `saemix` package as a backend. Analytical
   solutions suitable for use with this package have been implemented for parent
   only models and the most important models including one metabolite (SFO-SFO
   and DFOP-SFO). Fitting other models with `saem.mmkin`, while it makes use
-  of the compiled ODE models that mkin provides, has longer run times (at least
-  six minutes on my system).
+  of the compiled ODE models that mkin provides, has longer run times (from a couple
+  of minutes to more than an hour).
 
 ### Performance
 
@@ -130,7 +136,9 @@ version is found in the ['dev' subdirectory](https://pkgdown.jrwb.de/mkin/dev/).
 
 There is a graphical user interface that may be useful. Please
 refer to its [documentation page](https://pkgdown.jrwb.de/gmkin/)
-for installation instructions and a manual.
+for installation instructions and a manual. It only supports
+evaluations using (generalised) nonlinear regression, but
+not simultaneous fits using nonlinear mixed-effects models.
 
 ## News
 
@@ -187,13 +195,12 @@ license.
 
 Finally, there is
 [KineticEval](https://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.
+some further development of the scripts used for KinGUII.
 
 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.
+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
@@ -212,9 +219,13 @@ to ModelMaker 4.0, 2014-2015)
   of the visual fit in the kinetic evaluation of degradation data, 2019-2020)
 - Project Number 146839 (Checking the feasibility of using mixed-effects models for
   the derivation of kinetic modelling parameters from degradation studies, 2020-2021)
+- Project Number 173340 (Application of nonlinear hierarchical models to the
+  kinetic evaluation of chemical degradation data)
+
+Thanks to everyone involved for collaboration and support!
 
 Thanks are due also to Emmanuelle Comets, maintainer of the saemix package, for
-the nice collaboration on using the SAEM algorithm and its implementation in
+her interest and support for using the SAEM algorithm and its implementation in
 saemix for the evaluation of chemical degradation data.
 
 ## References