Fix and rebuild documentation, see NEWS

I had to fix the two pathway vignettes, as they did not work with
the released version any more. So they and the multistart vignette
which got some small fixes as well were rebuilt.

Complete rebuild of the online docs with the released version. The
documentation of the 'hierarchial_kinetics' format had to be fixed
as well.

1 files changed, 117 insertions, 21 deletions

diff --git a/docs/reference/mhmkin.html b/docs/reference/mhmkin.html
index e4b3e9d0..0ca948c8 100644
--- a/docs/reference/mhmkin.html
+++ b/docs/reference/mhmkin.html
@@ -22,13 +22,13 @@ mixed-effects model fitting functions."><!-- mathjax --><script src="https://cdn
       </button>
       <span class="navbar-brand">
         <a class="navbar-link" href="../index.html">mkin</a>
-        <span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="Released version">1.2.0</span>
+        <span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="Released version">1.2.3</span>
       </span>
     </div>
 
     <div id="navbar" class="navbar-collapse collapse">
       <ul class="nav navbar-nav"><li>
-  <a href="../reference/index.html">Functions and data</a>
+  <a href="../reference/index.html">Reference</a>
 </li>
 <li class="dropdown">
   <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
@@ -39,6 +39,8 @@ mixed-effects model fitting functions."><!-- mathjax --><script src="https://cdn
   <ul class="dropdown-menu" role="menu"><li>
       <a href="../articles/mkin.html">Introduction to mkin</a>
     </li>
+    <li class="divider">
+    <li class="dropdown-header">Example evaluations with (generalised) nonlinear least squares</li>
     <li>
       <a href="../articles/FOCUS_D.html">Example evaluation of FOCUS Example Dataset D</a>
     </li>
@@ -46,22 +48,29 @@ mixed-effects model fitting functions."><!-- mathjax --><script src="https://cdn
       <a href="../articles/FOCUS_L.html">Example evaluation of FOCUS Laboratory Data L1 to L3</a>
     </li>
     <li>
-      <a href="../articles/web_only/dimethenamid_2018.html">Example evaluations of dimethenamid data from 2018 with nonlinear mixed-effects models</a>
+      <a href="../articles/web_only/FOCUS_Z.html">Example evaluation of FOCUS Example Dataset Z</a>
     </li>
+    <li class="divider">
+    <li class="dropdown-header">Example evaluations with hierarchical models (nonlinear mixed-effects models)</li>
     <li>
-      <a href="../articles/web_only/multistart.html">Short demo of the multistart method</a>
+      <a href="../articles/prebuilt/2022_dmta_parent.html">Testing hierarchical parent degradation kinetics with residue data on dimethenamid and dimethenamid-P</a>
     </li>
     <li>
-      <a href="../articles/web_only/compiled_models.html">Performance benefit by using compiled model definitions in mkin</a>
+      <a href="../articles/prebuilt/2022_dmta_pathway.html">Testing hierarchical pathway kinetics with residue data on dimethenamid and dimethenamid-P</a>
     </li>
     <li>
-      <a href="../articles/web_only/FOCUS_Z.html">Example evaluation of FOCUS Example Dataset Z</a>
+      <a href="../articles/prebuilt/2022_cyan_pathway.html">Testing hierarchical pathway kinetics with residue data on cyantraniliprole</a>
     </li>
     <li>
-      <a href="../articles/twa.html">Calculation of time weighted average concentrations with mkin</a>
+      <a href="../articles/web_only/dimethenamid_2018.html">Comparison of saemix and nlme evaluations of dimethenamid data from 2018</a>
     </li>
     <li>
-      <a href="../articles/web_only/NAFTA_examples.html">Example evaluation of NAFTA SOP Attachment examples</a>
+      <a href="../articles/web_only/multistart.html">Short demo of the multistart method</a>
+    </li>
+    <li class="divider">
+    <li class="dropdown-header">Performance</li>
+    <li>
+      <a href="../articles/web_only/compiled_models.html">Performance benefit by using compiled model definitions in mkin</a>
     </li>
     <li>
       <a href="../articles/web_only/benchmarks.html">Benchmark timings for mkin</a>
@@ -69,6 +78,14 @@ mixed-effects model fitting functions."><!-- mathjax --><script src="https://cdn
     <li>
       <a href="../articles/web_only/saem_benchmarks.html">Benchmark timings for saem.mmkin</a>
     </li>
+    <li class="divider">
+    <li class="dropdown-header">Miscellaneous</li>
+    <li>
+      <a href="../articles/twa.html">Calculation of time weighted average concentrations with mkin</a>
+    </li>
+    <li>
+      <a href="../articles/web_only/NAFTA_examples.html">Example evaluation of NAFTA SOP Attachment examples</a>
+    </li>
   </ul></li>
 <li>
   <a href="../news/index.html">News</a>
@@ -113,7 +130,6 @@ mhmkin(
   backend = "saemix",
   algorithm = "saem",
   no_random_effect = NULL,
-  auto_ranef_threshold = 3,
   ...,
   cores = if (Sys.info()["sysname"] == "Windows") 1 else parallel::detectCores(),
   cluster = NULL
@@ -150,16 +166,14 @@ supported</p></dd>
 
 
 <dt>no_random_effect</dt>
-<dd><p>Default is NULL and will be passed to <a href="saem.html">saem</a>. If
-you specify "auto", random effects are only included if the number
-of datasets in which the parameter passed the t-test is at least 'auto_ranef_threshold'.
-Beware that while this may make for convenient model reduction or even
-numerical stability of the algorithm, it will likely lead to
-underparameterised models.</p></dd>
-
-
-<dt>auto_ranef_threshold</dt>
-<dd><p>See 'no_random_effect.</p></dd>
+<dd><p>Default is NULL and will be passed to <a href="saem.html">saem</a>. If a
+character vector is supplied, it will be passed to all calls to <a href="saem.html">saem</a>,
+which will exclude random effects for all matching parameters. Alternatively,
+a list of character vectors or an object of class <a href="illparms.html">illparms.mhmkin</a> can be
+specified. They have to have the same dimensions that the return object of
+the current call will have, i.e. the number of rows must match the number
+of degradation models in the mmkin object(s), and the number of columns must
+match the number of error models used in the mmkin object(s).</p></dd>
 
 
 <dt>cores</dt>
@@ -203,7 +217,7 @@ and the error model names for the second index (column index), with class
 attribute 'mhmkin'.</p>
 
 
-<p>An object of class <code>mhmkin</code>.</p>
+<p>An object inheriting from <code>mhmkin</code>.</p>
     </div>
     <div id="see-also">
     <h2>See also</h2>
@@ -214,6 +228,88 @@ attribute 'mhmkin'.</p>
     <p>Johannes Ranke</p>
     </div>
 
+    <div id="ref-examples">
+    <h2>Examples</h2>
+    <div class="sourceCode"><pre class="sourceCode r"><code><span class="r-in"><span><span class="co"># \dontrun{</span></span></span>
+<span class="r-in"><span><span class="co"># We start with separate evaluations of all the first six datasets with two</span></span></span>
+<span class="r-in"><span><span class="co"># degradation models and two error models</span></span></span>
+<span class="r-in"><span><span class="va">f_sep_const</span> <span class="op">&lt;-</span> <span class="fu"><a href="mmkin.html">mmkin</a></span><span class="op">(</span><span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="st">"SFO"</span>, <span class="st">"FOMC"</span><span class="op">)</span>, <span class="va">ds_fomc</span><span class="op">[</span><span class="fl">1</span><span class="op">:</span><span class="fl">6</span><span class="op">]</span>, cores <span class="op">=</span> <span class="fl">2</span>, quiet <span class="op">=</span> <span class="cn">TRUE</span><span class="op">)</span></span></span>
+<span class="r-in"><span><span class="va">f_sep_tc</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/stats/update.html" class="external-link">update</a></span><span class="op">(</span><span class="va">f_sep_const</span>, error_model <span class="op">=</span> <span class="st">"tc"</span><span class="op">)</span></span></span>
+<span class="r-in"><span><span class="co"># The mhmkin function sets up hierarchical degradation models aka</span></span></span>
+<span class="r-in"><span><span class="co"># nonlinear mixed-effects models for all four combinations, specifying</span></span></span>
+<span class="r-in"><span><span class="co"># uncorrelated random effects for all degradation parameters</span></span></span>
+<span class="r-in"><span><span class="va">f_saem_1</span> <span class="op">&lt;-</span> <span class="fu">mhmkin</span><span class="op">(</span><span class="fu"><a href="https://rdrr.io/r/base/list.html" class="external-link">list</a></span><span class="op">(</span><span class="va">f_sep_const</span>, <span class="va">f_sep_tc</span><span class="op">)</span>, cores <span class="op">=</span> <span class="fl">2</span><span class="op">)</span></span></span>
+<span class="r-in"><span><span class="fu"><a href="status.html">status</a></span><span class="op">(</span><span class="va">f_saem_1</span><span class="op">)</span></span></span>
+<span class="r-out co"><span class="r-pr">#&gt;</span>            error</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> degradation const tc</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span>        SFO  OK    OK</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span>        FOMC OK    OK</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> </span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> OK: Fit terminated successfully</span>
+<span class="r-in"><span><span class="co"># The 'illparms' function shows that in all hierarchical fits, at least</span></span></span>
+<span class="r-in"><span><span class="co"># one random effect is ill-defined (the confidence interval for the</span></span></span>
+<span class="r-in"><span><span class="co"># random effect expressed as standard deviation includes zero)</span></span></span>
+<span class="r-in"><span><span class="fu"><a href="illparms.html">illparms</a></span><span class="op">(</span><span class="va">f_saem_1</span><span class="op">)</span></span></span>
+<span class="r-out co"><span class="r-pr">#&gt;</span>            error</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> degradation const        tc                        </span>
+<span class="r-out co"><span class="r-pr">#&gt;</span>        SFO  sd(parent_0) sd(parent_0)              </span>
+<span class="r-out co"><span class="r-pr">#&gt;</span>        FOMC sd(log_beta) sd(parent_0), sd(log_beta)</span>
+<span class="r-in"><span><span class="co"># Therefore we repeat the fits, excluding the ill-defined random effects</span></span></span>
+<span class="r-in"><span><span class="va">f_saem_2</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/stats/update.html" class="external-link">update</a></span><span class="op">(</span><span class="va">f_saem_1</span>, no_random_effect <span class="op">=</span> <span class="fu"><a href="illparms.html">illparms</a></span><span class="op">(</span><span class="va">f_saem_1</span><span class="op">)</span><span class="op">)</span></span></span>
+<span class="r-in"><span><span class="fu"><a href="status.html">status</a></span><span class="op">(</span><span class="va">f_saem_2</span><span class="op">)</span></span></span>
+<span class="r-out co"><span class="r-pr">#&gt;</span>            error</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> degradation const tc</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span>        SFO  OK    OK</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span>        FOMC OK    OK</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> </span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> OK: Fit terminated successfully</span>
+<span class="r-in"><span><span class="fu"><a href="illparms.html">illparms</a></span><span class="op">(</span><span class="va">f_saem_2</span><span class="op">)</span></span></span>
+<span class="r-out co"><span class="r-pr">#&gt;</span>            error</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> degradation const tc</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span>        SFO          </span>
+<span class="r-out co"><span class="r-pr">#&gt;</span>        FOMC         </span>
+<span class="r-in"><span><span class="co"># Model comparisons show that FOMC with two-component error is preferable,</span></span></span>
+<span class="r-in"><span><span class="co"># and confirms our reduction of the default parameter model</span></span></span>
+<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/stats/anova.html" class="external-link">anova</a></span><span class="op">(</span><span class="va">f_saem_1</span><span class="op">)</span></span></span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> Data: 95 observations of 1 variable(s) grouped in 6 datasets</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> </span>
+<span class="r-out co"><span class="r-pr">#&gt;</span>            npar    AIC    BIC     Lik</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> SFO const     5 574.40 573.35 -282.20</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> SFO tc        6 543.72 542.47 -265.86</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> FOMC const    7 489.67 488.22 -237.84</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> FOMC tc       8 406.11 404.44 -195.05</span>
+<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/stats/anova.html" class="external-link">anova</a></span><span class="op">(</span><span class="va">f_saem_2</span><span class="op">)</span></span></span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> Data: 95 observations of 1 variable(s) grouped in 6 datasets</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> </span>
+<span class="r-out co"><span class="r-pr">#&gt;</span>            npar    AIC    BIC     Lik</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> SFO const     4 572.22 571.39 -282.11</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> SFO tc        5 541.63 540.59 -265.81</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> FOMC const    6 487.38 486.13 -237.69</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> FOMC tc       6 402.12 400.88 -195.06</span>
+<span class="r-in"><span><span class="co"># The convergence plot for the selected model looks fine</span></span></span>
+<span class="r-in"><span><span class="fu">saemix</span><span class="fu">::</span><span class="fu"><a href="https://rdrr.io/r/base/plot.html" class="external-link">plot</a></span><span class="op">(</span><span class="va">f_saem_2</span><span class="op">[[</span><span class="st">"FOMC"</span>, <span class="st">"tc"</span><span class="op">]</span><span class="op">]</span><span class="op">$</span><span class="va">so</span>, plot.type <span class="op">=</span> <span class="st">"convergence"</span><span class="op">)</span></span></span>
+<span class="r-plt img"><img src="mhmkin-1.png" alt="" width="700" height="433"></span>
+<span class="r-in"><span><span class="co"># The plot of predictions versus data shows that we have a pretty data-rich</span></span></span>
+<span class="r-in"><span><span class="co"># situation with homogeneous distribution of residuals, because we used the</span></span></span>
+<span class="r-in"><span><span class="co"># same degradation model, error model and parameter distribution model that</span></span></span>
+<span class="r-in"><span><span class="co"># was used in the data generation.</span></span></span>
+<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/graphics/plot.default.html" class="external-link">plot</a></span><span class="op">(</span><span class="va">f_saem_2</span><span class="op">[[</span><span class="st">"FOMC"</span>, <span class="st">"tc"</span><span class="op">]</span><span class="op">]</span><span class="op">)</span></span></span>
+<span class="r-plt img"><img src="mhmkin-2.png" alt="" width="700" height="433"></span>
+<span class="r-in"><span><span class="co"># We can specify the same parameter model reductions manually</span></span></span>
+<span class="r-in"><span><span class="va">no_ranef</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/base/list.html" class="external-link">list</a></span><span class="op">(</span><span class="st">"parent_0"</span>, <span class="st">"log_beta"</span>, <span class="st">"parent_0"</span>, <span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="st">"parent_0"</span>, <span class="st">"log_beta"</span><span class="op">)</span><span class="op">)</span></span></span>
+<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/dim.html" class="external-link">dim</a></span><span class="op">(</span><span class="va">no_ranef</span><span class="op">)</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="fl">2</span>, <span class="fl">2</span><span class="op">)</span></span></span>
+<span class="r-in"><span><span class="va">f_saem_2m</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/stats/update.html" class="external-link">update</a></span><span class="op">(</span><span class="va">f_saem_1</span>, no_random_effect <span class="op">=</span> <span class="va">no_ranef</span><span class="op">)</span></span></span>
+<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/stats/anova.html" class="external-link">anova</a></span><span class="op">(</span><span class="va">f_saem_2m</span><span class="op">)</span></span></span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> Data: 95 observations of 1 variable(s) grouped in 6 datasets</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> </span>
+<span class="r-out co"><span class="r-pr">#&gt;</span>            npar    AIC    BIC     Lik</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> SFO const     4 572.22 571.39 -282.11</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> SFO tc        5 541.63 540.59 -265.81</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> FOMC const    6 487.38 486.13 -237.69</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> FOMC tc       6 402.12 400.88 -195.06</span>
+<span class="r-in"><span><span class="co"># }</span></span></span>
+</code></pre></div>
+    </div>
   </div>
   <div class="col-md-3 hidden-xs hidden-sm" id="pkgdown-sidebar">
     <nav id="toc" data-toggle="toc" class="sticky-top"><h2 data-toc-skip>Contents</h2>
@@ -226,7 +322,7 @@ attribute 'mhmkin'.</p>
 </div>
 
 <div class="pkgdown">
-  <p></p><p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.0.6.</p>
+  <p></p><p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.0.7.</p>
 </div>
 
       </footer></div>