Documentation improvements, mainly fixing example code

The errors in the example code were in the \dontrun sections, so they
were not caught by CRAN checks. In addition, the static help files
generated with pkgdown were cached, so I noticed the errors only
after completely regenerating the documentation for version 1.0.0.

7 files changed, 44 insertions, 50 deletions

diff --git a/man/confint.mkinfit.Rd b/man/confint.mkinfit.Rd
index fd2890ff..b19e78c2 100644
--- a/man/confint.mkinfit.Rd
+++ b/man/confint.mkinfit.Rd
@@ -82,20 +82,20 @@ confint(f, method = "profile")
 if (identical(Sys.getenv("NOT_CRAN"), "true")) {
   n_cores <- parallel::detectCores() - 1
 } else {
- n_cores <- 1
+  n_cores <- 1
 }
 if (Sys.getenv("TRAVIS") != "") n_cores = 1
 if (Sys.info()["sysname"] == "Windows") n_cores = 1
 
-SFO_SFO <- mkinmod(parent = mkinsub("SFO", "m1"), m1 = mkinsub("SFO"), quiet = TRUE)
+SFO_SFO <- mkinmod(parent = mkinsub("SFO", "m1"), m1 = mkinsub("SFO"),
+  use_of_ff = "min", quiet = TRUE)
 SFO_SFO.ff <- mkinmod(parent = mkinsub("SFO", "m1"), m1 = mkinsub("SFO"),
   use_of_ff = "max", quiet = TRUE)
 f_d_1 <- mkinfit(SFO_SFO, subset(FOCUS_2006_D, value != 0), quiet = TRUE)
 system.time(ci_profile <- confint(f_d_1, method = "profile", cores = 1, quiet = TRUE))
 # Using more cores does not save much time here, as parent_0 takes up most of the time
 # If we additionally exclude parent_0 (the confidence of which is often of
-# minor interest), we get a nice performance improvement from about 50
-# seconds to about 12 seconds if we use at least four cores
+# minor interest), we get a nice performance improvement if we use at least 4 cores
 system.time(ci_profile_no_parent_0 <- confint(f_d_1, method = "profile",
   c("k_parent_sink", "k_parent_m1", "k_m1_sink", "sigma"), cores = n_cores))
 ci_profile
diff --git a/man/logLik.mkinfit.Rd b/man/logLik.mkinfit.Rd
index 637570e4..6b40305e 100644
--- a/man/logLik.mkinfit.Rd
+++ b/man/logLik.mkinfit.Rd
@@ -35,10 +35,10 @@ and the fitted error model parameters.
     parent = mkinsub("SFO", to = "m1"),
     m1 = mkinsub("SFO")
   )
-  d_t <- FOCUS_2006_D
+  d_t <- subset(FOCUS_2006_D, value != 0)
   f_nw <- mkinfit(sfo_sfo, d_t, quiet = TRUE) # no weighting (weights are unity)
-  f_obs <- mkinfit(sfo_sfo, d_t, error_model = "obs", quiet = TRUE)
-  f_tc <- mkinfit(sfo_sfo, d_t, error_model = "tc", quiet = TRUE)
+  f_obs <- update(f_nw, error_model = "obs")
+  f_tc <- update(f_nw, error_model = "tc")
   AIC(f_nw, f_obs, f_tc)
   }
 
diff --git a/man/mkinresplot.Rd b/man/mkinresplot.Rd
index 498d914d..9658ddb5 100644
--- a/man/mkinresplot.Rd
+++ b/man/mkinresplot.Rd
@@ -75,5 +75,5 @@ lines of the mkinfit object, and \code{\link{plot_res}} for a function
 combining the plot of the fit and the residual plot.
 }
 \author{
-Johannes Ranke
+Johannes Ranke and Katrin Lindenberger
 }
diff --git a/man/mmkin.Rd b/man/mmkin.Rd
index 9b836242..170ce8df 100644
--- a/man/mmkin.Rd
+++ b/man/mmkin.Rd
@@ -2,6 +2,7 @@
 % Please edit documentation in R/mmkin.R
 \name{mmkin}
 \alias{mmkin}
+\alias{print.mmkin}
 \title{Fit one or more kinetic models with one or more state variables to one or
 more datasets}
 \usage{
@@ -12,6 +13,8 @@ mmkin(
   cluster = NULL,
   ...
 )
+
+\method{print}{mmkin}(x, ...)
 }
 \arguments{
 \item{models}{Either a character vector of shorthand names like
@@ -30,7 +33,9 @@ detected by \code{\link[parallel:detectCores]{parallel::detectCores()}} are used
 \item{cluster}{A cluster as returned by \code{\link{makeCluster}} to be used
 for parallel execution.}
 
-\item{\dots}{Further arguments that will be passed to \code{\link{mkinfit}}.}
+\item{\dots}{Not used.}
+
+\item{x}{An \link{mmkin} object.}
 }
 \value{
 A two-dimensional \code{\link{array}} of \code{\link{mkinfit}}
diff --git a/man/nlme.mmkin.Rd b/man/nlme.mmkin.Rd
index f78256ac..2fb0488a 100644
--- a/man/nlme.mmkin.Rd
+++ b/man/nlme.mmkin.Rd
@@ -79,6 +79,12 @@ This functions sets up a nonlinear mixed effects model for an mmkin row
 object. An mmkin row object is essentially a list of mkinfit objects that
 have been obtained by fitting the same model to a list of datasets.
 }
+\details{
+Note that the convergence of the nlme algorithms depends on the quality
+of the data. In degradation kinetics, we often only have few datasets
+(e.g. data for few soils) and complicated degradation models, which may
+make it impossible to obtain convergence with nlme.
+}
 \note{
 As the object inherits from \link[nlme:nlme]{nlme::nlme}, there is a wealth of
 methods that will automatically work on 'nlme.mmkin' objects, such as
@@ -120,11 +126,10 @@ f_nlme_sfo <- nlme(f["SFO", ])
   # f_nlme_sfo_sfo_ff <- nlme(f_2["SFO-SFO-ff", ])
   #plot(f_nlme_sfo_sfo_ff)
 
-  # With the log-Cholesky parameterization, this converges in 11
-  # iterations and around 100 seconds, but without tweaking control
-  # parameters (with pdDiag, increasing the tolerance and pnlsMaxIter was
-  # necessary)
-  f_nlme_dfop_sfo <- nlme(f_2["DFOP-SFO", ])
+  # For the following, we need to increase pnlsMaxIter and the tolerance
+  # to get convergence
+  f_nlme_dfop_sfo <- nlme(f_2["DFOP-SFO", ],
+    control = list(pnlsMaxIter = 120, tolerance = 5e-4))
 
   plot(f_nlme_dfop_sfo)
 
@@ -144,22 +149,18 @@ f_nlme_sfo <- nlme(f["SFO", ])
     print(f_nlme_dfop_tc)
   }
 
-  f_2_obs <- mmkin(list("SFO-SFO" = m_sfo_sfo,
-   "DFOP-SFO" = m_dfop_sfo),
-    ds_2, quiet = TRUE, error_model = "obs")
+  f_2_obs <- update(f_2, error_model = "obs")
   f_nlme_sfo_sfo_obs <- nlme(f_2_obs["SFO-SFO", ])
   print(f_nlme_sfo_sfo_obs)
-  f_nlme_dfop_sfo_obs <- nlme(f_2_obs["DFOP-SFO", ])
+  f_nlme_dfop_sfo_obs <- nlme(f_2_obs["DFOP-SFO", ],
+    control = list(pnlsMaxIter = 120, tolerance = 5e-4))
 
-  f_2_tc <- mmkin(list("SFO-SFO" = m_sfo_sfo,
-   "DFOP-SFO" = m_dfop_sfo),
-    ds_2, quiet = TRUE, error_model = "tc")
-  # f_nlme_sfo_sfo_tc <- nlme(f_2_tc["SFO-SFO", ]) # stops with error message
-  f_nlme_dfop_sfo_tc <- nlme(f_2_tc["DFOP-SFO", ])
-  # We get warnings about false convergence in the LME step in several iterations
-  # but as the last such warning occurs in iteration 25 and we have 28 iterations
-  # we can ignore these
-  anova(f_nlme_dfop_sfo, f_nlme_dfop_sfo_obs, f_nlme_dfop_sfo_tc)
+  f_2_tc <- update(f_2, error_model = "tc")
+  # f_nlme_sfo_sfo_tc <- nlme(f_2_tc["SFO-SFO", ]) # No convergence with 50 iterations
+  # f_nlme_dfop_sfo_tc <- nlme(f_2_tc["DFOP-SFO", ],
+  #  control = list(pnlsMaxIter = 120, tolerance = 5e-4)) # Error in X[, fmap[[nm]]] <- gradnm
+
+  anova(f_nlme_dfop_sfo, f_nlme_dfop_sfo_obs)
 
 }
 }
diff --git a/man/print.mmkin.Rd b/man/print.mmkin.Rd
deleted file mode 100644
index 29abe143..00000000
--- a/man/print.mmkin.Rd
+++ /dev/null
@@ -1,16 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/mmkin.R
-\name{print.mmkin}
-\alias{print.mmkin}
-\title{Print method for mmkin objects}
-\usage{
-\method{print}{mmkin}(x, ...)
-}
-\arguments{
-\item{x}{An \link{mmkin} object.}
-
-\item{\dots}{Not used.}
-}
-\description{
-Print method for mmkin objects
-}
diff --git a/man/transform_odeparms.Rd b/man/transform_odeparms.Rd
index f38bb051..3a97ff8d 100644
--- a/man/transform_odeparms.Rd
+++ b/man/transform_odeparms.Rd
@@ -69,17 +69,21 @@ This is no problem for the internal use in \link{mkinfit}.
 
 SFO_SFO <- mkinmod(
   parent = list(type = "SFO", to = "m1", sink = TRUE),
-  m1 = list(type = "SFO"))
+  m1 = list(type = "SFO"), use_of_ff = "min")
+
 # Fit the model to the FOCUS example dataset D using defaults
-fit <- mkinfit(SFO_SFO, FOCUS_2006_D, quiet = TRUE)
+FOCUS_D <- subset(FOCUS_2006_D, value != 0) # remove zero values to avoid warning
+fit <- mkinfit(SFO_SFO, FOCUS_D, quiet = TRUE)
 fit.s <- summary(fit)
 # Transformed and backtransformed parameters
 print(fit.s$par, 3)
 print(fit.s$bpar, 3)
 
 \dontrun{
-# Compare to the version without transforming rate parameters
-fit.2 <- mkinfit(SFO_SFO, FOCUS_2006_D, transform_rates = FALSE, quiet = TRUE)
+# Compare to the version without transforming rate parameters (does not work
+# with analytical solution, we get NA values for m1 in predictions)
+fit.2 <- mkinfit(SFO_SFO, FOCUS_D, transform_rates = FALSE,
+  solution_type = "deSolve", quiet = TRUE)
 fit.2.s <- summary(fit.2)
 print(fit.2.s$par, 3)
 print(fit.2.s$bpar, 3)
@@ -93,13 +97,13 @@ transform_odeparms(initials, SFO_SFO)
 backtransform_odeparms(transformed, SFO_SFO)
 
 \dontrun{
-# The case of formation fractions
+# The case of formation fractions (this is now the default)
 SFO_SFO.ff <- mkinmod(
   parent = list(type = "SFO", to = "m1", sink = TRUE),
   m1 = list(type = "SFO"),
   use_of_ff = "max")
 
-fit.ff <- mkinfit(SFO_SFO.ff, FOCUS_2006_D, quiet = TRUE)
+fit.ff <- mkinfit(SFO_SFO.ff, FOCUS_D, quiet = TRUE)
 fit.ff.s <- summary(fit.ff)
 print(fit.ff.s$par, 3)
 print(fit.ff.s$bpar, 3)
@@ -114,7 +118,7 @@ SFO_SFO.ff.2 <- mkinmod(
   use_of_ff = "max")
 
 
-fit.ff.2 <- mkinfit(SFO_SFO.ff.2, FOCUS_2006_D, quiet = TRUE)
+fit.ff.2 <- mkinfit(SFO_SFO.ff.2, FOCUS_D, quiet = TRUE)
 fit.ff.2.s <- summary(fit.ff.2)
 print(fit.ff.2.s$par, 3)
 print(fit.ff.2.s$bpar, 3)