diff options
| -rw-r--r-- | R/mkinmod.R | 65 | ||||
| -rw-r--r-- | docs/dev/pkgdown.yml | 2 | ||||
| -rw-r--r-- | docs/dev/reference/mkinmod.html | 88 | ||||
| -rw-r--r-- | man/mkinmod.Rd | 65 |
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) “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'><-</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'>#> Compilation argument: -#> /usr/lib/R/bin/R CMD SHLIB file1bc3f55ac46.c 2> file1bc3f55ac46.c.err.txt +#> /usr/lib/R/bin/R CMD SHLIB file15d25f6867c9.c 2> file15d25f6867c9.c.err.txt #> Program source: #> 1: #include <R.h> #> 2: @@ -279,16 +284,35 @@ Evaluating and Calculating Degradation Kinetics in Environmental Media</p> #> 17: f[0] = - k_parent * y[0]; #> 18: f[1] = + f_parent_to_m1 * k_parent * y[0] - k_m1 * y[1]; #> 19: }</div><div class='output co'>#> <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'>#> function (observed, odeini, odeparms) +#> { +#> predicted <- numeric(0) +#> with(as.list(odeparms), { +#> t <- observed[observed$name == "parent", "time"] +#> predicted <<- c(predicted, SFO.solution(t, odeini["parent"], +#> k_parent)) +#> t <- observed[observed$name == "m1", "time"] +#> predicted <<- c(predicted, (((k_m1 - k_parent) * odeini["m1"] - +#> f_parent_to_m1 * k_parent * odeini["parent"]) * exp(-k_m1 * +#> t) + f_parent_to_m1 * k_parent * odeini["parent"] * +#> exp(-k_parent * t))/(k_m1 - k_parent)) +#> }) +#> return(predicted) +#> } +#> <environment: 0x5555576161e0></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'><-</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'><-</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'><-</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) } } |