aboutsummaryrefslogtreecommitdiff
path: root/R/mkinmod.R
diff options
context:
space:
mode:
Diffstat (limited to 'R/mkinmod.R')
-rw-r--r--R/mkinmod.R65
1 files changed, 39 insertions, 26 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

Contact - Imprint