Improve saem method, add summary

Also make the endpoints function work for saem objects.

3 files changed, 108 insertions, 8 deletions

diff --git a/man/endpoints.Rd b/man/endpoints.Rd
index 9c354ae9..72487717 100644
--- a/man/endpoints.Rd
+++ b/man/endpoints.Rd
@@ -8,8 +8,11 @@ with mkinfit}
 endpoints(fit)
 }
 \arguments{
-\item{fit}{An object of class \code{\link{mkinfit}} or
-\code{\link{nlme.mmkin}}}
+\item{fit}{An object of class \link{mkinfit}, \link{nlme.mmkin} or
+\link{saem.mmkin}. Or another object that has list components
+mkinmod containing an \link{mkinmod} degradation model, and two numeric vectors,
+bparms.optim and bparms.fixed, that contain parameter values
+for that model.}
 }
 \value{
 A list with a matrix of dissipation times named distimes,
@@ -24,8 +27,13 @@ for one of the parents or metabolites, the Eigenvalues are returned. These
 are equivalent to the rate constants of the DFOP model, but with the
 advantage that the SFORB model can also be used for metabolites.
 }
+\details{
+Additional DT50 values are calculated from the FOMC DT90 and k1 and k2 from
+HS and DFOP, as well as from Eigenvalues b1 and b2 of any SFORB models
+}
 \note{
-The function is used internally by \code{\link{summary.mkinfit}}.
+The function is used internally by \link{summary.mkinfit},
+\link{summary.nlme.mmkin} and \link{summary.saem.mmkin}.
 }
 \examples{
 
@@ -42,4 +50,3 @@ The function is used internally by \code{\link{summary.mkinfit}}.
 \author{
 Johannes Ranke
 }
-\keyword{manip}
diff --git a/man/saem.Rd b/man/saem.Rd
index 39b66448..96b8b55a 100644
--- a/man/saem.Rd
+++ b/man/saem.Rd
@@ -43,7 +43,8 @@ used.}
 by the saemix function?}
 }
 \value{
-An \link[saemix:SaemixObject-class]{saemix::SaemixObject}.
+An S3 object of class 'saem.mmkin', containing the fitted
+\link[saemix:SaemixObject-class]{saemix::SaemixObject} as a list component named 'so'.
 
 An \link[saemix:SaemixModel-class]{saemix::SaemixModel} object.
 
@@ -51,8 +52,8 @@ 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
-to the expectation maximisation algorithm (SAEM).
+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
@@ -95,6 +96,9 @@ f_mmkin_des <- mmkin(list("DFOP-SFO" = dfop_sfo), ds, quiet = TRUE, solution_typ
 # Using a single core, the following takes about 6 minutes, using 10 cores
 # it is slower instead of faster
 f_saem_des <- saem(f_mmkin_des, cores = 1)
-compare.saemix(list(f_saemix$so, f_saemix_des$so))
+compare.saemix(list(f_saem$so, f_saem_des$so))
 }
 }
+\seealso{
+\link{summary.saem.mmkin}
+}
diff --git a/man/summary.saem.mmkin.Rd b/man/summary.saem.mmkin.Rd
new file mode 100644
index 00000000..0f0d8264
--- /dev/null
+++ b/man/summary.saem.mmkin.Rd
@@ -0,0 +1,89 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/summary.saem.mmkin.R
+\name{summary.saem.mmkin}
+\alias{summary.saem.mmkin}
+\alias{print.summary.saem.mmkin}
+\title{Summary method for class "saem.mmkin"}
+\usage{
+\method{summary}{saem.mmkin}(object, data = FALSE, verbose = FALSE, distimes = TRUE, ...)
+
+\method{print}{summary.saem.mmkin}(x, digits = max(3, getOption("digits") - 3), verbose = x$verbose, ...)
+}
+\arguments{
+\item{object}{an object of class \link{saem.mmkin}}
+
+\item{data}{logical, indicating whether the full data should be included in
+the summary.}
+
+\item{verbose}{Should the summary be verbose?}
+
+\item{distimes}{logical, indicating whether DT50 and DT90 values should be
+included.}
+
+\item{\dots}{optional arguments passed to methods like \code{print}.}
+
+\item{x}{an object of class \link{summary.saem.mmkin}}
+
+\item{digits}{Number of digits to use for printing}
+}
+\value{
+The summary function returns a list based on the \link[saemix:SaemixObject-class]{saemix::SaemixObject}
+obtained in the fit, with at least the following additional components
+\item{saemixversion, mkinversion, Rversion}{The saemix, mkin and R versions used}
+\item{date.fit, date.summary}{The dates where the fit and the summary were
+produced}
+\item{diffs}{The differential equations used in the degradation model}
+\item{use_of_ff}{Was maximum or minimum use made of formation fractions}
+\item{data}{The data}
+\item{confint_trans}{Transformed parameters as used in the optimisation, with confidence intervals}
+\item{confint_back}{Backtransformed parameters, with confidence intervals if available}
+\item{ff}{The estimated formation fractions derived from the fitted
+model.}
+\item{distimes}{The DT50 and DT90 values for each observed variable.}
+\item{SFORB}{If applicable, eigenvalues of SFORB components of the model.}
+The print method is called for its side effect, i.e. printing the summary.
+}
+\description{
+Lists model equations, initial parameter values, optimised parameters
+for fixed effects (population), random effects (deviations from the
+population mean) and residual error model, as well as the resulting
+endpoints such as formation fractions and DT50 values. Optionally
+(default is FALSE), the data are listed in full.
+}
+\examples{
+# Generate five datasets following SFO kinetics
+sampling_times = c(0, 1, 3, 7, 14, 28, 60, 90, 120)
+dt50_sfo_in_pop <- 50
+k_in_pop <- log(2) / dt50_sfo_in_pop
+set.seed(1234)
+k_in <- rlnorm(5, log(k_in_pop), 0.5)
+SFO <- mkinmod(parent = mkinsub("SFO"))
+
+pred_sfo <- function(k) {
+  mkinpredict(SFO,
+    c(k_parent = k),
+    c(parent = 100),
+    sampling_times)
+}
+
+ds_sfo_mean <- lapply(k_in, pred_sfo)
+names(ds_sfo_mean) <- paste("ds", 1:5)
+
+ds_sfo_syn <- lapply(ds_sfo_mean, function(ds) {
+  add_err(ds,
+    sdfunc = function(value) sqrt(1^2 + value^2 * 0.07^2),
+    n = 1)[[1]]
+})
+
+\dontrun{
+# Evaluate using mmkin and saem
+f_mmkin <- mmkin("SFO", ds_sfo_syn, quiet = TRUE, error_model = "tc", cores = 1)
+f_saem <- saem(f_mmkin)
+summary(f_saem, data = TRUE)
+}
+
+}
+\author{
+Johannes Ranke for the mkin specific parts
+saemix authors for the parts inherited from saemix.
+}