Create saem generic for fitting saemix models

The reasons for this decision were
- Creating an saemix generic in the saemix package caused problems with
  roxygen, because functions like saemix.plot.xy were documented in
  their help files as S3 methods, although explicitly exported with
  @export
- Creating an saemix generic in this package is possible, but would
  make it necessary to load samix with exclude = "saemix" in order to
  avoid overwriting the generic when loading saemix.
- The return object of such an saemix generic in this package cannot
  be an S3 class with class attribute c("saemix.mmkin", "SaemixObject")
  similar to nlme.mmkin, as saemix returns an S4 class.
- Extending the S4 class SaemixObject using simple inheritance to
  a class SaemixMmkinObject with additional slots did not work
  as expected.  When the initialize method was left untouched, it
  prevented creation of an SaemixMmkinObject even if it was based
  on an initialised SaemixObject, as the initialize method seems
  to always be called by new(). This could potentially be circumvented
  by a coerce method. If an alternative initialize method was
  used, an SaemixMmkinObject could be created. However, the methods
  written for SaemixObjects only worked in some instances, either
  because they checked for the class, and not for class inheritance
  (like compare.saemix), or because the initialize method was called
  for some reason. Therefore, the idea of creating a derived S4 class
  was abandoned.
- A side effect of this decision is that the introduction of the saem
  generic opens the possibility to use the same generic also for other
  backends like nlmixr with the SAEM algorithm.

1 files changed, 0 insertions, 103 deletions

diff --git a/man/saemix.Rd b/man/saemix.Rd
deleted file mode 100644
index a664b0cc..00000000
--- a/man/saemix.Rd
+++ /dev/null
@@ -1,103 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/saemix.R
-\name{saemix}
-\alias{saemix}
-\alias{saemix.mmkin}
-\alias{saemix_model}
-\alias{saemix_data}
-\title{Create saemix models}
-\usage{
-saemix(model, data, control, ...)
-
-\method{saemix}{mmkin}(
-  model,
-  data,
-  control = list(displayProgress = FALSE, print = FALSE, save = FALSE, save.graphs =
-    FALSE),
-  cores = 1,
-  verbose = FALSE,
-  suppressPlot = TRUE,
-  ...
-)
-
-saemix_model(object, cores = 1, verbose = FALSE, ...)
-
-saemix_data(object, verbose = FALSE, ...)
-}
-\arguments{
-\item{model}{For the default method, this is an \link[saemix:saemixModel]{saemix::saemixModel} object.
-If this is an \link{mmkin} row object, the \link[saemix:saemixModel]{saemix::saemixModel} is created
-internally from the \link{mmkin} object.}
-
-\item{\dots}{Further parameters passed to \link[saemix:saemixData]{saemix::saemixData}
-and \link[saemix:saemixModel]{saemix::saemixModel}.}
-
-\item{cores}{The number of cores to be used for multicore processing using
-\code{\link[parallel:mclapply]{parallel::mclapply()}}. Using more than 1 core is experimental and may
-lead to uncontrolled forking, apparently depending on the BLAS version
-used.}
-
-\item{verbose}{Should we print information about created objects?}
-
-\item{object}{An \link{mmkin} row object containing several fits of the same
-\link{mkinmod} model to different datasets}
-}
-\value{
-An \link[saemix:SaemixObject-class]{saemix::SaemixObject}.
-
-An \link[saemix:SaemixModel-class]{saemix::SaemixModel} object.
-
-An \link[saemix:SaemixData-class]{saemix::SaemixData} object.
-}
-\description{
-The saemix function defined in this package is an S3 generic function
-using \code{\link[saemix:saemix]{saemix::saemix()}} as its method for \link[saemix:SaemixModel-class]{saemix::SaemixModel} objects.
-}
-\details{
-The method for mmkin row objects sets up a nonlinear mixed effects model for
-use with the saemix package. 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.
-
-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{
-# We can load saemix, but should exclude the saemix function
-# as it would mask our generic version of it
-library(saemix, exclude = "saemix")
-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, cores = 1,
-  state.ini = c(parent = 100), fixed_initials = "parent", quiet = TRUE)
-f_saemix_p0_fixed <- saemix(f_mmkin_parent_p0_fixed)
-
-f_mmkin_parent <- mmkin(c("SFO", "FOMC", "DFOP"), ds, quiet = TRUE)
-f_saemix_sfo <- saemix(f_mmkin_parent["SFO", ])
-f_saemix_fomc <- saemix(f_mmkin_parent["FOMC", ])
-f_saemix_dfop <- saemix(f_mmkin_parent["DFOP", ])
-
-# As this returns an SaemixObject, we can use functions from saemix
-compare.saemix(list(f_saemix_sfo, f_saemix_fomc, f_saemix_dfop))
-
-f_mmkin_parent_tc <- update(f_mmkin_parent, error_model = "tc")
-f_saemix_fomc_tc <- saemix(f_mmkin_parent_tc["FOMC", ])
-compare.saemix(list(f_saemix_fomc, f_saemix_fomc_tc))
-
-dfop_sfo <- mkinmod(parent = mkinsub("DFOP", "A1"),
-  A1 = mkinsub("SFO"))
-f_mmkin <- mmkin(list("DFOP-SFO" = dfop_sfo), ds, quiet = TRUE, solution_type = "analytical")
-# This takes about 4 minutes on my system
-f_saemix <- saemix(f_mmkin)
-
-# Using a single core, it takes about 6 minutes, using 10 cores it is slower
-# instead of faster
-f_mmkin_des <- mmkin(list("DFOP-SFO" = dfop_sfo), ds, quiet = TRUE, solution_type = "deSolve")
-f_saemix_des <- saemix(f_mmkin_des, cores = 1)
-compare.saemix(list(f_saemix, f_saemix_des))
-
-}
-}