12 files changed, 628 insertions, 8 deletions
diff --git a/docs/dev/reference/example_analysis/dlls/sforb_sfo2.so b/docs/dev/reference/example_analysis/dlls/sforb_sfo2.so
new file mode 100755
index 00000000..a692256d
--- /dev/null
+++ b/docs/dev/reference/example_analysis/dlls/sforb_sfo2.so
diff --git a/docs/dev/reference/example_analysis/example_analysis.Rmd b/docs/dev/reference/example_analysis/example_analysis.Rmd
new file mode 100644
index 00000000..38a6bd20
--- /dev/null
+++ b/docs/dev/reference/example_analysis/example_analysis.Rmd
@@ -0,0 +1,314 @@
+---
+title: "Hierarchical kinetic modelling of degradation data"
+author:
+date:
+output: mkin::hierarchical_kinetics
+geometry: margin=2cm
+---
+
+\clearpage
+
+# Setup
+
+```{r packages, cache = FALSE, message = FALSE}
+library(mkin)
+library(knitr)
+library(saemix)
+library(parallel)
+library(readxl)
+```
+
+```{r n_cores, cache = FALSE}
+n_cores <- detectCores()
+
+if (Sys.info()["sysname"] == "Windows") {
+  cl <- makePSOCKcluster(n_cores)
+} else {
+  cl <- makeForkCluster(n_cores)
+}
+```
+
+\clearpage
+
+# Introduction
+
+This report shows hierarchical kinetic modelling for ...
+The data were obtained from ...
+
+```{r ds}
+data_path <- system.file(
+  "testdata", "lambda-cyhalothrin_soil_efsa_2014.xlsx",
+  package = "mkin")
+ds <- read_spreadsheet(data_path, valid_datasets = c(1:4, 7:13))
+covariates <- attr(ds, "covariates")
+```
+
+The covariate data are shown below.
+
+```{r results = "asis", dependson = "ds", echo = FALSE}
+kable(covariates, caption = "Covariate data for all datasets")
+```
+
+\clearpage
+
+The datasets with the residue time series are shown in the tables below. Please
+refer to the spreadsheet for details like data sources, treatment of values
+below reporting limits and time step normalisation factors.
+
+```{r results = "asis", dependson = "ds", echo = FALSE}
+for (ds_name in names(ds)) {
+  print(
+    kable(mkin_long_to_wide(ds[[ds_name]]),
+      caption = paste("Dataset", ds_name),
+      booktabs = TRUE, row.names = FALSE))
+  cat("\n\\clearpage\n")
+}
+```
+
+# Parent only evaluations
+
+The following code performs separate fits of the candidate degradation models
+to all datasets using constant variance and the two-component error model.
+
+```{r parent-sep, dependson = "ds"}
+parent_deg_mods <- c("SFO", "FOMC", "DFOP", "SFORB")
+errmods <- c(const = "constant variance", tc = "two-component error")
+parent_sep_const <- mmkin(
+  parent_deg_mods, ds,
+  error_model = "const",
+  cluster = cl, quiet = TRUE)
+parent_sep_tc <- update(parent_sep_const, error_model = "tc")
+```
+
+To select the parent model, the corresponding hierarchical fits are performed below.
+
+```{r parent-mhmkin, dependson = "parent-sep"}
+parent_mhmkin <- mhmkin(list(parent_sep_const, parent_sep_tc), cluster = cl)
+status(parent_mhmkin) |> kable()
+```
+
+All fits terminate without errors (status OK). The check for ill-defined
+parameters shows that not all random effect parameters can be robustly
+quantified.
+
+```{r dependson = "parent_mhmkin"}
+illparms(parent_mhmkin) |> kable()
+```
+
+Therefore, the fits are updated, excluding random effects that were
+ill-defined according to the `illparms` function. The status of the fits
+is checked.
+
+```{r parent-mhmkin-refined}
+parent_mhmkin_refined <- update(parent_mhmkin,
+  no_random_effect = illparms(parent_mhmkin))
+status(parent_mhmkin_refined) |> kable()
+```
+
+Also, it is checked if the AIC values of the refined fits are actually smaller
+than the AIC values of the original fits.
+
+```{r dependson = "parent-mhmkin-refined"}
+(AIC(parent_mhmkin_refined) < AIC(parent_mhmkin)) |> kable()
+```
+
+From the refined fits, the most suitable model is selected using the AIC.
+
+```{r parent-best, dependson = "parent-mhmkin"}
+aic_parent <- AIC(parent_mhmkin_refined)
+min_aic <- which(aic_parent == min(aic_parent), arr.ind = TRUE)
+best_degmod_parent <- rownames(aic_parent)[min_aic[1]]
+best_errmod_parent <- colnames(aic_parent)[min_aic[2]]
+anova(parent_mhmkin_refined) |> kable(digits = 1)
+parent_best <- parent_mhmkin_refined[[best_degmod_parent, best_errmod_parent]]
+```
+
+Based on the AIC, the combination of the `r best_degmod_parent` degradation
+model with the error model `r errmods[best_errmod_parent]` is identified to
+be most suitable for the degradation of the parent. The check below
+confirms that no ill-defined parameters remain for this combined model.
+
+```{r dependson = "parent-best"}
+illparms(parent_best)
+```
+
+The corresponding fit is plotted below.
+
+```{r dependson = "parent-best"}
+plot(parent_best)
+```
+The fitted parameters, together with approximate confidence
+intervals are listed below.
+
+```{r dependson = "parent-best"}
+parms(parent_best, ci = TRUE) |> kable(digits = 3)
+```
+
+To investigate a potential covariate influence on degradation parameters, a
+covariate model is added to the hierarchical model for each of the degradation
+parameters with well-defined random effects. Also, a version with covariate
+models for both of them is fitted.
+
+```{r parent-best-pH}
+parent_best_pH_1 <- update(parent_best, covariates = covariates,
+  covariate_models = list(log_k_lambda_free ~ pH))
+parent_best_pH_2 <- update(parent_best, covariates = covariates,
+  covariate_models = list(log_k_lambda_bound_free ~ pH))
+parent_best_pH_3 <- update(parent_best, covariates = covariates,
+  covariate_models = list(log_k_lambda_free ~ pH, log_k_lambda_bound_free ~ pH))
+```
+
+The resulting models are compared.
+
+```{r dependson = "parent-best-pH"}
+anova(parent_best, parent_best_pH_1, parent_best_pH_2, parent_best_pH_3) |>
+  kable(digits = 1)
+```
+
+The model fit with the lowest AIC is the one with a pH correlation of the
+desorption rate constant `k_lambda_bound_free`. Plot and parameter listing
+of this fit are shown below. Also, it is confirmed that no ill-defined
+variance parameters are found.
+
+```{r dependson = "parent-best-pH"}
+plot(parent_best_pH_2)
+```
+
+```{r dependson = "parent-best-pH"}
+illparms(parent_best_pH_2)
+parms(parent_best_pH_2, ci = TRUE) |> kable(digits = 3)
+```
+
+\clearpage
+
+# Pathway fits
+
+As an example of a pathway fit, a model with SFORB for the parent compound and
+parallel formation of two metabolites is set up.
+
+```{r path-1-degmod}
+if (!dir.exists("dlls")) dir.create("dlls")
+
+m_sforb_sfo2 = mkinmod(
+  lambda = mkinsub("SFORB", to = c("c_V", "c_XV")),
+  c_V = mkinsub("SFO"),
+  c_XV = mkinsub("SFO"),
+  name = "sforb_sfo2",
+  dll_dir = "dlls",
+  overwrite = TRUE, quiet = TRUE
+)
+```
+
+Separate evaluations of all datasets are performed with constant variance
+and using two-component error.
+
+```{r path-1-sep, dependson = c("path-1-degmod", "ds")}
+sforb_sep_const <- mmkin(list(sforb_path = m_sforb_sfo2), ds,
+  cluster = cl, quiet = TRUE)
+sforb_sep_tc <- update(sforb_sep_const, error_model = "tc")
+```
+
+The separate fits with constant variance are plotted.
+
+```{r dependson = "path-1-sep", fig.height = 9}
+plot(mixed(sforb_sep_const))
+```
+
+The two corresponding hierarchical fits, with the random effects for the parent
+degradation parameters excluded as discussed above, and including the covariate
+model that was identified for the parent degradation, are attempted below.
+
+```{r path-1, dependson = "path-1-sep"}
+path_1 <- mhmkin(list(sforb_sep_const, sforb_sep_tc),
+  no_random_effect = c("lambda_free_0", "log_k_lambda_free_bound"),
+  covariates = covariates, covariate_models = list(log_k_lambda_bound_free ~ pH),
+  cluster = cl)
+```
+
+```{r dependson = "path-1"}
+status(path_1) |> kable()
+```
+
+The status information shows that both fits were successfully completed.
+
+```{r dependson = "path-1"}
+anova(path_1) |> kable(digits = 1)
+```
+Model comparison shows that the two-component error model provides a much
+better fit.
+
+```{r dependson = "path-1"}
+illparms(path_1[["sforb_path", "tc"]])
+```
+
+Two ill-defined variance components are found. Therefore, the fit is
+repeated with the corresponding random effects removed.
+
+```{r path-1-refined, dependson = "path-1"}
+path_1_refined <- update(path_1[["sforb_path", "tc"]],
+  no_random_effect = c("lambda_free_0", "log_k_lambda_free_bound",
+    "log_k_c_XV", "f_lambda_ilr_2"))
+```
+
+The empty output of the illparms function indicates that there are no
+ill-defined parameters remaining in the refined fit.
+
+```{r dependson = "path-1-refined"}
+illparms(path_1_refined)
+```
+
+Below, the refined fit is plotted and the fitted parameters are shown together
+with their 95% confidence intervals.
+
+```{r dependson = "path-1-refined", fig.height = 9}
+plot(path_1_refined)
+```
+
+```{r dependson = "path-1-refined", fig.height = 9}
+parms(path_1_refined, ci = TRUE) |> kable(digits = 3)
+```
+
+\clearpage
+
+# Appendix
+
+## Listings of initial parent fits
+
+```{r listings-parent, results = "asis", echo = FALSE, dependson = "parent_mhmkin"}
+for (deg_mod in parent_deg_mods) {
+  for (err_mod in c("const", "tc")) {
+    caption <- paste("Hierarchical", deg_mod, "fit with", errmods[err_mod])
+    tex_listing(parent_mhmkin[[deg_mod, err_mod]], caption)
+  }
+}
+```
+
+## Listings of refined parent fits
+
+```{r listings-parent-refined, results = "asis", echo = FALSE, dependson = "parent_mhmkin_refined"}
+for (deg_mod in parent_deg_mods) {
+  for (err_mod in c("const", "tc")) {
+    caption <- paste("Refined hierarchical", deg_mod, "fit with", errmods[err_mod])
+    tex_listing(parent_mhmkin_refined[[deg_mod, err_mod]], caption)
+  }
+}
+```
+
+## Listings of pathway fits
+
+```{r listings-path-1, results = "asis", echo = FALSE, dependson = "path-1-refined"}
+tex_listing(path_1[["sforb_path", "const"]],
+  caption = "Hierarchical fit of SFORB-SFO2 with constant variance")
+tex_listing(path_1[["sforb_path", "tc"]],
+  caption = "Hierarchical fit of SFORB-SFO2 with two-component error")
+tex_listing(path_1_refined,
+  caption = "Refined hierarchical fit of SFORB-SFO2 with two-component error")
+```
+
+## Session info
+
+```{r echo = FALSE, cache = FALSE}
+parallel::stopCluster(cl)
+sessionInfo()
+```
+
diff --git a/docs/dev/reference/example_analysis/header.tex b/docs/dev/reference/example_analysis/header.tex
new file mode 100644
index 00000000..a2b7ce83
--- /dev/null
+++ b/docs/dev/reference/example_analysis/header.tex
@@ -0,0 +1 @@
+\definecolor{shadecolor}{RGB}{248,248,248}
diff --git a/docs/dev/reference/example_analysis/skeleton.pdf b/docs/dev/reference/example_analysis/skeleton.pdf
new file mode 100644
index 00000000..53c5fb31
--- /dev/null
+++ b/docs/dev/reference/example_analysis/skeleton.pdf
diff --git a/docs/dev/reference/example_analysis/skeleton_files/figure-latex/unnamed-chunk-11-1.pdf b/docs/dev/reference/example_analysis/skeleton_files/figure-latex/unnamed-chunk-11-1.pdf
new file mode 100644
index 00000000..ab685d92
--- /dev/null
+++ b/docs/dev/reference/example_analysis/skeleton_files/figure-latex/unnamed-chunk-11-1.pdf
diff --git a/docs/dev/reference/example_analysis/skeleton_files/figure-latex/unnamed-chunk-16-1.pdf b/docs/dev/reference/example_analysis/skeleton_files/figure-latex/unnamed-chunk-16-1.pdf
new file mode 100644
index 00000000..5d88063b
--- /dev/null
+++ b/docs/dev/reference/example_analysis/skeleton_files/figure-latex/unnamed-chunk-16-1.pdf
diff --git a/docs/dev/reference/example_analysis/skeleton_files/figure-latex/unnamed-chunk-6-1.pdf b/docs/dev/reference/example_analysis/skeleton_files/figure-latex/unnamed-chunk-6-1.pdf
new file mode 100644
index 00000000..5e0d7b6f
--- /dev/null
+++ b/docs/dev/reference/example_analysis/skeleton_files/figure-latex/unnamed-chunk-6-1.pdf
diff --git a/docs/dev/reference/example_analysis/skeleton_files/figure-latex/unnamed-chunk-9-1.pdf b/docs/dev/reference/example_analysis/skeleton_files/figure-latex/unnamed-chunk-9-1.pdf
new file mode 100644
index 00000000..eecd06a8
--- /dev/null
+++ b/docs/dev/reference/example_analysis/skeleton_files/figure-latex/unnamed-chunk-9-1.pdf
diff --git a/docs/dev/reference/hierarchical_kinetics.html b/docs/dev/reference/hierarchical_kinetics.html
new file mode 100644
index 00000000..bedb8753
--- /dev/null
+++ b/docs/dev/reference/hierarchical_kinetics.html
@@ -0,0 +1,154 @@
+<!DOCTYPE html>
+<!-- Generated by pkgdown: do not edit by hand --><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Hierarchical kinetics template — hierarchical_kinetics • mkin</title><!-- jquery --><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script><!-- Bootstrap --><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/css/bootstrap.min.css" integrity="sha256-bZLfwXAP04zRMK2BjiO8iu9pf4FbLqX6zitd+tIvLhE=" crossorigin="anonymous"><script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/js/bootstrap.min.js" integrity="sha256-nuL8/2cJ5NDSSwnKD8VqreErSWHtnEP9E7AySL+1ev4=" crossorigin="anonymous"></script><!-- bootstrap-toc --><link rel="stylesheet" href="../bootstrap-toc.css"><script src="../bootstrap-toc.js"></script><!-- Font Awesome icons --><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css" integrity="sha256-mmgLkCYLUQbXn0B1SRqzHar6dCnv9oZFPEC1g1cwlkk=" crossorigin="anonymous"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/v4-shims.min.css" integrity="sha256-wZjR52fzng1pJHwx4aV2AO3yyTOXrcDW7jBpJtTwVxw=" crossorigin="anonymous"><!-- clipboard.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.6/clipboard.min.js" integrity="sha256-inc5kl9MA1hkeYUt+EC3BhlIgyp/2jDIyBLS6k3UxPI=" crossorigin="anonymous"></script><!-- headroom.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/headroom.min.js" integrity="sha256-AsUX4SJE1+yuDu5+mAVzJbuYNPHj/WroHuZ8Ir/CkE0=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/jQuery.headroom.min.js" integrity="sha256-ZX/yNShbjqsohH1k95liqY9Gd8uOiE1S4vZc+9KQ1K4=" crossorigin="anonymous"></script><!-- pkgdown --><link href="../pkgdown.css" rel="stylesheet"><script src="../pkgdown.js"></script><meta property="og:title" content="Hierarchical kinetics template — hierarchical_kinetics"><meta property="og:description" content="R markdown format for setting up hierarchical kinetics based on a template
+provided with the mkin package."><meta name="robots" content="noindex"><!-- mathjax --><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/config/TeX-AMS-MML_HTMLorMML.js" integrity="sha256-84DKXVJXs0/F8OTMzX4UR909+jtl4G7SPypPavF+GfA=" crossorigin="anonymous"></script><!--[if lt IE 9]>
+<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
+<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
+<![endif]--></head><body data-spy="scroll" data-target="#toc">
+    
+
+    <div class="container template-reference-topic">
+      <header><div class="navbar navbar-default navbar-fixed-top" role="navigation">
+  <div class="container">
+    <div class="navbar-header">
+      <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false">
+        <span class="sr-only">Toggle navigation</span>
+        <span class="icon-bar"></span>
+        <span class="icon-bar"></span>
+        <span class="icon-bar"></span>
+      </button>
+      <span class="navbar-brand">
+        <a class="navbar-link" href="../index.html">mkin</a>
+        <span class="version label label-info" data-toggle="tooltip" data-placement="bottom" title="In-development version">1.2.2</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>
+</li>
+<li class="dropdown">
+  <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
+    Articles
+     
+    <span class="caret"></span>
+  </a>
+  <ul class="dropdown-menu" role="menu"><li>
+      <a href="../articles/mkin.html">Introduction to mkin</a>
+    </li>
+    <li>
+      <a href="../articles/FOCUS_D.html">Example evaluation of FOCUS Example Dataset D</a>
+    </li>
+    <li>
+      <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>
+    </li>
+    <li>
+      <a href="../articles/web_only/multistart.html">Short demo of the multistart method</a>
+    </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/FOCUS_Z.html">Example evaluation of FOCUS Example Dataset Z</a>
+    </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>
+    <li>
+      <a href="../articles/web_only/benchmarks.html">Benchmark timings for mkin</a>
+    </li>
+    <li>
+      <a href="../articles/web_only/saem_benchmarks.html">Benchmark timings for saem.mmkin</a>
+    </li>
+  </ul></li>
+<li>
+  <a href="../news/index.html">News</a>
+</li>
+      </ul><ul class="nav navbar-nav navbar-right"><li>
+  <a href="https://github.com/jranke/mkin/" class="external-link">
+    <span class="fab fa-github fa-lg"></span>
+     
+  </a>
+</li>
+      </ul></div><!--/.nav-collapse -->
+  </div><!--/.container -->
+</div><!--/.navbar -->
+
+      
+
+      </header><div class="row">
+  <div class="col-md-9 contents">
+    <div class="page-header">
+    <h1>Hierarchical kinetics template</h1>
+    <small class="dont-index">Source: <a href="https://github.com/jranke/mkin/blob/HEAD/R/hierarchical_kinetics.R" class="external-link"><code>R/hierarchical_kinetics.R</code></a></small>
+    <div class="hidden name"><code>hierarchical_kinetics.Rd</code></div>
+    </div>
+
+    <div class="ref-description">
+    <p>R markdown format for setting up hierarchical kinetics based on a template
+provided with the mkin package.</p>
+    </div>
+
+    <div id="ref-usage">
+    <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">hierarchical_kinetics</span><span class="op">(</span><span class="va">...</span>, keep_tex <span class="op">=</span> <span class="cn">FALSE</span><span class="op">)</span></span></code></pre></div>
+    </div>
+
+    <div id="arguments">
+    <h2>Arguments</h2>
+    <dl><dt>...</dt>
+<dd><p>Arguments to <code><a href="https://pkgs.rstudio.com/rmarkdown/reference/pdf_document.html" class="external-link">rmarkdown::pdf_document</a></code></p></dd>
+
+
+<dt>keep_tex</dt>
+<dd><p>Keep the intermediate tex file used in the conversion to PDF</p></dd>
+
+</dl></div>
+    <div id="value">
+    <h2>Value</h2>
+    
+
+<p>R Markdown output format to pass to
+<code><a href="https://pkgs.rstudio.com/rmarkdown/reference/render.html" class="external-link">render</a></code></p>
+
+
+    </div>
+
+    <div id="ref-examples">
+    <h2>Examples</h2>
+    <div class="sourceCode"><pre class="sourceCode r"><code><span class="r-in"><span></span></span>
+<span class="r-in"><span><span class="co"># \dontrun{</span></span></span>
+<span class="r-in"><span><span class="kw"><a href="https://rdrr.io/r/base/library.html" class="external-link">library</a></span><span class="op">(</span><span class="va"><a href="https://github.com/rstudio/rmarkdown" class="external-link">rmarkdown</a></span><span class="op">)</span></span></span>
+<span class="r-in"><span><span class="fu"><a href="https://pkgs.rstudio.com/rmarkdown/reference/draft.html" class="external-link">draft</a></span><span class="op">(</span><span class="st">"example_analysis.rmd"</span>, template <span class="op">=</span> <span class="st">"hierarchical_kinetics"</span>, package <span class="op">=</span> <span class="st">"mkin"</span><span class="op">)</span></span></span>
+<span class="r-in"><span><span class="co"># }</span></span></span>
+<span class="r-in"><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>
+    </nav></div>
+</div>
+
+
+      <footer><div class="copyright">
+  <p></p><p>Developed by Johannes Ranke.</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.7.</p>
+</div>
+
+      </footer></div>
+
+  
+
+
+  
+
+  </body></html>
+
diff --git a/docs/dev/reference/index.html b/docs/dev/reference/index.html
index 794126cf..525551fd 100644
--- a/docs/dev/reference/index.html
+++ b/docs/dev/reference/index.html
@@ -195,6 +195,10 @@ of an mmkin object</p></td>
           <p class="section-desc"></p><p>Create and work with nonlinear hierarchical models</p>
         </th>
       </tr></tbody><tbody><tr><td>
+          <p><code><a href="hierarchical_kinetics.html">hierarchical_kinetics()</a></code> </p>
+        </td>
+        <td><p>Hierarchical kinetics template</p></td>
+      </tr><tr><td>
           <p><code><a href="read_spreadsheet.html">read_spreadsheet()</a></code> </p>
         </td>
         <td><p>Read datasets and relevant meta information from a spreadsheet file</p></td>
@@ -356,9 +360,9 @@ degradation models and one or more error models</p></td>
           <p class="section-desc"></p>
         </th>
       </tr></tbody><tbody><tr><td>
-          <p><code><a href="tex_listing.html">tex_listing()</a></code> </p>
+          <p><code><a href="summary_listing.html">summary_listing()</a></code> <code><a href="summary_listing.html">tex_listing()</a></code> <code><a href="summary_listing.html">html_listing()</a></code> </p>
         </td>
-        <td><p>Wrap the output of a summary function in tex listing environment</p></td>
+        <td><p>Display the output of a summary function according to the output format</p></td>
       </tr><tr><td>
           <p><code><a href="f_time_norm_focus.html">f_time_norm_focus()</a></code> </p>
         </td>
@@ -493,7 +497,7 @@ kinetic models fitted with mkinfit</p></td>
 </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>
diff --git a/docs/dev/reference/mkinmod.html b/docs/dev/reference/mkinmod.html
index 251215a7..145dee83 100644
--- a/docs/dev/reference/mkinmod.html
+++ b/docs/dev/reference/mkinmod.html
@@ -132,7 +132,7 @@ the source compartment.
 Additionally, <code>mkinsub()</code> has an argument <code>to</code>, specifying names of
 variables to which a transfer is to be assumed in the model.
 If the argument <code>use_of_ff</code> is set to "min"
-(default) and the model for the compartment is "SFO" or "SFORB", an
+and the model for the compartment is "SFO" or "SFORB", an
 additional <code>mkinsub()</code> argument can be <code>sink = FALSE</code>, effectively
 fixing the flux to sink to zero.
 In print.mkinmod, this argument is currently not used.</p></dd>
@@ -247,7 +247,7 @@ in the FOCUS and NAFTA guidance documents are used.</p>
 <p>For kinetic models with more than one observed variable, a symbolic solution
 of the system of differential equations is included in the resulting
 mkinmod object in some cases, speeding up the solution.</p>
-<p>If a C compiler is found by <code><a href="https://rdrr.io/pkg/pkgbuild/man/has_compiler.html" class="external-link">pkgbuild::has_compiler()</a></code> and there
+<p>If a C compiler is found by <code><a href="https://r-lib.github.io/pkgbuild/reference/has_compiler.html" class="external-link">pkgbuild::has_compiler()</a></code> and there
 is more than one observed variable in the specification, C code is generated
 for evaluating the differential equations, compiled using
 <code><a href="https://rdrr.io/pkg/inline/man/cfunction.html" class="external-link">inline::cfunction()</a></code> and added to the resulting mkinmod object.</p>
@@ -310,7 +310,7 @@ Evaluating and Calculating Degradation Kinetics in Environmental Media</p>
 <span class="r-in"><span>   parent <span class="op">=</span> <span class="fu">mkinsub</span><span class="op">(</span><span class="st">"SFO"</span>, <span class="st">"m1"</span>, full_name <span class="op">=</span> <span class="st">"Test compound"</span><span class="op">)</span>,</span></span>
 <span class="r-in"><span>   m1 <span class="op">=</span> <span class="fu">mkinsub</span><span class="op">(</span><span class="st">"SFO"</span>, full_name <span class="op">=</span> <span class="st">"Metabolite M1"</span><span class="op">)</span>,</span></span>
 <span class="r-in"><span>   name <span class="op">=</span> <span class="st">"SFO_SFO"</span>, dll_dir <span class="op">=</span> <span class="va">DLL_dir</span>, unload <span class="op">=</span> <span class="cn">TRUE</span>, overwrite <span class="op">=</span> <span class="cn">TRUE</span><span class="op">)</span></span></span>
-<span class="r-msg co"><span class="r-pr">#&gt;</span> Copied DLL from /tmp/RtmpbZbZ8Y/file8c6a9f402f42.so to /home/jranke/.local/share/mkin/SFO_SFO.so</span>
+<span class="r-msg co"><span class="r-pr">#&gt;</span> Copied DLL from /tmp/RtmpelWAOB/fileb43c31a25a86.so to /home/jranke/.local/share/mkin/SFO_SFO.so</span>
 <span class="r-in"><span><span class="co"># Now we can save the model and restore it in a new session</span></span></span>
 <span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/readRDS.html" class="external-link">saveRDS</a></span><span class="op">(</span><span class="va">SFO_SFO.2</span>, file <span class="op">=</span> <span class="st">"~/SFO_SFO.rds"</span><span class="op">)</span></span></span>
 <span class="r-in"><span><span class="co"># Terminate the R session here if you would like to check, and then do</span></span></span>
@@ -363,7 +363,7 @@ Evaluating and Calculating Degradation Kinetics in Environmental Media</p>
 <span class="r-out co"><span class="r-pr">#&gt;</span>     })</span>
 <span class="r-out co"><span class="r-pr">#&gt;</span>     return(predicted)</span>
 <span class="r-out co"><span class="r-pr">#&gt;</span> }</span>
-<span class="r-out co"><span class="r-pr">#&gt;</span> &lt;environment: 0x55556029f678&gt;</span>
+<span class="r-out co"><span class="r-pr">#&gt;</span> &lt;environment: 0x55555f013820&gt;</span>
 <span class="r-in"><span></span></span>
 <span class="r-in"><span><span class="co"># If we have several parallel metabolites</span></span></span>
 <span class="r-in"><span><span class="co"># (compare tests/testthat/test_synthetic_data_for_UBA_2014.R)</span></span></span>
@@ -392,7 +392,7 @@ Evaluating and Calculating Degradation Kinetics in Environmental Media</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>
diff --git a/docs/dev/reference/summary_listing.html b/docs/dev/reference/summary_listing.html
new file mode 100644
index 00000000..876412cc
--- /dev/null
+++ b/docs/dev/reference/summary_listing.html
@@ -0,0 +1,147 @@
+<!DOCTYPE html>
+<!-- Generated by pkgdown: do not edit by hand --><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Display the output of a summary function according to the output format — summary_listing • mkin</title><!-- jquery --><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script><!-- Bootstrap --><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/css/bootstrap.min.css" integrity="sha256-bZLfwXAP04zRMK2BjiO8iu9pf4FbLqX6zitd+tIvLhE=" crossorigin="anonymous"><script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/js/bootstrap.min.js" integrity="sha256-nuL8/2cJ5NDSSwnKD8VqreErSWHtnEP9E7AySL+1ev4=" crossorigin="anonymous"></script><!-- bootstrap-toc --><link rel="stylesheet" href="../bootstrap-toc.css"><script src="../bootstrap-toc.js"></script><!-- Font Awesome icons --><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css" integrity="sha256-mmgLkCYLUQbXn0B1SRqzHar6dCnv9oZFPEC1g1cwlkk=" crossorigin="anonymous"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/v4-shims.min.css" integrity="sha256-wZjR52fzng1pJHwx4aV2AO3yyTOXrcDW7jBpJtTwVxw=" crossorigin="anonymous"><!-- clipboard.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.6/clipboard.min.js" integrity="sha256-inc5kl9MA1hkeYUt+EC3BhlIgyp/2jDIyBLS6k3UxPI=" crossorigin="anonymous"></script><!-- headroom.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/headroom.min.js" integrity="sha256-AsUX4SJE1+yuDu5+mAVzJbuYNPHj/WroHuZ8Ir/CkE0=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/jQuery.headroom.min.js" integrity="sha256-ZX/yNShbjqsohH1k95liqY9Gd8uOiE1S4vZc+9KQ1K4=" crossorigin="anonymous"></script><!-- pkgdown --><link href="../pkgdown.css" rel="stylesheet"><script src="../pkgdown.js"></script><meta property="og:title" content="Display the output of a summary function according to the output format — summary_listing"><meta property="og:description" content='This function is intended for use in a R markdown code chunk with the chunk
+option results = "asis".'><meta name="robots" content="noindex"><!-- mathjax --><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/config/TeX-AMS-MML_HTMLorMML.js" integrity="sha256-84DKXVJXs0/F8OTMzX4UR909+jtl4G7SPypPavF+GfA=" crossorigin="anonymous"></script><!--[if lt IE 9]>
+<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
+<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
+<![endif]--></head><body data-spy="scroll" data-target="#toc">
+    
+
+    <div class="container template-reference-topic">
+      <header><div class="navbar navbar-default navbar-fixed-top" role="navigation">
+  <div class="container">
+    <div class="navbar-header">
+      <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false">
+        <span class="sr-only">Toggle navigation</span>
+        <span class="icon-bar"></span>
+        <span class="icon-bar"></span>
+        <span class="icon-bar"></span>
+      </button>
+      <span class="navbar-brand">
+        <a class="navbar-link" href="../index.html">mkin</a>
+        <span class="version label label-info" data-toggle="tooltip" data-placement="bottom" title="In-development version">1.2.2</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>
+</li>
+<li class="dropdown">
+  <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
+    Articles
+     
+    <span class="caret"></span>
+  </a>
+  <ul class="dropdown-menu" role="menu"><li>
+      <a href="../articles/mkin.html">Introduction to mkin</a>
+    </li>
+    <li>
+      <a href="../articles/FOCUS_D.html">Example evaluation of FOCUS Example Dataset D</a>
+    </li>
+    <li>
+      <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>
+    </li>
+    <li>
+      <a href="../articles/web_only/multistart.html">Short demo of the multistart method</a>
+    </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/FOCUS_Z.html">Example evaluation of FOCUS Example Dataset Z</a>
+    </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>
+    <li>
+      <a href="../articles/web_only/benchmarks.html">Benchmark timings for mkin</a>
+    </li>
+    <li>
+      <a href="../articles/web_only/saem_benchmarks.html">Benchmark timings for saem.mmkin</a>
+    </li>
+  </ul></li>
+<li>
+  <a href="../news/index.html">News</a>
+</li>
+      </ul><ul class="nav navbar-nav navbar-right"><li>
+  <a href="https://github.com/jranke/mkin/" class="external-link">
+    <span class="fab fa-github fa-lg"></span>
+     
+  </a>
+</li>
+      </ul></div><!--/.nav-collapse -->
+  </div><!--/.container -->
+</div><!--/.navbar -->
+
+      
+
+      </header><div class="row">
+  <div class="col-md-9 contents">
+    <div class="page-header">
+    <h1>Display the output of a summary function according to the output format</h1>
+    <small class="dont-index">Source: <a href="https://github.com/jranke/mkin/blob/HEAD/R/summary_listing.R" class="external-link"><code>R/summary_listing.R</code></a></small>
+    <div class="hidden name"><code>summary_listing.Rd</code></div>
+    </div>
+
+    <div class="ref-description">
+    <p>This function is intended for use in a R markdown code chunk with the chunk
+option <code>results = "asis"</code>.</p>
+    </div>
+
+    <div id="ref-usage">
+    <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">summary_listing</span><span class="op">(</span><span class="va">object</span>, caption <span class="op">=</span> <span class="cn">NULL</span>, label <span class="op">=</span> <span class="cn">NULL</span>, clearpage <span class="op">=</span> <span class="cn">TRUE</span><span class="op">)</span></span>
+<span></span>
+<span><span class="fu">tex_listing</span><span class="op">(</span><span class="va">object</span>, caption <span class="op">=</span> <span class="cn">NULL</span>, label <span class="op">=</span> <span class="cn">NULL</span>, clearpage <span class="op">=</span> <span class="cn">TRUE</span><span class="op">)</span></span>
+<span></span>
+<span><span class="fu">html_listing</span><span class="op">(</span><span class="va">object</span>, caption <span class="op">=</span> <span class="cn">NULL</span><span class="op">)</span></span></code></pre></div>
+    </div>
+
+    <div id="arguments">
+    <h2>Arguments</h2>
+    <dl><dt>object</dt>
+<dd><p>The object for which the summary is to be listed</p></dd>
+
+
+<dt>caption</dt>
+<dd><p>An optional caption</p></dd>
+
+
+<dt>label</dt>
+<dd><p>An optional label, ignored in html output</p></dd>
+
+
+<dt>clearpage</dt>
+<dd><p>Should a new page be started after the listing? Ignored in html output</p></dd>
+
+</dl></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>
+    </nav></div>
+</div>
+
+
+      <footer><div class="copyright">
+  <p></p><p>Developed by Johannes Ranke.</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.7.</p>
+</div>
+
+      </footer></div>
+
+  
+
+
+  
+
+  </body></html>
+