Add summary method for nlme.mmkin objects

Improve and update docs

4 files changed, 113 insertions, 10 deletions

diff --git a/man/nlme.mmkin.Rd b/man/nlme.mmkin.Rd
index 041b939a..bf45c6e5 100644
--- a/man/nlme.mmkin.Rd
+++ b/man/nlme.mmkin.Rd
@@ -74,6 +74,11 @@ 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.
 }
+\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
+\code{\link[nlme:intervals]{nlme::intervals()}}, \code{\link[nlme:anova.lme]{nlme::anova.lme()}} and \code{\link[nlme:coef.lme]{nlme::coef.lme()}}.
+}
 \examples{
 ds <- lapply(experimental_data_for_UBA_2019[6:10],
  function(x) subset(x$data[c("name", "time", "value")], name == "parent"))
diff --git a/man/plot.nlme.mmkin.Rd b/man/plot.nlme.mmkin.Rd
index 6944d4b1..5f0f0ef1 100644
--- a/man/plot.nlme.mmkin.Rd
+++ b/man/plot.nlme.mmkin.Rd
@@ -50,6 +50,10 @@ predicted values?}
 \item{maxabs}{Maximum absolute value of the residuals. This is used for the
 scaling of the y axis and defaults to "auto".}
 
+\item{ncol.legend}{Number of columns to use in the legend}
+
+\item{nrow.legend}{Number of rows to use in the legend}
+
 \item{rel.height.legend}{The relative height of the legend shown on top}
 
 \item{rel.height.bottom}{The relative height of the bottom plot row}
@@ -78,7 +82,8 @@ ds <- lapply(experimental_data_for_UBA_2019[6:10],
 names(ds) <- paste0("ds ", 6:10)
 dfop_sfo <- mkinmod(parent = mkinsub("DFOP", "A1"),
   A1 = mkinsub("SFO"), quiet = TRUE)
-f <- mmkin(list("DFOP-SFO" = dfop_sfo), ds, quiet = TRUE, cores = 1)
+\dontrun{
+f <- mmkin(list("DFOP-SFO" = dfop_sfo), ds, quiet = TRUE)
 plot(f[, 3:4], standardized = TRUE)
 
 library(nlme)
@@ -87,6 +92,7 @@ library(nlme)
 f_nlme <- nlme(f, control = list(pnlsMaxIter = 120, tolerance = 1e-3))
 plot(f_nlme)
 }
+}
 \author{
 Johannes Ranke
 }
diff --git a/man/sigma_twocomp.Rd b/man/sigma_twocomp.Rd
index ed79d493..d205a2f7 100644
--- a/man/sigma_twocomp.Rd
+++ b/man/sigma_twocomp.Rd
@@ -44,15 +44,8 @@ f_gnls <- gnls(value ~ SSasymp(time, 0, parent_0, lrc),
   data = d_syn, na.action = na.omit,
   start = list(parent_0 = 100, lrc = -3))
 if (length(findFunction("varConstProp")) > 0) {
-  f_gnls_tc <- gnls(value ~ SSasymp(time, 0, parent_0, lrc),
-    data = d_syn, na.action = na.omit,
-    start = list(parent_0 = 100, lrc = -3),
-    weights = varConstProp())
-  f_gnls_tc_sf <- gnls(value ~ SSasymp(time, 0, parent_0, lrc),
-    data = d_syn, na.action = na.omit,
-    start = list(parent_0 = 100, lrc = -3),
-    control = list(sigma = 1),
-    weights = varConstProp())
+  f_gnls_tc <- update(f_gnls, weights = varConstProp())
+  f_gnls_tc_sf <- update(f_gnls_tc, control = list(sigma = 1))
 }
 f_mkin <- mkinfit("SFO", d_syn, error_model = "const", quiet = TRUE)
 f_mkin_tc <- mkinfit("SFO", d_syn, error_model = "tc", quiet = TRUE)
diff --git a/man/summary.nlme.mmkin.Rd b/man/summary.nlme.mmkin.Rd
new file mode 100644
index 00000000..ea625dd7
--- /dev/null
+++ b/man/summary.nlme.mmkin.Rd
@@ -0,0 +1,99 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/summary.nlme.mmkin.R
+\name{summary.nlme.mmkin}
+\alias{summary.nlme.mmkin}
+\alias{print.summary.nlme.mmkin}
+\title{Summary method for class "nlme.mmkin"}
+\usage{
+\method{summary}{nlme.mmkin}(
+  object,
+  data = FALSE,
+  verbose = FALSE,
+  distimes = TRUE,
+  alpha = 0.05,
+  ...
+)
+
+\method{print}{summary.nlme.mmkin}(x, digits = max(3, getOption("digits") - 3), verbose = x$verbose, ...)
+}
+\arguments{
+\item{object}{an object of class \link{nlme.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{alpha}{error level for confidence interval estimation from the t
+distribution}
+
+\item{\dots}{optional arguments passed to methods like \code{print}.}
+
+\item{x}{an object of class \link{summary.nlme.mmkin}}
+
+\item{digits}{Number of digits to use for printing}
+}
+\value{
+The summary function returns a list based on the \link{nlme} object
+obtained in the fit, with at least the following additional components
+\item{nlmeversion, mkinversion, Rversion}{The nlme, 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]]
+})
+
+# Evaluate using mmkin and nlme
+library(nlme)
+f_mmkin <- mmkin("SFO", ds_sfo_syn, quiet = TRUE, error_model = "tc", cores = 1)
+f_nlme <- nlme(f_mmkin)
+summary(f_nlme, data = TRUE)
+
+}
+\author{
+Johannes Ranke for the mkin specific parts
+José Pinheiro and Douglas Bates for the components inherited from nlme
+}