From b76e401a854021eaeda6f8ba262baf37b4ecfac2 Mon Sep 17 00:00:00 2001
From: Johannes Ranke <jranke@uni-bremen.de>
Date: Thu, 13 Oct 2022 03:51:22 +0200
Subject: Select best fit from multistart, use in parhist

- Add 'best' and 'which.best' generics with methods for multistart
objects
- Per default, scale the parameters in parhist plots using the fit with
the highest log likelihood.
---
 man/multistart.Rd | 20 +++++++++++++++++++-
 man/parhist.Rd    | 16 +++++++++++++---
 2 files changed, 32 insertions(+), 4 deletions(-)

(limited to 'man')

diff --git a/man/multistart.Rd b/man/multistart.Rd
index 78ff4614..d20c0465 100644
--- a/man/multistart.Rd
+++ b/man/multistart.Rd
@@ -4,6 +4,10 @@
 \alias{multistart}
 \alias{multistart.saem.mmkin}
 \alias{print.multistart}
+\alias{best}
+\alias{best.default}
+\alias{which.best}
+\alias{which.best.default}
 \title{Perform a hierarchical model fit with multiple starting values}
 \usage{
 multistart(
@@ -17,6 +21,14 @@ multistart(
 \method{multistart}{saem.mmkin}(object, n = 50, cores = 1, cluster = NULL, ...)
 
 \method{print}{multistart}(x, ...)
+
+best(object, ...)
+
+\method{best}{default}(object, ...)
+
+which.best(object, ...)
+
+\method{which.best}{default}(object, ...)
 }
 \arguments{
 \item{object}{The fit object to work with}
@@ -36,6 +48,10 @@ for parallel execution.}
 \value{
 A list of \link{saem.mmkin} objects, with class attributes
 'multistart.saem.mmkin' and 'multistart'.
+
+The object with the highest likelihood
+
+The index of the object with the highest likelihood
 }
 \description{
 The purpose of this method is to check if a certain algorithm for fitting
@@ -69,8 +85,10 @@ f_mmkin <- mmkin("DFOP", dmta_ds, error_model = "tc", cores = 7, quiet = TRUE)
 f_saem_full <- saem(f_mmkin)
 f_saem_full_multi <- multistart(f_saem_full, n = 16, cores = 16)
 parhist(f_saem_full_multi, lpos = "bottomright")
+illparms(f_saem_full)
 
-f_saem_reduced <- update(f_saem_full, covariance.model = diag(c(1, 1, 0, 1)))
+f_saem_reduced <- update(f_saem_full, no_random_effect = "log_k2")
+illparms(f_saem_reduced)
 # On Windows, we need to create a cluster first. When working with
 # such a cluster, we need to export the mmkin object to the cluster
 # nodes, as it is referred to when updating the saem object on the nodes.
diff --git a/man/parhist.Rd b/man/parhist.Rd
index a8319283..67bbadad 100644
--- a/man/parhist.Rd
+++ b/man/parhist.Rd
@@ -4,11 +4,20 @@
 \alias{parhist}
 \title{Plot parameter distributions from multistart objects}
 \usage{
-parhist(object, lpos = "bottomleft", main = "", ...)
+parhist(
+  object,
+  scale = c("best", "median"),
+  lpos = "bottomleft",
+  main = "",
+  ...
+)
 }
 \arguments{
 \item{object}{The \link{multistart} object}
 
+\item{scale}{By default, scale parameters using the best available fit.
+If 'median', parameters are scaled using the median parameters from all fits.}
+
 \item{lpos}{Positioning of the legend.}
 
 \item{main}{Title of the plot}
@@ -16,8 +25,9 @@ parhist(object, lpos = "bottomleft", main = "", ...)
 \item{\dots}{Passed to \link{boxplot}}
 }
 \description{
-Produces a boxplot with all parameters from the multiple runs, divided by
-using their medians as in the paper by Duchesne et al. (2021).
+Produces a boxplot with all parameters from the multiple runs, scaled
+either by the parameters of the run with the highest likelihood,
+or by their medians as proposed in the paper by Duchesne et al. (2021).
 }
 \references{
 Duchesne R, Guillemin A, Gandrillon O, Crauste F. Practical
-- 
cgit v1.2.1