Produce predictions from a kinetic model using specific parameters

+ + +

This function produces a time series for all the observed variables in a +kinetic model as specified by mkinmod, using a specific set of +kinetic parameters and initial values for the state variables.

+ +

mkinpredict(
+  x,
+  odeparms,
+  odeini,
+  outtimes = seq(0, 120, by = 0.1),
+  solution_type = "deSolve",
+  use_compiled = "auto",
+  method.ode = "lsoda",
+  atol = 1e-08,
+  rtol = 1e-10,
+  map_output = TRUE,
+  ...
+)
+
+# S3 method for mkinmod
+mkinpredict(
+  x,
+  odeparms = c(k_parent_sink = 0.1),
+  odeini = c(parent = 100),
+  outtimes = seq(0, 120, by = 0.1),
+  solution_type = "deSolve",
+  use_compiled = "auto",
+  method.ode = "lsoda",
+  atol = 1e-08,
+  rtol = 1e-10,
+  map_output = TRUE,
+  ...
+)
+
+# S3 method for mkinfit
+mkinpredict(
+  x,
+  odeparms = x$bparms.ode,
+  odeini = x$bparms.state,
+  outtimes = seq(0, 120, by = 0.1),
+  solution_type = "deSolve",
+  use_compiled = "auto",
+  method.ode = "lsoda",
+  atol = 1e-08,
+  rtol = 1e-10,
+  map_output = TRUE,
+  ...
+)

+ +

Arguments

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

x	A kinetic model as produced by `mkinmod`, or a kinetic +fit as fitted by `mkinfit`. In the latter case, the fitted +parameters are used for the prediction.
odeparms	A numeric vector specifying the parameters used in the +kinetic model, which is generally defined as a set of ordinary +differential equations.
odeini	A numeric vector containing the initial values of the state +variables of the model. Note that the state variables can differ from the +observed variables, for example in the case of the SFORB model.
outtimes	A numeric vector specifying the time points for which model +predictions should be generated.
solution_type	The method that should be used for producing the +predictions. This should generally be "analytical" if there is only one +observed variable, and usually "deSolve" in the case of several observed +variables. The third possibility "eigen" is faster but not applicable to +some models e.g. using FOMC for the parent compound.
use_compiled	If set to `FALSE`, no compiled version of the +`mkinmod` model is used, even if is present.
method.ode	The solution method passed via `mkinpredict` +to `ode` in case the solution type is "deSolve". The default +"lsoda" is performant, but sometimes fails to converge.
atol	Absolute error tolerance, passed to `ode`. Default +is 1e-8, lower than in `lsoda`.
rtol	Absolute error tolerance, passed to `ode`. Default +is 1e-10, much lower than in `lsoda`.
map_output	Boolean to specify if the output should list values for +the observed variables (default) or for all state variables (if set to +FALSE). Setting this to FALSE has no effect for analytical solutions, +as these always return mapped output.
...	Further arguments passed to the ode solver in case such a +solver is used.

+ +

Value

+ +

A matrix with the numeric solution in wide format

+ +

Examples


+SFO <- mkinmod(degradinol = mkinsub("SFO"))
+# Compare solution types
+mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
+      solution_type = "analytical")
#>    time  degradinol
+#> 0     0 100.0000000
+#> 1     1  74.0818221
+#> 2     2  54.8811636
+#> 3     3  40.6569660
+#> 4     4  30.1194212
+#> 5     5  22.3130160
+#> 6     6  16.5298888
+#> 7     7  12.2456428
+#> 8     8   9.0717953
+#> 9     9   6.7205513
+#> 10   10   4.9787068
+#> 11   11   3.6883167
+#> 12   12   2.7323722
+#> 13   13   2.0241911
+#> 14   14   1.4995577
+#> 15   15   1.1108997
+#> 16   16   0.8229747
+#> 17   17   0.6096747
+#> 18   18   0.4516581
+#> 19   19   0.3345965
+#> 20   20   0.2478752
mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
+      solution_type = "deSolve")
#>    time  degradinol
+#> 0     0 100.0000000
+#> 1     1  74.0818221
+#> 2     2  54.8811636
+#> 3     3  40.6569660
+#> 4     4  30.1194212
+#> 5     5  22.3130160
+#> 6     6  16.5298888
+#> 7     7  12.2456428
+#> 8     8   9.0717953
+#> 9     9   6.7205513
+#> 10   10   4.9787068
+#> 11   11   3.6883167
+#> 12   12   2.7323722
+#> 13   13   2.0241911
+#> 14   14   1.4995577
+#> 15   15   1.1108996
+#> 16   16   0.8229747
+#> 17   17   0.6096747
+#> 18   18   0.4516581
+#> 19   19   0.3345965
+#> 20   20   0.2478752
mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
+      solution_type = "deSolve", use_compiled = FALSE)
#>    time  degradinol
+#> 0     0 100.0000000
+#> 1     1  74.0818221
+#> 2     2  54.8811636
+#> 3     3  40.6569660
+#> 4     4  30.1194212
+#> 5     5  22.3130160
+#> 6     6  16.5298888
+#> 7     7  12.2456428
+#> 8     8   9.0717953
+#> 9     9   6.7205513
+#> 10   10   4.9787068
+#> 11   11   3.6883167
+#> 12   12   2.7323722
+#> 13   13   2.0241911
+#> 14   14   1.4995577
+#> 15   15   1.1108996
+#> 16   16   0.8229747
+#> 17   17   0.6096747
+#> 18   18   0.4516581
+#> 19   19   0.3345965
+#> 20   20   0.2478752
mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
+      solution_type = "eigen")
#>    time  degradinol
+#> 0     0 100.0000000
+#> 1     1  74.0818221
+#> 2     2  54.8811636
+#> 3     3  40.6569660
+#> 4     4  30.1194212
+#> 5     5  22.3130160
+#> 6     6  16.5298888
+#> 7     7  12.2456428
+#> 8     8   9.0717953
+#> 9     9   6.7205513
+#> 10   10   4.9787068
+#> 11   11   3.6883167
+#> 12   12   2.7323722
+#> 13   13   2.0241911
+#> 14   14   1.4995577
+#> 15   15   1.1108997
+#> 16   16   0.8229747
+#> 17   17   0.6096747
+#> 18   18   0.4516581
+#> 19   19   0.3345965
+#> 20   20   0.2478752

+# Compare integration methods to analytical solution
+mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
+      solution_type = "analytical")[21,]
#>       time degradinol 
+#> 20.0000000  0.2478752 
mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
+      method = "lsoda")[21,]
#>       time degradinol 
+#> 20.0000000  0.2478752 
mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
+      method = "ode45")[21,]
#>       time degradinol 
+#> 20.0000000  0.2478752 
mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
+      method = "rk4")[21,]
#>       time degradinol 
+#> 20.0000000  0.2480043 
# rk4 is not as precise here
+
+# The number of output times used to make a lot of difference until the
+# default for atol was adjusted
+mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100),
+      seq(0, 20, by = 0.1))[201,]
#>       time degradinol 
+#> 20.0000000  0.2478752 
mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100),
+      seq(0, 20, by = 0.01))[2001,]
#>       time degradinol 
+#> 20.0000000  0.2478752 

+# Comparison of the performance of solution types
+SFO_SFO = mkinmod(parent = list(type = "SFO", to = "m1"),
+                  m1 = list(type = "SFO"), use_of_ff = "max")
#> Successfully compiled differential equation model from auto-generated C code.
if(require(rbenchmark)) {
+  benchmark(replications = 10, order = "relative", columns = c("test", "relative", "elapsed"),
+    eigen = mkinpredict(SFO_SFO,
+      c(k_parent = 0.15, f_parent_to_m1 = 0.5, k_m1 = 0.01),
+      c(parent = 100, m1 = 0), seq(0, 20, by = 0.1),
+      solution_type = "eigen")[201,],
+    deSolve_compiled = mkinpredict(SFO_SFO,
+      c(k_parent = 0.15, f_parent_to_m1 = 0.5, k_m1 = 0.01),
+      c(parent = 100, m1 = 0), seq(0, 20, by = 0.1),
+      solution_type = "deSolve")[201,],
+    deSolve = mkinpredict(SFO_SFO,
+      c(k_parent = 0.15, f_parent_to_m1 = 0.5, k_m1 = 0.01),
+      c(parent = 100, m1 = 0), seq(0, 20, by = 0.1),
+      solution_type = "deSolve", use_compiled = FALSE)[201,],
+    analytical = mkinpredict(SFO_SFO,
+      c(k_parent = 0.15, f_parent_to_m1 = 0.5, k_m1 = 0.01),
+      c(parent = 100, m1 = 0), seq(0, 20, by = 0.1),
+      solution_type = "analytical", use_compiled = FALSE)[201,])
+}
#>               test relative elapsed
+#> 2 deSolve_compiled      1.0   0.005
+#> 4       analytical      1.0   0.005
+#> 1            eigen      4.0   0.020
+#> 3          deSolve     45.6   0.228

+# \dontrun{
+  # Predict from a fitted model
+  f <- mkinfit(SFO_SFO, FOCUS_2006_C, quiet = TRUE)
+  f <- mkinfit(SFO_SFO, FOCUS_2006_C, quiet = TRUE, solution_type = "deSolve")
+  head(mkinpredict(f))
#>     time   parent       m1
+#> 0    0.0 82.49216 0.000000
+#> 0.1  0.1 80.00562 1.236198
+#> 0.2  0.2 77.59404 2.422818
+#> 0.3  0.3 75.25514 3.561476
+#> 0.4  0.4 72.98675 4.653740
+#> 0.5  0.5 70.78673 5.701130
# }
+
+

+ +