path: root/man/saem.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/saemix.R
\name{saem}
\alias{saem}
\alias{saem.mmkin}
\alias{saemix_model}
\alias{saemix_data}
\title{Fit nonlinear mixed models with SAEM}
\usage{
saem(object, control, ...)

\method{saem}{mmkin}(
  object,
  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{object}{An \link{mmkin} row object containing several fits of the same
\link{mkinmod} model to different datasets}

\item{control}{Passed to \link[saemix:saemix]{saemix::saemix}}

\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{suppressPlot}{Should we suppress any plotting that is done
by the saemix function?}
}
\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, cores = 1,
  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, both are fast
f_mmkin <- mmkin(list(
    "SFO-SFO" = sfo_sfo, "FOMC-SFO" = fomc_sfo, "DFOP-SFO" = dfop_sfo),
  ds, quiet = TRUE)
# These 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", ])
summary(f_saem_dfop_sfo, data = FALSE)

# Using a single core, the following takes about 6 minutes, using 10 cores
# it is slower instead of faster
#f_saem_fomc <- saem(f_mmkin["FOMC-SFO", ], cores = 1)
}
}
\seealso{
\link{summary.saem.mmkin} \link{plot.mixed.mmkin}
}