Additional algorithm "d_c", more tests, docs

The new algorithm tries direct optimization of the likelihood, as well
as a three step procedure. In this way, we consistently get the
model with the highest likelihood for SFO, DFOP and HS for all 12
new test datasets.

3 files changed, 44 insertions, 0 deletions

diff --git a/man/mkinerrplot.Rd b/man/mkinerrplot.Rd
index 4cbb5eb7..3b557b0a 100644
--- a/man/mkinerrplot.Rd
+++ b/man/mkinerrplot.Rd
@@ -68,8 +68,10 @@
  \code{\link{mkinplot}}, for a way to plot the data and the fitted lines of the
  mkinfit object.  }
 \examples{
+\dontrun{
 model <- mkinmod(parent = mkinsub("SFO", "m1"), m1 = mkinsub("SFO"))
 fit <- mkinfit(model, FOCUS_2006_D, error_model = "tc", quiet = TRUE)
 mkinerrplot(fit)
 }
+}
 \keyword{ hplot }
diff --git a/man/mkinfit.Rd b/man/mkinfit.Rd
index 78a53ee0..975eace8 100644
--- a/man/mkinfit.Rd
+++ b/man/mkinfit.Rd
@@ -31,6 +31,8 @@ mkinfit(mkinmod, observed,
   quiet = FALSE,
   atol = 1e-8, rtol = 1e-10, n.outtimes = 100,
   error_model = c("const", "obs", "tc"),
+  error_model_algorithm = c("d_3", "direct", "twostep", "threestep", "fourstep", "IRLS"),
+  reweight.tol = 1e-8, reweight.max.iter = 10,
   trace_parms = FALSE, ...)
 }
 \arguments{
@@ -171,6 +173,44 @@ mkinfit(mkinmod, observed,
     errors follow a lognormal distribution for large values, not a normal
     distribution as assumed by this method.
   }
+  \item{error_model_algorithm}{
+    If the error model is "const", the error model algorithm is ignored,
+    because no special algorithm is needed and unweighted (also known as
+    ordinary) least squares fitting can be applied.
+
+    The default algorithm "d_3" will directly minimize the negative
+    log-likelihood and - independently - also use the three step algorithm
+    described below. The fit with the higher likelihood is returned.
+
+    The algorithm "direct" will directly minimize the negative
+    log-likelihood.
+
+    The algorithm "twostep" will minimize the negative log-likelihood
+    after an initial unweighted leas squares optimisation step.
+
+    The algorithm "threestep" starts with unweighted least squares,
+    then optimizes only the error model using the degradation model
+    parameters found, and then minimizes the negative log-likelihood
+    with free degradation and error model parameters.
+
+    The algorithm "fourstep" starts with unweighted least squares,
+    then optimizes only the error model using the degradation model
+    parameters found, then optimizes the degradation model again
+    with fixed error model parameters, and finally minimizes the negative
+    log-likelihood with free degradation and error model parameters.
+
+    The algorithm "IRLS" starts with unweighted least squares,
+    and then iterates optimization of the error model parameters and subsequent
+    optimization of the degradation model using those error model parameters,
+    until the error model parameters converge.
+  }
+  \item{reweight.tol}{
+    Tolerance for the convergence criterion calculated from the error model
+    parameters in IRLS fits.
+  }
+  \item{reweight.max.iter}{
+    Maximum number of iterations in IRLS fits.
+  }
   \item{trace_parms}{
     Should a trace of the parameter values be listed?
   }
diff --git a/man/plot.mkinfit.Rd b/man/plot.mkinfit.Rd
index 9514c5e5..5e20ad90 100644
--- a/man/plot.mkinfit.Rd
+++ b/man/plot.mkinfit.Rd
@@ -115,6 +115,7 @@ plot_sep(fit, sep_obs = TRUE,  show_residuals = TRUE, show_errmin = TRUE, \dots)
 \examples{
 # One parent compound, one metabolite, both single first order, path from
 # parent to sink included
+\dontrun{
 SFO_SFO <- mkinmod(parent = mkinsub("SFO", "m1", full = "Parent"),
                    m1 = mkinsub("SFO", full = "Metabolite M1" ))
 fit <- mkinfit(SFO_SFO, FOCUS_2006_D, quiet = TRUE, error_model = "tc")
@@ -136,6 +137,7 @@ plot_sep(fit, lpos = c("topright", "bottomright"))
 plot(fit, sep_obs = TRUE, show_errplot = TRUE, lpos = c("topright", "bottomright"),
      show_errmin = TRUE)
 }
+}
 \author{
   Johannes Ranke
 }