Merge branch 'algorithm'

4 files changed, 164 insertions, 0 deletions

diff --git a/man/experimental_data_for_UBA.Rd b/man/experimental_data_for_UBA.Rd
new file mode 100644
index 00000000..e3386a2f
--- /dev/null
+++ b/man/experimental_data_for_UBA.Rd
@@ -0,0 +1,120 @@
+\name{experimental_data_for_UBA_2019}
+\alias{experimental_data_for_UBA_2019}
+\docType{data}
+\title{
+  Experimental datasets used for development and testing of error models
+}
+\description{
+ The 12 datasets were extracted from active substance evaluation dossiers published
+ by EFSA. Kinetic evaluations shown for these datasets are intended to illustrate
+ and advance error model specifications. The fact that these data and some
+ results are shown here do not imply a license to use them in the context of
+ pesticide registrations, as the use of the data may be constrained by
+ data protection regulations.
+
+ Preprocessing of data was performed based on the recommendations of the FOCUS
+ kinetics workgroup (FOCUS, 2014) as described below.
+
+ Datasets 1 and 2 are from the Renewal Assessment Report (RAR) for imazamox
+ (France, 2015, p. 15). For setting values reported as zero, an LOQ of 0.1
+ was assumed. Metabolite residues reported for day zero were added to the
+ parent compound residues.
+
+ Datasets 3 and 4 are from the Renewal Assessment Report (RAR) for isofetamid
+ (Belgium, 2014, p. 8) and show the data for two different radiolabels. For
+ dataset 4, the value given for the metabolite in the day zero sampling
+ in replicate B was added to the parent compound, following the respective
+ FOCUS recommendation.
+
+ Dataset 5 is from the Renewal Assessment Report (RAR) for ethofumesate
+ (Austria, 2015, p. 16).
+
+ Datasets 6 to 10 are from the Renewal Assessment Report (RAR) for glyphosate
+ (Germany, 2013a, pages 8, 28, 50, 51). For the initial sampling,
+ the residues given for the metabolite were added to the parent
+ value, following the recommendation of the FOCUS kinetics workgroup.
+
+ Dataset 11 is from the Renewal Assessment Report (RAR) for 2,4-D
+ (Germany, 2013b, p. 644). Values reported as zero were set to NA, with
+ the exception of the day three sampling of metabolite A2, which was set
+ to one half of the LOD reported to be 1\% AR.
+
+ Dataset 12 is from the Renewal Assessment Report (RAR) for thifensulfuron-methyl
+ (United Kingdom, 2014, p. 81).
+
+}
+\usage{experimental_data_for_UBA_2019}
+\format{
+  A list containing twelve datasets as an R6 class defined by \code{\link{mkinds}},
+  each containing, among others, the following components
+  \describe{
+    \item{\code{title}}{The name of the dataset, e.g. \code{Soil 1}}
+    \item{\code{data}}{A data frame with the data in the form expected by \code{\link{mkinfit}}}
+  }
+}
+\source{
+
+  Austria (2015). Ethofumesate Renewal Assessment Report Volume 3 Annex B.8 (AS)
+
+  Belgium (2014). Isofetamid (IKF-5411) Draft Assessment Report Volume 3 Annex B.8 (AS)
+
+  France (2015). Imazamox Draft Renewal Assessment Report Volume 3 Annex B.8 (AS)
+
+  FOCUS (2014) \dQuote{Generic guidance for Estimating Persistence and
+  Degradation Kinetics from Environmental Fate Studies on Pesticides in EU
+  Registration} Report of the FOCUS Work Group on Degradation Kinetics,
+  Version 1.1, 18 December 2014
+  \url{http://esdac.jrc.ec.europa.eu/projects/degradation-kinetics}
+
+  Germany (2013a). Renewal Assessment Report Glyphosate Volume 3 Annex B.8: Environmental Fate
+  and Behaviour
+
+  Germany (2013b). Renewal Assessment Report 2,4-D Volume 3 Annex B.8: Fate and behaviour in the
+  environment
+
+  Ranke (2019) Documentation of results obtained for the error model expertise
+  written for the German Umweltbundesamt.
+
+  United Kingdom (2014). Thifensulfuron-methyl - Annex B.8 (Volume 3) to the Report and Proposed
+  Decision of the United Kingdom made to the European Commission under Regulation (EC) No.
+  1141/2010 for renewal of an active substance
+
+}
+\examples{\dontrun{
+
+# Model definitions
+sfo_sfo <- mkinmod(
+  parent = mkinsub("SFO", to = "A1"),
+  A1 = mkinsub("SFO"),
+  use_of_ff = "max"
+)
+
+dfop_sfo <- mkinmod(
+  parent = mkinsub("DFOP", to = "A1"),
+  A1 = mkinsub("SFO"),
+  use_of_ff = "max"
+)
+
+sfo_sfo_sfo <- mkinmod(
+  parent = mkinsub("SFO", to = "A1"),
+  A1 = mkinsub("SFO", to = "A2"),
+  A2 = mkinsub("SFO"),
+  use_of_ff = "max"
+)
+
+dfop_sfo_sfo <- mkinmod(
+  parent = mkinsub("DFOP", to = "A1"),
+  A1 = mkinsub("SFO", to = "A2"),
+  A2 = mkinsub("SFO"),
+  use_of_ff = "max"
+)
+d_1_2 <- lapply(experimental_data_for_UBA_2019[1:2], function(x) x$data)
+names(d_1_2) <- paste("Soil", 1:2)
+
+
+f_1_2_tc <- mmkin(list("DFOP-SFO-SFO" = dfop_sfo_sfo), d_1_2, error_model = "tc")
+
+plot(f_1_2_tc, resplot = "errmod")
+
+}}
+\keyword{datasets}
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
 }