From 156b82b88dbd73e9370c74b474432b410415046d Mon Sep 17 00:00:00 2001 From: Johannes Ranke Date: Wed, 27 May 2020 08:54:54 +0200 Subject: Improve mkinmod docs --- R/mkinmod.R | 65 ++++++++++++++++++------------ docs/dev/pkgdown.yml | 2 +- docs/dev/reference/mkinmod.html | 88 ++++++++++++++++++++++++++--------------- 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 @@ - + @@ -75,7 +74,7 @@ list of lists can be given in the speclist argument." /> mkin - 0.9.50.3 + 0.9.50.3 @@ -147,10 +146,9 @@ list of lists can be given in the speclist argument." />
-

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).

mkinmod(
@@ -166,19 +164,19 @@ list of lists can be given in the speclist argument.

     
     
       ...
-      
For each observed variable, a list has to be specified as an
-argument, containing at least a component 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
-to, specifying names of variables to which a transfer is to be
-assumed in the model.  If the argument use_of_ff is set to "min"
+      
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 to, specifying names of
+variables to which a transfer is to be assumed in the model.
+If the argument 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 sink = FALSE, effectively
+fixing the flux to sink to zero.

     
     
       use_of_ff
@@ -200,14 +198,14 @@ argument. Default is NULL.

     
     
       verbose
-      
If TRUE, passed to cfunction if
+      
If TRUE, passed to inline::cfunction() if
 applicable to give detailed information about the C function being built.

     
     
 
     
Value

 
-    
A list of class mkinmod for use with mkinfit,
+    
A list of class mkinmod for use with mkinfit(),
 containing, among others,

 
diffs
A vector of string representations of differential equations, one for
 each modelling variable.

@@ -225,11 +223,18 @@ returned by cfunction.

 
     
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 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.

     
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 mkinfit.

+model for metabolites, you may want to read the note in the help
+page to mkinfit.

     
References

 
     
FOCUS (2006) “Guidance Document on Estimating Persistence
@@ -258,7 +263,7 @@ Evaluating and Calculating Degradation Kinetics in Environmental Media

 SFO_SFO <- mkinmod(
   parent = mkinsub("SFO", "m1"),
   m1 = mkinsub("SFO"), verbose = TRUE)
#> 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

 #>  17: f[0] = - k_parent * y[0];
 #>  18: f[1] = + f_parent_to_m1 * k_parent * y[0] - k_m1 * y[1];
 #>  19: }
#> Successfully compiled differential equation model from auto-generated C code.

+# The symbolic solution which is available in this case is not
+# made for human reading but for speed of computation
+SFO_SFO$deg_func
#> 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>

 # 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)
 # }