Function to set up a kinetic model with one or more state variables

+ +

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

Print mkinmod objects in a way that the user finds his way to get to its +components.

+ +

Usage

mkinmod(
+  ...,
+  use_of_ff = "max",
+  name = NULL,
+  speclist = NULL,
+  quiet = FALSE,
+  verbose = FALSE,
+  dll_dir = NULL,
+  unload = FALSE,
+  overwrite = FALSE
+)
+
+# S3 method for class 'mkinmod'
+print(x, ...)
+
+mkinsub(submodel, to = NULL, sink = TRUE, full_name = NA)

+ +

Arguments

+ + +

...: 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" +and the model for the compartment is "SFO" or "SFORB", an +additional mkinsub() argument can be sink = FALSE, effectively +fixing the flux to sink to zero. +In print.mkinmod, this argument is currently not used.
use_of_ff: Specification of the use of formation fractions in the +model equations and, if applicable, the coefficient matrix. If "max", +formation fractions are always used (default). If "min", a minimum use of +formation fractions is made, i.e. each first-order pathway to a metabolite +has its own rate constant.
name: A name for the model. Should be a valid R object name.
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 inline::cfunction() if +applicable to give detailed information about the C function being built.
dll_dir: Directory where an DLL object, if generated internally by +inline::cfunction(), should be saved. The DLL will only be stored in a +permanent location for use in future sessions, if 'dll_dir' and 'name' +are specified. This is helpful if fit objects are cached e.g. by knitr, +as the cache remains functional across sessions if the DLL is stored in +a user defined location.
unload: If a DLL from the target location in 'dll_dir' is already +loaded, should that be unloaded first?
overwrite: If a file exists at the target DLL location in 'dll_dir', +should this be overwritten?
x: An mkinmod object.
submodel: Character vector of length one to specify the submodel type. +See mkinmod for the list of allowed submodel names.
to: Vector of the names of the state variable to which a +transformation shall be included in the model.
sink: Should a pathway to sink be included in the model in addition to +the pathways to other state variables?
full_name: An optional name to be used e.g. for plotting fits +performed with the model. You can use non-ASCII characters here, but then +your R code will not be portable, i.e. may produce unintended plot +results on other operating systems or system configurations.

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.
cf: If generated, a compiled function calculating the derivatives as +returned by cfunction.

A list for use with mkinmod.

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

Author

Johannes Ranke

+ +

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"))
+#> Temporary DLL for differentials generated and loaded
+print(SFO_SFO)
+#> <mkinmod> model generated with
+#> Use of formation fractions $use_of_ff: max 
+#> Specification $spec:
+#> $parent
+#> $type: SFO; $to: m1; $sink: TRUE
+#> $m1
+#> $type: SFO; $sink: TRUE
+#> Coefficient matrix $coefmat available
+#> Compiled model $cf available
+#> Differential equations:
+#> d_parent/dt = - k_parent * parent
+#> d_m1/dt = + f_parent_to_m1 * k_parent * parent - k_m1 * m1
+
+# \dontrun{
+ fit_sfo_sfo <- mkinfit(SFO_SFO, FOCUS_2006_D, quiet = TRUE, solution_type = "deSolve")
+#> Warning: Observations with value of zero were removed from the data
+
+ # Now supplying compound names used for plotting, and write to user defined location
+ # We need to choose a path outside the session tempdir because this gets removed
+ DLL_dir <- "~/.local/share/mkin"
+ if (!dir.exists(DLL_dir)) dir.create(DLL_dir)
+ SFO_SFO.2 <- mkinmod(
+   parent = mkinsub("SFO", "m1", full_name = "Test compound"),
+   m1 = mkinsub("SFO", full_name = "Metabolite M1"),
+   name = "SFO_SFO", dll_dir = DLL_dir, unload = TRUE, overwrite = TRUE)
+#> Temporary DLL for differentials generated and loaded
+#> Copied DLL from /tmp/RtmpSeNGYy/file226312370605e2.so to /home/jranke/.local/share/mkin/SFO_SFO.so
+# Now we can save the model and restore it in a new session
+saveRDS(SFO_SFO.2, file = "~/SFO_SFO.rds")
+# Terminate the R session here if you would like to check, and then do
+library(mkin)
+SFO_SFO.3 <- readRDS("~/SFO_SFO.rds")
+fit_sfo_sfo <- mkinfit(SFO_SFO.3, FOCUS_2006_D, quiet = TRUE, solution_type = "deSolve")
+#> Warning: Observations with value of zero were removed from the data
+
+# Show details of creating the C function
+SFO_SFO <- mkinmod(
+  parent = mkinsub("SFO", "m1"),
+  m1 = mkinsub("SFO"), verbose = TRUE)
+#> 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 diffs ( 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: }
+#> Temporary DLL for differentials generated and loaded
+
+# 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: 0x5555577ec6d0>
+
+# 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"),
+ quiet = TRUE)
+
+fit_DFOP_par_c <- mkinfit(m_synth_DFOP_par,
+  synthetic_data_for_UBA_2014[[12]]$data,
+  quiet = TRUE)
+# }
+
+