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 --- docs/dev/pkgdown.yml | 2 +- docs/dev/reference/mkinmod.html | 88 ++++++++++++++++++++++++++--------------- 2 files changed, 57 insertions(+), 33 deletions(-) (limited to 'docs') 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) # }