Improve mkinmod docs

4 files changed, 135 insertions, 85 deletions

diff --git a/R/mkinmod.R b/R/mkinmod.R
index e58d1e22..a410c02d 100644
--- a/R/mkinmod.R
+++ b/R/mkinmod.R
@@ -1,26 +1,34 @@
 #' Function to set up a kinetic model with one or more state variables
 #'
-#' The function usually takes several expressions, each assigning a compound
-#' name to a list, specifying the kinetic model type and reaction or transfer
-#' to other observed compartments. Instead of specifying several expressions, a
-#' list of lists can be given in the speclist argument.
+#' This function is usually called using a call to [mkinsub()] for each observed
+#' variable, specifying the corresponding submodel as well as outgoing pathways
+#' (see examples).
 #'
 #' For the definition of model types and their parameters, the equations given
 #' in the FOCUS and NAFTA guidance documents are used.
 #'
-#' @param ...  For each observed variable, a list has to be specified as an
-#'   argument, containing at least a component \code{type}, specifying the type
-#'   of kinetics to use for the variable. Currently, single first order
-#'   kinetics "SFO", indeterminate order rate equation kinetics "IORE", or
-#'   single first order with reversible binding "SFORB" are implemented for all
-#'   variables, while "FOMC", "DFOP" and "HS" can additionally be chosen for
-#'   the first variable which is assumed to be the source compartment.
-#'   Additionally, each component of the list can include a character vector
-#'   \code{to}, specifying names of variables to which a transfer is to be
-#'   assumed in the model.  If the argument \code{use_of_ff} is set to "min"
+#' 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.
+#'
+#' If a C compiler is found by [pkgbuild::has_compiler()] and there
+#' is more than one observed variable in the specification, C code is generated
+#' for evaluating the differential equations, compiled using
+#' [inline::cfunction()] and added to the resulting mkinmod object.
+#'
+#' @param ...  For each observed variable, a list as obtained by [mkinsub()]
+#'   has to be specified as an argument (see examples).  Currently, single
+#'   first order kinetics "SFO", indeterminate order rate equation kinetics
+#'   "IORE", or single first order with reversible binding "SFORB" are
+#'   implemented for all variables, while "FOMC", "DFOP", "HS" and "logistic"
+#'   can additionally be chosen for the first variable which is assumed to be
+#'   the source compartment.
+#'   Additionally, [mkinsub()] has an argument \code{to}, specifying names of
+#'   variables to which a transfer is to be assumed in the model.
+#'   If the argument \code{use_of_ff} is set to "min"
 #'   (default) and the model for the compartment is "SFO" or "SFORB", an
-#'   additional component of the list can be "sink=FALSE" effectively fixing
-#'   the flux to sink to zero.
+#'   additional [mkinsub()] argument can be \code{sink = FALSE}, effectively
+#'   fixing the flux to sink to zero.
 #' @param use_of_ff Specification of the use of formation fractions in the
 #'   model equations and, if applicable, the coefficient matrix. If "min", a
 #'   minimum use of formation fractions is made in order to avoid fitting the
@@ -30,12 +38,12 @@
 #'   submodel types and pathways can be given as a single list using this
 #'   argument. Default is NULL.
 #' @param quiet Should messages be suppressed?
-#' @param verbose If \code{TRUE}, passed to \code{\link{cfunction}} if
+#' @param verbose If \code{TRUE}, passed to [inline::cfunction()] if
 #'   applicable to give detailed information about the C function being built.
 #' @importFrom methods signature
 #' @importFrom pkgbuild has_compiler
 #' @importFrom inline cfunction
-#' @return A list of class \code{mkinmod} for use with \code{\link{mkinfit}},
+#' @return A list of class \code{mkinmod} for use with [mkinfit()],
 #'   containing, among others,
 #'   \item{diffs}{
 #'     A vector of string representations of differential equations, one for
@@ -61,8 +69,8 @@
 #'     returned by cfunction.
 #'   }
 #' @note The IORE submodel is not well tested for metabolites. When using this
-#'   model for metabolites, you may want to read the second note in the help
-#'   page to \code{\link{mkinfit}}.
+#'   model for metabolites, you may want to read the note in the help
+#'   page to [mkinfit].
 #' @author Johannes Ranke
 #' @references FOCUS (2006) \dQuote{Guidance Document on Estimating Persistence
 #'   and Degradation Kinetics from Environmental Fate Studies on Pesticides in
@@ -93,16 +101,21 @@
 #'   parent = mkinsub("SFO", "m1"),
 #'   m1 = mkinsub("SFO"), verbose = TRUE)
 #'
+#' # The symbolic solution which is available in this case is not
+#' # made for human reading but for speed of computation
+#' SFO_SFO$deg_func
+#'
 #' # If we have several parallel metabolites
 #' # (compare tests/testthat/test_synthetic_data_for_UBA_2014.R)
-#' m_synth_DFOP_par <- mkinmod(parent = mkinsub("DFOP", c("M1", "M2")),
-#'                            M1 = mkinsub("SFO"),
-#'                            M2 = mkinsub("SFO"),
-#'                            use_of_ff = "max", quiet = TRUE)
+#' m_synth_DFOP_par <- mkinmod(
+#'  parent = mkinsub("DFOP", c("M1", "M2")),
+#'  M1 = mkinsub("SFO"),
+#'  M2 = mkinsub("SFO"),
+#'  use_of_ff = "max", quiet = TRUE)
 #'
 #' fit_DFOP_par_c <- mkinfit(m_synth_DFOP_par,
-#'                           synthetic_data_for_UBA_2014[[12]]$data,
-#'                           quiet = TRUE)
+#'   synthetic_data_for_UBA_2014[[12]]$data,
+#'   quiet = TRUE)
 #' }
 #'
 #' @export mkinmod
diff --git a/docs/dev/pkgdown.yml b/docs/dev/pkgdown.yml
index 31ffe2ad..a7e9e750 100644
--- a/docs/dev/pkgdown.yml
+++ b/docs/dev/pkgdown.yml
@@ -10,7 +10,7 @@ articles:
   NAFTA_examples: web_only/NAFTA_examples.html
   benchmarks: web_only/benchmarks.html
   compiled_models: web_only/compiled_models.html
-last_built: 2020-05-27T05:43Z
+last_built: 2020-05-27T06:53Z
 urls:
   reference: https://pkgdown.jrwb.de/mkin/reference
   article: https://pkgdown.jrwb.de/mkin/articles
diff --git a/docs/dev/reference/mkinmod.html b/docs/dev/reference/mkinmod.html
index 80a72b2b..14b9eb1a 100644
--- a/docs/dev/reference/mkinmod.html
+++ b/docs/dev/reference/mkinmod.html
@@ -40,10 +40,9 @@
 
 
 <meta property="og:title" content="Function to set up a kinetic model with one or more state variables — mkinmod" />
-<meta property="og:description" content="The function usually takes several expressions, each assigning a compound
-name to a list, specifying the kinetic model type and reaction or transfer
-to other observed compartments. Instead of specifying several expressions, a
-list of lists can be given in the speclist argument." />
+<meta property="og:description" content="This function is usually called using a call to mkinsub() for each observed
+variable, specifying the corresponding submodel as well as outgoing pathways
+(see examples)." />
 
 
 <meta name="robots" content="noindex">
@@ -75,7 +74,7 @@ list of lists can be given in the speclist argument." />
       </button>
       <span class="navbar-brand">
         <a class="navbar-link" href="../index.html">mkin</a>
-        <span class="version label label-danger" data-toggle="tooltip" data-placement="bottom" title="In-development version">0.9.50.3</span>
+        <span class="version label label-info" data-toggle="tooltip" data-placement="bottom" title="In-development version">0.9.50.3</span>
       </span>
     </div>
 
@@ -147,10 +146,9 @@ list of lists can be given in the speclist argument." />
     </div>
 
     <div class="ref-description">
-    <p>The function usually takes several expressions, each assigning a compound
-name to a list, specifying the kinetic model type and reaction or transfer
-to other observed compartments. Instead of specifying several expressions, a
-list of lists can be given in the speclist argument.</p>
+    <p>This function is usually called using a call to <code><a href='mkinsub.html'>mkinsub()</a></code> for each observed
+variable, specifying the corresponding submodel as well as outgoing pathways
+(see examples).</p>
     </div>
 
     <pre class="usage"><span class='fu'>mkinmod</span>(
@@ -166,19 +164,19 @@ list of lists can be given in the speclist argument.</p>
     <colgroup><col class="name" /><col class="desc" /></colgroup>
     <tr>
       <th>...</th>
-      <td><p>For each observed variable, a list has to be specified as an
-argument, containing at least a component <code>type</code>, specifying the type
-of kinetics to use for the variable. Currently, single first order
-kinetics "SFO", indeterminate order rate equation kinetics "IORE", or
-single first order with reversible binding "SFORB" are implemented for all
-variables, while "FOMC", "DFOP" and "HS" can additionally be chosen for
-the first variable which is assumed to be the source compartment.
-Additionally, each component of the list can include a character vector
-<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"
+      <td><p>For each observed variable, a list as obtained by <code><a href='mkinsub.html'>mkinsub()</a></code>
+has to be specified as an argument (see examples).  Currently, single
+first order kinetics "SFO", indeterminate order rate equation kinetics
+"IORE", or single first order with reversible binding "SFORB" are
+implemented for all variables, while "FOMC", "DFOP", "HS" and "logistic"
+can additionally be chosen for the first variable which is assumed to be
+the source compartment.
+Additionally, <code><a href='mkinsub.html'>mkinsub()</a></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
-additional component of the list can be "sink=FALSE" effectively fixing
-the flux to sink to zero.</p></td>
+additional <code><a href='mkinsub.html'>mkinsub()</a></code> argument can be <code>sink = FALSE</code>, effectively
+fixing the flux to sink to zero.</p></td>
     </tr>
     <tr>
       <th>use_of_ff</th>
@@ -200,14 +198,14 @@ argument. Default is NULL.</p></td>
     </tr>
     <tr>
       <th>verbose</th>
-      <td><p>If <code>TRUE</code>, passed to <code>cfunction</code> if
+      <td><p>If <code>TRUE</code>, passed to <code><a href='https://rdrr.io/pkg/inline/man/cfunction.html'>inline::cfunction()</a></code> if
 applicable to give detailed information about the C function being built.</p></td>
     </tr>
     </table>
 
     <h2 class="hasAnchor" id="value"><a class="anchor" href="#value"></a>Value</h2>
 
-    <p>A list of class <code>mkinmod</code> for use with <code><a href='mkinfit.html'>mkinfit</a></code>,
+    <p>A list of class <code>mkinmod</code> for use with <code><a href='mkinfit.html'>mkinfit()</a></code>,
 containing, among others,</p>
 <dt>diffs</dt><dd><p>A vector of string representations of differential equations, one for
 each modelling variable.</p></dd>
@@ -225,11 +223,18 @@ returned by cfunction.</p></dd>
 
     <p>For the definition of model types and their parameters, the equations given
 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'>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'>inline::cfunction()</a></code> and added to the resulting mkinmod object.</p>
     <h2 class="hasAnchor" id="note"><a class="anchor" href="#note"></a>Note</h2>
 
     <p>The IORE submodel is not well tested for metabolites. When using this
-model for metabolites, you may want to read the second note in the help
-page to <code><a href='mkinfit.html'>mkinfit</a></code>.</p>
+model for metabolites, you may want to read the note in the help
+page to <a href='mkinfit.html'>mkinfit</a>.</p>
     <h2 class="hasAnchor" id="references"><a class="anchor" href="#references"></a>References</h2>
 
     <p>FOCUS (2006) &#8220;Guidance Document on Estimating Persistence
@@ -258,7 +263,7 @@ Evaluating and Calculating Degradation Kinetics in Environmental Media</p>
 <span class='no'>SFO_SFO</span> <span class='kw'>&lt;-</span> <span class='fu'>mkinmod</span>(
   <span class='kw'>parent</span> <span class='kw'>=</span> <span class='fu'><a href='mkinsub.html'>mkinsub</a></span>(<span class='st'>"SFO"</span>, <span class='st'>"m1"</span>),
   <span class='kw'>m1</span> <span class='kw'>=</span> <span class='fu'><a href='mkinsub.html'>mkinsub</a></span>(<span class='st'>"SFO"</span>), <span class='kw'>verbose</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)</div><div class='output co'>#&gt; Compilation argument:
-#&gt;  /usr/lib/R/bin/R CMD SHLIB file1bc3f55ac46.c 2&gt; file1bc3f55ac46.c.err.txt 
+#&gt;  /usr/lib/R/bin/R CMD SHLIB file15d25f6867c9.c 2&gt; file15d25f6867c9.c.err.txt 
 #&gt; Program source:
 #&gt;   1: #include &lt;R.h&gt;
 #&gt;   2: 
@@ -279,16 +284,35 @@ Evaluating and Calculating Degradation Kinetics in Environmental Media</p>
 #&gt;  17: f[0] = - k_parent * y[0];
 #&gt;  18: f[1] = + f_parent_to_m1 * k_parent * y[0] - k_m1 * y[1];
 #&gt;  19: }</div><div class='output co'>#&gt; <span class='message'>Successfully compiled differential equation model from auto-generated C code.</span></div><div class='input'>
+<span class='co'># The symbolic solution which is available in this case is not</span>
+<span class='co'># made for human reading but for speed of computation</span>
+<span class='no'>SFO_SFO</span>$<span class='no'>deg_func</span></div><div class='output co'>#&gt; function (observed, odeini, odeparms) 
+#&gt; {
+#&gt;     predicted &lt;- numeric(0)
+#&gt;     with(as.list(odeparms), {
+#&gt;         t &lt;- observed[observed$name == "parent", "time"]
+#&gt;         predicted &lt;&lt;- c(predicted, SFO.solution(t, odeini["parent"], 
+#&gt;             k_parent))
+#&gt;         t &lt;- observed[observed$name == "m1", "time"]
+#&gt;         predicted &lt;&lt;- c(predicted, (((k_m1 - k_parent) * odeini["m1"] - 
+#&gt;             f_parent_to_m1 * k_parent * odeini["parent"]) * exp(-k_m1 * 
+#&gt;             t) + f_parent_to_m1 * k_parent * odeini["parent"] * 
+#&gt;             exp(-k_parent * t))/(k_m1 - k_parent))
+#&gt;     })
+#&gt;     return(predicted)
+#&gt; }
+#&gt; &lt;environment: 0x5555576161e0&gt;</div><div class='input'>
 <span class='co'># If we have several parallel metabolites</span>
 <span class='co'># (compare tests/testthat/test_synthetic_data_for_UBA_2014.R)</span>
-<span class='no'>m_synth_DFOP_par</span> <span class='kw'>&lt;-</span> <span class='fu'>mkinmod</span>(<span class='kw'>parent</span> <span class='kw'>=</span> <span class='fu'><a href='mkinsub.html'>mkinsub</a></span>(<span class='st'>"DFOP"</span>, <span class='fu'><a href='https://rdrr.io/r/base/c.html'>c</a></span>(<span class='st'>"M1"</span>, <span class='st'>"M2"</span>)),
-                           <span class='kw'>M1</span> <span class='kw'>=</span> <span class='fu'><a href='mkinsub.html'>mkinsub</a></span>(<span class='st'>"SFO"</span>),
-                           <span class='kw'>M2</span> <span class='kw'>=</span> <span class='fu'><a href='mkinsub.html'>mkinsub</a></span>(<span class='st'>"SFO"</span>),
-                           <span class='kw'>use_of_ff</span> <span class='kw'>=</span> <span class='st'>"max"</span>, <span class='kw'>quiet</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)
+<span class='no'>m_synth_DFOP_par</span> <span class='kw'>&lt;-</span> <span class='fu'>mkinmod</span>(
+ <span class='kw'>parent</span> <span class='kw'>=</span> <span class='fu'><a href='mkinsub.html'>mkinsub</a></span>(<span class='st'>"DFOP"</span>, <span class='fu'><a href='https://rdrr.io/r/base/c.html'>c</a></span>(<span class='st'>"M1"</span>, <span class='st'>"M2"</span>)),
+ <span class='kw'>M1</span> <span class='kw'>=</span> <span class='fu'><a href='mkinsub.html'>mkinsub</a></span>(<span class='st'>"SFO"</span>),
+ <span class='kw'>M2</span> <span class='kw'>=</span> <span class='fu'><a href='mkinsub.html'>mkinsub</a></span>(<span class='st'>"SFO"</span>),
+ <span class='kw'>use_of_ff</span> <span class='kw'>=</span> <span class='st'>"max"</span>, <span class='kw'>quiet</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)
 
 <span class='no'>fit_DFOP_par_c</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='mkinfit.html'>mkinfit</a></span>(<span class='no'>m_synth_DFOP_par</span>,
-                          <span class='no'>synthetic_data_for_UBA_2014</span><span class='kw'>[[</span><span class='fl'>12</span>]]$<span class='no'>data</span>,
-                          <span class='kw'>quiet</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)
+  <span class='no'>synthetic_data_for_UBA_2014</span><span class='kw'>[[</span><span class='fl'>12</span>]]$<span class='no'>data</span>,
+  <span class='kw'>quiet</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)
 <span class='co'># }</span></div></pre>
   </div>
   <div class="col-md-3 hidden-xs hidden-sm" id="pkgdown-sidebar">
diff --git a/man/mkinmod.Rd b/man/mkinmod.Rd
index 6a6d2027..98623201 100644
--- a/man/mkinmod.Rd
+++ b/man/mkinmod.Rd
@@ -13,19 +13,19 @@ mkinmod(
 )
 }
 \arguments{
-\item{...}{For each observed variable, a list has to be specified as an
-argument, containing at least a component \code{type}, specifying the type
-of kinetics to use for the variable. Currently, single first order
-kinetics "SFO", indeterminate order rate equation kinetics "IORE", or
-single first order with reversible binding "SFORB" are implemented for all
-variables, while "FOMC", "DFOP" and "HS" can additionally be chosen for
-the first variable which is assumed to be the source compartment.
-Additionally, each component of the list can include a character vector
-\code{to}, specifying names of variables to which a transfer is to be
-assumed in the model.  If the argument \code{use_of_ff} is set to "min"
+\item{...}{For each observed variable, a list as obtained by \code{\link[=mkinsub]{mkinsub()}}
+has to be specified as an argument (see examples).  Currently, single
+first order kinetics "SFO", indeterminate order rate equation kinetics
+"IORE", or single first order with reversible binding "SFORB" are
+implemented for all variables, while "FOMC", "DFOP", "HS" and "logistic"
+can additionally be chosen for the first variable which is assumed to be
+the source compartment.
+Additionally, \code{\link[=mkinsub]{mkinsub()}} has an argument \code{to}, specifying names of
+variables to which a transfer is to be assumed in the model.
+If the argument \code{use_of_ff} is set to "min"
 (default) and the model for the compartment is "SFO" or "SFORB", an
-additional component of the list can be "sink=FALSE" effectively fixing
-the flux to sink to zero.}
+additional \code{\link[=mkinsub]{mkinsub()}} argument can be \code{sink = FALSE}, effectively
+fixing the flux to sink to zero.}
 
 \item{use_of_ff}{Specification of the use of formation fractions in the
 model equations and, if applicable, the coefficient matrix. If "min", a
@@ -39,11 +39,11 @@ argument. Default is NULL.}
 
 \item{quiet}{Should messages be suppressed?}
 
-\item{verbose}{If \code{TRUE}, passed to \code{\link{cfunction}} if
+\item{verbose}{If \code{TRUE}, passed to \code{\link[inline:cfunction]{inline::cfunction()}} if
 applicable to give detailed information about the C function being built.}
 }
 \value{
-A list of class \code{mkinmod} for use with \code{\link{mkinfit}},
+A list of class \code{mkinmod} for use with \code{\link[=mkinfit]{mkinfit()}},
 containing, among others,
 \item{diffs}{
 A vector of string representations of differential equations, one for
@@ -70,19 +70,27 @@ returned by cfunction.
 }
 }
 \description{
-The function usually takes several expressions, each assigning a compound
-name to a list, specifying the kinetic model type and reaction or transfer
-to other observed compartments. Instead of specifying several expressions, a
-list of lists can be given in the speclist argument.
+This function is usually called using a call to \code{\link[=mkinsub]{mkinsub()}} for each observed
+variable, specifying the corresponding submodel as well as outgoing pathways
+(see examples).
 }
 \details{
 For the definition of model types and their parameters, the equations given
 in the FOCUS and NAFTA guidance documents are used.
+
+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.
+
+If a C compiler is found by \code{\link[pkgbuild:has_compiler]{pkgbuild::has_compiler()}} and there
+is more than one observed variable in the specification, C code is generated
+for evaluating the differential equations, compiled using
+\code{\link[inline:cfunction]{inline::cfunction()}} and added to the resulting mkinmod object.
 }
 \note{
 The IORE submodel is not well tested for metabolites. When using this
-model for metabolites, you may want to read the second note in the help
-page to \code{\link{mkinfit}}.
+model for metabolites, you may want to read the note in the help
+page to \link{mkinfit}.
 }
 \examples{
 
@@ -105,16 +113,21 @@ SFO_SFO <- mkinmod(
   parent = mkinsub("SFO", "m1"),
   m1 = mkinsub("SFO"), verbose = TRUE)
 
+# The symbolic solution which is available in this case is not
+# made for human reading but for speed of computation
+SFO_SFO$deg_func
+
 # If we have several parallel metabolites
 # (compare tests/testthat/test_synthetic_data_for_UBA_2014.R)
-m_synth_DFOP_par <- mkinmod(parent = mkinsub("DFOP", c("M1", "M2")),
-                           M1 = mkinsub("SFO"),
-                           M2 = mkinsub("SFO"),
-                           use_of_ff = "max", quiet = TRUE)
+m_synth_DFOP_par <- mkinmod(
+ parent = mkinsub("DFOP", c("M1", "M2")),
+ M1 = mkinsub("SFO"),
+ M2 = mkinsub("SFO"),
+ use_of_ff = "max", quiet = TRUE)
 
 fit_DFOP_par_c <- mkinfit(m_synth_DFOP_par,
-                          synthetic_data_for_UBA_2014[[12]]$data,
-                          quiet = TRUE)
+  synthetic_data_for_UBA_2014[[12]]$data,
+  quiet = TRUE)
 }
 
 }