Rename template folder, create format

Instead of rmarkdown::pdf_document, mkin::hierarchical_kinetics is used
as a document format in the template. In this way, the template file can
be freed from some R code and yaml options that the average user does
not have to be aware of.

12 files changed, 110 insertions, 48 deletions

diff --git a/.Rbuildignore b/.Rbuildignore
index 0dcec29a..1eb33577 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -9,9 +9,9 @@
 ^test.R$
 ^mkin_.*\.tar\.gz
 ^mkin.tar$
-^inst/rmarkdown/templates/hier/skeleton/skeleton.pdf$
-^inst/rmarkdown/templates/hier/skeleton/skeleton_cache
-^inst/rmarkdown/templates/hier/skeleton/skeleton_files
+^inst/rmarkdown/templates/hierarchical_kinetics/skeleton/skeleton.pdf$
+^inst/rmarkdown/templates/hierarchical_kinetics/skeleton/skeleton_cache
+^inst/rmarkdown/templates/hierarchical_kinetics/skeleton/skeleton_files
 ^vignettes/.build.timestamp$
 ^vignettes/.*_cache$
 ^vignettes/.*cache$
diff --git a/.gitignore b/.gitignore
index 4f479259..9808896d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,8 +1,8 @@
 docs/articles/*_cache/
 install.log
-inst/rmarkdown/templates/hier/skeleton/skeleton_cache
-inst/rmarkdown/templates/hier/skeleton/skeleton_files
-inst/rmarkdown/templates/hier/skeleton/skeleton.pdf
+inst/rmarkdown/templates/hierarchical_kinetics/skeleton/skeleton_cache
+inst/rmarkdown/templates/hierarchical_kinetics/skeleton/skeleton_files
+inst/rmarkdown/templates/hierarchical_kinetics/skeleton/skeleton.pdf
 mkin*.tar.gz
 mkin.tar
 mkin.Rcheck
diff --git a/GNUmakefile b/GNUmakefile
index 4680514c..4a33c538 100644
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -24,8 +24,8 @@ pkgfiles = \
 	DESCRIPTION \
 	inst/WORDLIST \
 	inst/dataset_generation/* \
-	inst/rmarkdown/templates/hier/template.yaml \
-	inst/rmarkdown/templates/hier/skeleton/skeleton.Rmd \
+	inst/rmarkdown/templates/hierarchical_kinetics/template.yaml \
+	inst/rmarkdown/templates/hierarchical_kinetics/skeleton/skeleton.Rmd \
 	inst/testdata/* \
 	man/* \
 	NAMESPACE \
diff --git a/NAMESPACE b/NAMESPACE
index 107ffc54..84d6b713 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -96,6 +96,7 @@ export(create_deg_func)
 export(endpoints)
 export(f_time_norm_focus)
 export(get_deg_func)
+export(hierarchical_kinetics)
 export(illparms)
 export(ilr)
 export(intervals)
@@ -187,6 +188,7 @@ importFrom(stats,qf)
 importFrom(stats,qlogis)
 importFrom(stats,qnorm)
 importFrom(stats,qt)
+importFrom(stats,quantile)
 importFrom(stats,residuals)
 importFrom(stats,rnorm)
 importFrom(stats,shapiro.test)
diff --git a/NEWS.md b/NEWS.md
index 7e65204f..2c09df35 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,5 +1,9 @@
 # mkin 1.2.2
 
+- 'inst/rmarkdown/templates/hier': R markdown template to facilitate the application of hierarchical kinetic models.
+
+- 'inst/testdata/lambda-cyhalothrin_soil_efsa_2014.xlsx': Example spreadsheet for use with 'read_spreadsheet()'.
+
 - 'R/mhmkin.R': Allow an 'illparms.mhmkin' object or a list with suitable dimensions as value of the argument 'no_random_effects', making it possible to exclude random effects that were ill-defined in simpler variants of the set of degradation models. Remove the possibility to exclude random effects based on separate fits, as it did not work well.
 
 - 'R/summary.saem.mmkin.R': List all initial parameter values in the summary, including random effects and error model parameters. Avoid redundant warnings that occurred in the calculation of correlations of the fixed effects in the case that the Fisher information matrix could not be inverted. List correlations of random effects if specified by the user in the covariance model.
diff --git a/R/hierarchical_kinetics.R b/R/hierarchical_kinetics.R
new file mode 100644
index 00000000..f7ffb333
--- /dev/null
+++ b/R/hierarchical_kinetics.R
@@ -0,0 +1,39 @@
+#' Hierarchical kinetics template
+#'
+#' R markdown format for setting up hierarchical kinetics based on a template
+#' provided with the mkin package.
+#'
+#' @inheritParams rmarkdown::pdf_document
+#' @param ... Arguments to \code{rmarkdown::pdf_document}
+#'
+#' @return R Markdown output format to pass to
+#'   \code{\link[rmarkdown:render]{render}}
+#'
+#' @examples
+#'
+#' \dontrun{
+#' library(rmarkdown)
+#' draft("New analysis.rmd", template = "hierarchical_kinetics", package = "mkin")
+#' }
+#'
+#' @export
+hierarchical_kinetics <- function(..., keep_tex = FALSE) {
+
+  if (getRversion() < "4.1.0")
+    stop("You need R with version > 4.1.0 to compile this document")
+
+  if (!requireNamespace("knitr")) stop("Please install the knitr package to use this template")
+  if (!requireNamespace("rmarkdown")) stop("Please install the rmarkdown package to use this template")
+  knitr::opts_chunk$set(echo = FALSE, cache = TRUE, comment = "", tidy = FALSE)
+  knitr::opts_chunk$set(fig.align = "center", fig.pos = "H")
+  options(knitr.kable.NA = "")
+
+  fmt <- rmarkdown::pdf_document(...,
+    keep_tex = keep_tex,
+    toc = TRUE,
+    includes = rmarkdown::includes(in_header = "header.tex"),
+    extra_dependencies = c("float", "listing", "framed")
+  )
+
+  return(fmt)
+}
diff --git a/R/parplot.R b/R/parplot.R
index e9c18947..3da4b51a 100644
--- a/R/parplot.R
+++ b/R/parplot.R
@@ -23,7 +23,7 @@
 #' of the in vitro erythropoiesis. BMC Bioinformatics. 2021 Oct 4;22(1):478.
 #' doi: 10.1186/s12859-021-04373-4.
 #' @seealso [multistart]
-#' @importFrom stats median
+#' @importFrom stats median quantile
 #' @export
 parplot <- function(object, ...) {
   UseMethod("parplot")
diff --git a/inst/rmarkdown/templates/hierarchical_kinetics/skeleton/header.tex b/inst/rmarkdown/templates/hierarchical_kinetics/skeleton/header.tex
new file mode 100644
index 00000000..a2b7ce83
--- /dev/null
+++ b/inst/rmarkdown/templates/hierarchical_kinetics/skeleton/header.tex
@@ -0,0 +1 @@
+\definecolor{shadecolor}{RGB}{248,248,248}
diff --git a/inst/rmarkdown/templates/hier/skeleton/skeleton.Rmd b/inst/rmarkdown/templates/hierarchical_kinetics/skeleton/skeleton.Rmd
index df6fa2f9..74fae164 100644
--- a/inst/rmarkdown/templates/hier/skeleton/skeleton.Rmd
+++ b/inst/rmarkdown/templates/hierarchical_kinetics/skeleton/skeleton.Rmd
@@ -1,42 +1,17 @@
 ---
 title: "Hierarchical kinetic modelling of degradation data"
 author:
-date: Last change on DD MMM YYYY, last compiled on `r format(Sys.time(),
-  "%e %B %Y")`
-output:
-  pdf_document:
-    extra_dependencies: ["float", "listing"]
-toc: yes
+date:
+output: mkin::hierarchical_kinetics
 geometry: margin=2cm
 ---
 
-
-```{r setup, echo = FALSE, cache = FALSE}
-errmods <- c(const = "constant variance", tc = "two-component error")
-
-knitr::opts_chunk$set(
-  comment = "", tidy = FALSE, cache = TRUE, fig.pos = "H", fig.align = "center"
-)
-options(knitr.kable.NA = "")
-
-# Version requirements
-if (getRversion() < "4.1.0")
-  stop("You need R with version > 4.1.0 to compile this document")
-if ((saemix_version <- packageVersion("saemix")) < "3.1") {
-  warning("Your saemix version is ", saemix_version,
-    ", you should preferably use 3.2 to compile this document")
-}
-if ((mkin_version <- packageVersion("mkin")) < "1.2.2") {
-  stop("Your mkin version is ", mkin_version,
-    ", you need at least 1.2.2 to compile this document")
-}
-```
-
-```{r packages, cache = FALSE, message = FALSE, warning = FALSE, echo = FALSE}
+```{r packages, cache = FALSE, message = FALSE}
 library(mkin)
+library(knitr)
 library(saemix)
 library(parallel)
-library(knitr)
+library(readxl)
 ```
 
 ```{r n_cores, cache = FALSE, echo = FALSE}
@@ -91,6 +66,7 @@ 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",
@@ -124,7 +100,7 @@ status(parent_mhmkin_refined) |> kable()
 
 The most suitable model is selected based on the AIC.
 
-```{r dependson = "parent-mhmkin"}
+```{r, 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]]
@@ -157,7 +133,7 @@ Detailed listings of the parent fits are shown in the Appendix.
 
 ### Parent fits
 
-```{r listings-parent, results = "asis", echo = FALSE}
+```{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])
@@ -168,7 +144,7 @@ for (deg_mod in parent_deg_mods) {
 
 ### Refined parent fits
 
-```{r listings-pathway, results = "asis", echo = FALSE}
+```{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])
@@ -179,7 +155,7 @@ for (deg_mod in parent_deg_mods) {
 
 ## Session info
 
-```{r, echo = FALSE}
+```{r, echo = FALSE, cache = FALSE}
 parallel::stopCluster(cl)
 sessionInfo()
 ```
diff --git a/inst/rmarkdown/templates/hier/template.yaml b/inst/rmarkdown/templates/hierarchical_kinetics/template.yaml
index d8ab6a4d..d8ab6a4d 100644
--- a/inst/rmarkdown/templates/hier/template.yaml
+++ b/inst/rmarkdown/templates/hierarchical_kinetics/template.yaml
diff --git a/log/check.log b/log/check.log
index 42365918..aec61e33 100644
--- a/log/check.log
+++ b/log/check.log
@@ -1,5 +1,5 @@
 * using log directory ‘/home/jranke/git/mkin/mkin.Rcheck’
-* using R version 4.2.2 (2022-10-31)
+* using R version 4.2.2 Patched (2022-11-10 r83330)
 * using platform: x86_64-pc-linux-gnu (64-bit)
 * using session charset: UTF-8
 * using options ‘--no-tests --as-cran’
@@ -18,7 +18,7 @@ Maintainer: ‘Johannes Ranke <johannes.ranke@jrwb.de>’
 * checking for portable file names ... OK
 * checking for sufficient/correct file permissions ... OK
 * checking serialization versions ... OK
-* checking whether package ‘mkin’ can be installed ... [11s/11s] OK
+* checking whether package ‘mkin’ can be installed ... OK
 * checking installed package size ... OK
 * checking package directory ... OK
 * checking for future file timestamps ... OK
@@ -41,7 +41,14 @@ Maintainer: ‘Johannes Ranke <johannes.ranke@jrwb.de>’
 * checking S3 generic/method consistency ... OK
 * checking replacement functions ... OK
 * checking foreign function calls ... OK
-* checking R code for possible problems ... [19s/19s] OK
+* checking R code for possible problems ... NOTE
+parplot.multistart.saem.mmkin: no visible global function definition
+  for ‘quantile’
+Undefined global functions or variables:
+  quantile
+Consider adding
+  importFrom("stats", "quantile")
+to your NAMESPACE file.
 * checking Rd files ... OK
 * checking Rd metadata ... OK
 * checking Rd line widths ... OK
@@ -57,7 +64,7 @@ Maintainer: ‘Johannes Ranke <johannes.ranke@jrwb.de>’
 * checking data for ASCII and uncompressed saves ... OK
 * checking installed files from ‘inst/doc’ ... OK
 * checking files in ‘vignettes’ ... OK
-* checking examples ... [24s/24s] OK
+* checking examples ... [11s/11s] OK
 * checking for unstated dependencies in ‘tests’ ... OK
 * checking tests ... SKIPPED
 * checking for unstated dependencies in vignettes ... OK
@@ -69,5 +76,9 @@ Maintainer: ‘Johannes Ranke <johannes.ranke@jrwb.de>’
 * checking for detritus in the temp directory ... OK
 * DONE
 
-Status: OK
+Status: 1 NOTE
+See
+  ‘/home/jranke/git/mkin/mkin.Rcheck/00check.log’
+for details.
+
 
diff --git a/man/hierarchical_kinetics.Rd b/man/hierarchical_kinetics.Rd
new file mode 100644
index 00000000..4bb82a4c
--- /dev/null
+++ b/man/hierarchical_kinetics.Rd
@@ -0,0 +1,29 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/hierarchical_kinetics.R
+\name{hierarchical_kinetics}
+\alias{hierarchical_kinetics}
+\title{Hierarchical kinetics template}
+\usage{
+hierarchical_kinetics(..., keep_tex = FALSE)
+}
+\arguments{
+\item{...}{Arguments to \code{rmarkdown::pdf_document}}
+
+\item{keep_tex}{Keep the intermediate tex file used in the conversion to PDF}
+}
+\value{
+R Markdown output format to pass to
+\code{\link[rmarkdown:render]{render}}
+}
+\description{
+R markdown format for setting up hierarchical kinetics based on a template
+provided with the mkin package.
+}
+\examples{
+
+\dontrun{
+library(rmarkdown)
+draft("New analysis.rmd", template = "hierarchical_kinetics", package = "mkin")
+}
+
+}