Batch processing for hierarchical fits

- 'R/mhmkin.R': New method for performing multiple hierarchical mkin fits in one function call, optionally in parallel.

- 'R/saem.R': 'logLik' and 'update' methods for 'saem.mmkin' objects.

- 'R/illparms.R': Add methods for 'saem.mmkin' and 'mhmkin' objects.

tests: Use 2 cores on travis, should work according to docs

3 files changed, 112 insertions, 7 deletions

diff --git a/man/illparms.Rd b/man/illparms.Rd
index 7f70229d..90adf2bb 100644
--- a/man/illparms.Rd
+++ b/man/illparms.Rd
@@ -5,6 +5,9 @@
 \alias{illparms.mkinfit}
 \alias{illparms.mmkin}
 \alias{print.illparms.mmkin}
+\alias{illparms.saem.mmkin}
+\alias{illparms.mhmkin}
+\alias{print.illparms.mhmkin}
 \title{Method to get the names of ill-defined parameters}
 \usage{
 illparms(object, ...)
@@ -14,6 +17,12 @@ illparms(object, ...)
 \method{illparms}{mmkin}(object, conf.level = 0.95, ...)
 
 \method{print}{illparms.mmkin}(x, ...)
+
+\method{illparms}{saem.mmkin}(object, conf.level = 0.95, random = TRUE, errmod = TRUE, ...)
+
+\method{illparms}{mhmkin}(object, conf.level = 0.95, random = TRUE, errmod = TRUE, ...)
+
+\method{print}{illparms.mhmkin}(x, ...)
 }
 \arguments{
 \item{object}{The object to investigate}
@@ -23,14 +32,32 @@ illparms(object, ...)
 \item{conf.level}{The confidence level for checking p values}
 
 \item{x}{The object to be printed}
+
+\item{random}{For hierarchical fits, should random effects be tested?}
+
+\item{errmod}{For hierarchical fits, should error model parameters be
+tested?}
 }
 \value{
-For \link{mkinfit} objects, a character vector of parameter names
-For \link{mmkin} objects, an object of class 'illparms.mmkin' with a
-suitable printing method.
+For \link{mkinfit} or \link{saem} objects, a character vector of parameter
+names. For \link{mmkin} or \link{mhmkin} objects, a matrix like object of class
+'illparms.mmkin' or 'illparms.mhmkin'. The latter objects have a suitable
+printing method.
 }
 \description{
-Method to get the names of ill-defined parameters
+The method for generalised nonlinear regression fits as obtained
+with \link{mkinfit} and \link{mmkin} checks if the degradation parameters
+pass the Wald test (in degradation kinetics often simply called t-test) for
+significant difference from zero. For this test, the parameterisation
+without parameter transformations is used.
+}
+\details{
+The method for hierarchical model fits, also known as nonlinear
+mixed-effects model fits as obtained with \link{saem} and \link{mhmkin}
+checks if any of the confidence intervals for the random
+effects expressed as standard deviations include zero, and if
+the confidence intervals for the error model parameters include
+zero.
 }
 \examples{
 fit <- mkinfit("FOMC", FOCUS_2006_A, quiet = TRUE)
diff --git a/man/mhmkin.Rd b/man/mhmkin.Rd
new file mode 100644
index 00000000..0ef1599e
--- /dev/null
+++ b/man/mhmkin.Rd
@@ -0,0 +1,75 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/mhmkin.R
+\name{mhmkin}
+\alias{mhmkin}
+\alias{mhmkin.list}
+\alias{[.mhmkin}
+\alias{print.mhmkin}
+\title{Fit nonlinear mixed-effects models built from one or more kinetic
+degradation models and one or more error models}
+\usage{
+mhmkin(objects, backend = "saemix", algorithm = "saem", ...)
+
+\method{mhmkin}{list}(
+  objects,
+  backend = "saemix",
+  ...,
+  cores = if (Sys.info()["sysname"] == "Windows") 1 else parallel::detectCores(),
+  cluster = NULL
+)
+
+\method{[}{mhmkin}(x, i, j, ..., drop = FALSE)
+
+\method{print}{mhmkin}(x, ...)
+}
+\arguments{
+\item{objects}{A list of \link{mmkin} objects containing fits of the same
+degradation models to the same data, but using different error models.}
+
+\item{backend}{The backend to be used for fitting. Currently, only saemix is
+supported}
+
+\item{algorithm}{The algorithm to be used for fitting (currently not used)}
+
+\item{\dots}{Further arguments that will be passed to the nonlinear mixed-effects
+model fitting function.}
+
+\item{cores}{The number of cores to be used for multicore processing. This
+is only used when the \code{cluster} argument is \code{NULL}. On Windows
+machines, cores > 1 is not supported, you need to use the \code{cluster}
+argument to use multiple logical processors. Per default, all cores detected
+by \code{\link[parallel:detectCores]{parallel::detectCores()}} are used, except on Windows where the default
+is 1.}
+
+\item{cluster}{A cluster as returned by \link{makeCluster} to be used for
+parallel execution.}
+
+\item{x}{An \link{mhmkin} object.}
+
+\item{i}{Row index selecting the fits for specific models}
+
+\item{j}{Column index selecting the fits to specific datasets}
+
+\item{drop}{If FALSE, the method always returns an mhmkin object, otherwise
+either a list of fit objects or a single fit object.}
+}
+\value{
+A two-dimensional \link{array} of fit objects and/or try-errors that can
+be indexed using the degradation model names for the first index (row index)
+and the error model names for the second index (column index), with class
+attribute 'mhmkin'.
+
+An object of class \code{\link{mhmkin}}.
+}
+\description{
+The name of the methods expresses that (\strong{m}ultiple) \strong{h}ierarchichal
+(also known as multilevel) \strong{m}ulticompartment \strong{kin}etic models are
+fitted. Our kinetic models are nonlinear, so we can use various nonlinear
+mixed-effects model fitting functions.
+}
+\seealso{
+\code{\link{[.mhmkin}} for subsetting \link{mhmkin} objects
+}
+\author{
+Johannes Ranke
+}
diff --git a/man/saem.Rd b/man/saem.Rd
index 0c066dd2..a202f52f 100644
--- a/man/saem.Rd
+++ b/man/saem.Rd
@@ -49,9 +49,9 @@ saemix_data(object, verbose = FALSE, ...)
 
 \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.}
+are done in 'saemix' for the supported cases, i.e. (as of version 1.1.2)
+SFO, FOMC, DFOP and HS without fixing \code{parent_0}, and SFO or DFOP with
+one SFO metabolite.}
 
 \item{degparms_start}{Parameter values given as a named numeric vector will
 be used to override the starting values obtained from the 'mmkin' object.}
@@ -120,6 +120,9 @@ 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", ])
+illparms(f_saem_dfop)
+update(f_saem_dfop, covariance.model = diag(c(1, 1, 1, 0)))
+AIC(f_saem_dfop)
 
 # The returned saem.mmkin object contains an SaemixObject, therefore we can use
 # functions from saemix