Reintroduce interface to saemix

Also after the upgrade from buster to bullseye of my local system, some
test results for saemix have changed.

1 files changed, 155 insertions, 0 deletions

diff --git a/man/saem.Rd b/man/saem.Rd
new file mode 100644
index 00000000..d5a8f17e
--- /dev/null
+++ b/man/saem.Rd
@@ -0,0 +1,155 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/saem.R
+\name{saem}
+\alias{saem}
+\alias{saem.mmkin}
+\alias{print.saem.mmkin}
+\alias{saemix_model}
+\alias{saemix_data}
+\title{Fit nonlinear mixed models with SAEM}
+\usage{
+saem(object, ...)
+
+\method{saem}{mmkin}(
+  object,
+  transformations = c("mkin", "saemix"),
+  degparms_start = numeric(),
+  solution_type = "auto",
+  control = list(displayProgress = FALSE, print = FALSE, save = FALSE, save.graphs =
+    FALSE),
+  verbose = FALSE,
+  quiet = FALSE,
+  ...
+)
+
+\method{print}{saem.mmkin}(x, digits = max(3, getOption("digits") - 3), ...)
+
+saemix_model(
+  object,
+  solution_type = "auto",
+  transformations = c("mkin", "saemix"),
+  degparms_start = numeric(),
+  verbose = FALSE,
+  ...
+)
+
+saemix_data(object, verbose = FALSE, ...)
+}
+\arguments{
+\item{object}{An \link{mmkin} row object containing several fits of the same
+\link{mkinmod} model to different datasets}
+
+\item{\dots}{Further parameters passed to \link[saemix:saemixModel]{saemix::saemixModel}.}
+
+\item{transformations}{Per default, all parameter transformations are done
+in mkin. If this argument is set to 'saemix', parameter transformations
+are done in 'saemix' for the supported cases. Currently this is only
+supported in cases where the initial concentration of the parent is not fixed,
+SFO or DFOP is used for the parent and there is either no metabolite or one.}
+
+\item{degparms_start}{Parameter values given as a named numeric vector will
+be used to override the starting values obtained from the 'mmkin' object.}
+
+\item{solution_type}{Possibility to specify the solution type in case the
+automatic choice is not desired}
+
+\item{control}{Passed to \link[saemix:saemix]{saemix::saemix}}
+
+\item{verbose}{Should we print information about created objects of
+type \link[saemix:SaemixModel-class]{saemix::SaemixModel} and \link[saemix:SaemixData-class]{saemix::SaemixData}?}
+
+\item{quiet}{Should we suppress the messages saemix prints at the beginning
+and the end of the optimisation process?}
+
+\item{x}{An saem.mmkin object to print}
+
+\item{digits}{Number of digits to use for printing}
+}
+\value{
+An S3 object of class 'saem.mmkin', containing the fitted
+\link[saemix:SaemixObject-class]{saemix::SaemixObject} as a list component named 'so'. The
+object also inherits from 'mixed.mmkin'.
+
+An \link[saemix:SaemixModel-class]{saemix::SaemixModel} object.
+
+An \link[saemix:SaemixData-class]{saemix::SaemixData} object.
+}
+\description{
+This function uses \code{\link[saemix:saemix]{saemix::saemix()}} as a backend for fitting nonlinear mixed
+effects models created from \link{mmkin} row objects using the Stochastic Approximation
+Expectation Maximisation algorithm (SAEM).
+}
+\details{
+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 using \link{mkinfit}.
+
+Starting values for the fixed effects (population mean parameters, argument
+psi0 of \code{\link[saemix:saemixModel]{saemix::saemixModel()}} are the mean values of the parameters found
+using \link{mmkin}.
+}
+\examples{
+\dontrun{
+ds <- lapply(experimental_data_for_UBA_2019[6:10],
+ function(x) subset(x$data[c("name", "time", "value")]))
+names(ds) <- paste("Dataset", 6:10)
+f_mmkin_parent_p0_fixed <- mmkin("FOMC", ds,
+  state.ini = c(parent = 100), fixed_initials = "parent", quiet = TRUE)
+f_saem_p0_fixed <- saem(f_mmkin_parent_p0_fixed)
+
+f_mmkin_parent <- mmkin(c("SFO", "FOMC", "DFOP"), ds, quiet = TRUE)
+f_saem_sfo <- saem(f_mmkin_parent["SFO", ])
+f_saem_fomc <- saem(f_mmkin_parent["FOMC", ])
+f_saem_dfop <- saem(f_mmkin_parent["DFOP", ])
+
+# The returned saem.mmkin object contains an SaemixObject, therefore we can use
+# functions from saemix
+library(saemix)
+compare.saemix(list(f_saem_sfo$so, f_saem_fomc$so, f_saem_dfop$so))
+plot(f_saem_fomc$so, plot.type = "convergence")
+plot(f_saem_fomc$so, plot.type = "individual.fit")
+plot(f_saem_fomc$so, plot.type = "npde")
+plot(f_saem_fomc$so, plot.type = "vpc")
+
+f_mmkin_parent_tc <- update(f_mmkin_parent, error_model = "tc")
+f_saem_fomc_tc <- saem(f_mmkin_parent_tc["FOMC", ])
+compare.saemix(list(f_saem_fomc$so, f_saem_fomc_tc$so))
+
+sfo_sfo <- mkinmod(parent = mkinsub("SFO", "A1"),
+  A1 = mkinsub("SFO"))
+fomc_sfo <- mkinmod(parent = mkinsub("FOMC", "A1"),
+  A1 = mkinsub("SFO"))
+dfop_sfo <- mkinmod(parent = mkinsub("DFOP", "A1"),
+  A1 = mkinsub("SFO"))
+# The following fit uses analytical solutions for SFO-SFO and DFOP-SFO,
+# and compiled ODEs for FOMC that are much slower
+f_mmkin <- mmkin(list(
+    "SFO-SFO" = sfo_sfo, "FOMC-SFO" = fomc_sfo, "DFOP-SFO" = dfop_sfo),
+  ds, quiet = TRUE)
+# saem fits of SFO-SFO and DFOP-SFO to these data take about five seconds
+# each on this system, as we use analytical solutions written for saemix.
+# When using the analytical solutions written for mkin this took around
+# four minutes
+f_saem_sfo_sfo <- saem(f_mmkin["SFO-SFO", ])
+f_saem_dfop_sfo <- saem(f_mmkin["DFOP-SFO", ])
+# We can use print, plot and summary methods to check the results
+print(f_saem_dfop_sfo)
+plot(f_saem_dfop_sfo)
+summary(f_saem_dfop_sfo, data = TRUE)
+
+# The following takes about 6 minutes
+#f_saem_dfop_sfo_deSolve <- saem(f_mmkin["DFOP-SFO", ], solution_type = "deSolve",
+#  control = list(nbiter.saemix = c(200, 80), nbdisplay = 10))
+
+#saemix::compare.saemix(list(
+#  f_saem_dfop_sfo$so,
+#  f_saem_dfop_sfo_deSolve$so))
+
+# If the model supports it, we can also use eigenvalue based solutions, which
+# take a similar amount of time
+#f_saem_sfo_sfo_eigen <- saem(f_mmkin["SFO-SFO", ], solution_type = "eigen",
+#  control = list(nbiter.saemix = c(200, 80), nbdisplay = 10))
+}
+}
+\seealso{
+\link{summary.saem.mmkin} \link{plot.mixed.mmkin}
+}