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.

+ +

mkinmod(
+  ...,
+  use_of_ff = "max",
+  speclist = NULL,
+  quiet = FALSE,
+  verbose = FALSE
+)

+ +

Arguments

+ + + + + + + + + + + + + + + + + + + + + + +

...	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" +(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.
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 +product of formation fractions and rate constants. If "max", formation +fractions are always used.
speclist	The specification of the observed variables and their +submodel types and pathways can be given as a single list using this +argument. Default is NULL.
quiet	Should messages be suppressed?
verbose	If `TRUE`, passed to `cfunction` if +applicable to give detailed information about the C function being built.

+ +

Value

+ +

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.

map

A list containing named character vectors for each observed variable, +specifying the modelling variables by which it is represented.

use_of_ff

The content of use_of_ff is passed on in this list component.

deg_func

If generated, a function containing the solution of the degradation +model.

coefmat

The coefficient matrix, if the system of differential equations can be +represented by one.

If generated, a compiled function calculating the derivatives as +returned by cfunction.

+ +

Details

+ +

For the definition of model types and their parameters, the equations given +in the FOCUS and NAFTA guidance documents are used.

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.

References

+ +

FOCUS (2006) “Guidance Document on Estimating Persistence +and Degradation Kinetics from Environmental Fate Studies on Pesticides in +EU Registration” Report of the FOCUS Work Group on Degradation Kinetics, +EC Document Reference Sanco/10058/2005 version 2.0, 434 pp, +http://esdac.jrc.ec.europa.eu/projects/degradation-kinetics

NAFTA Technical Working Group on Pesticides (not dated) Guidance for +Evaluating and Calculating Degradation Kinetics in Environmental Media

+ +

Examples


+# Specify the SFO model (this is not needed any more, as we can now mkinfit("SFO", ...)
+SFO <- mkinmod(parent = mkinsub("SFO"))
+
+# One parent compound, one metabolite, both single first order
+SFO_SFO <- mkinmod(
+  parent = mkinsub("SFO", "m1"),
+  m1 = mkinsub("SFO"))
#> Successfully compiled differential equation model from auto-generated C code.

+# \dontrun{
+# The above model used to be specified like this, before the advent of mkinsub()
+SFO_SFO <- mkinmod(
+  parent = list(type = "SFO", to = "m1"),
+  m1 = list(type = "SFO"))
#> Successfully compiled differential equation model from auto-generated C code.

+# Show details of creating the C function
+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 
+#> Program source:
+#>   1: #include <R.h>
+#>   2: 
+#>   3: 
+#>   4: static double parms [3];
+#>   5: #define k_parent parms[0]
+#>   6: #define f_parent_to_m1 parms[1]
+#>   7: #define k_m1 parms[2]
+#>   8: 
+#>   9: void initpar(void (* odeparms)(int *, double *)) {
+#>  10:     int N = 3;
+#>  11:     odeparms(&N, parms);
+#>  12: }
+#>  13: 
+#>  14: 
+#>  15: void func ( int * n, double * t, double * y, double * f, double * rpar, int * ipar ) {
+#>  16: 
+#>  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.

+# 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)
+
+fit_DFOP_par_c <- mkinfit(m_synth_DFOP_par,
+                          synthetic_data_for_UBA_2014[[12]]$data,
+                          quiet = TRUE)
+# }

+ +