Accessing Information in dMod Objects

Many of the objects in dMod carry attributes or special value within their environments. Here, we highlight the major functions to access this information and manipulate it.

We start with setting up a small model, i.e. a prediction function x and a parameter transformation function p. The model describes a simple dissipative system that is excited by an external periodic force.

library(dMod)
library(dplyr)

x <- eqnvec(
  A = "-lambda*A + sin(omega*time)^2"
) %>% 
  odemodel(modelname = "oscillator") %>% 
  Xs()

p <- 
  eqnvec(
    omega = "3.14/T",
    lambda = "exp(lambda)",
    A = 0
  ) %>% 
  P(condition = "First_harmonic") +
  eqnvec(
    omega = "3.14/T/2",
    lambda = "exp(lambda)",
    A = 0
  ) %>% 
  P(condition = "Second_harmonic")

Extract equations with getEquations

Whenever symbolic information goes into a function, it can usually be extract with getEquations. Typical examples are prediction functions, parameter transformation functions and observation functions. For our example we get the differential equations back from x:

getEquations(x)
## [[1]]
## Idx Inner <- Outer
##   1     A <- -lambda*A+sin(omega*time)^2

The parameter transformation is returned from p:

getEquations(p)
## $First_harmonic
## Idx  Inner <- Outer
##   3      A <- 0
##   2 lambda <- exp(lambda)
##   1  omega <- 3.14/T
## 
## $Second_harmonic
## Idx  Inner <- Outer
##   3      A <- 0
##   2 lambda <- exp(lambda)
##   1  omega <- 3.14/T/2

Extract derivative information with getDerivs

Another important get function is getDerivs which returns numeric values from evaluated prediction, observation and parameter transformation function. We define parameters, times and compute the prediction.

pars <- c(lambda = -1, T = 10)
pinner <- p(pars)

times <- seq(0, 20, .1)
prediction <- (x*p)(times, pars, deriv = TRUE)
plot(prediction)

To extract the Jacobian of the parameter transformation, we call:

getDerivs(pinner)
## $First_harmonic
##           lambda       T
## omega  0.0000000 -0.0314
## lambda 0.3678794  0.0000
## A      0.0000000  0.0000
## 
## $Second_harmonic
##           lambda       T
## omega  0.0000000 -0.0157
## lambda 0.3678794  0.0000
## A      0.0000000  0.0000

Also the sensitivities of the model prediction are accessible. The are returned by getDerivs as a prediction list (same as the model prediction itself). Therefore, we can directly plot the result:

getDerivs(prediction) %>% plot()

Extract parameters with getParameters

The getParameters command can be applied to functions as well as evaluated functions. For parameter-, prediction- and observation functions we get the symbols back:

getParameters(x)
## [1] "A"      "lambda" "omega"
getParameters(p)
## [1] "T"      "lambda"

For the evaluated prediction function, we get the inner parameters that went into the model evaluation:

getParameters(prediction)
## $First_harmonic
##      A:  0
## lambda:  0.367879441171442
##  omega:  0.314
## 
## $Second_harmonic
##      A:  0
## lambda:  0.367879441171442
##  omega:  0.157

Changing options of dMod objects

Usually, when dMod objects (e.g. functions) are created, the user can supply additional options that control the behavior of the functions. These options are saved in the environment of the function as controls and can be accessed with the controls() command.

For example parameter transformtion functions can be created with the argument attach.input = TRUE or FALSE. We see this option when we call:

controls(p)
## First_harmonic:
## [1] "attach.input"
## Second_harmonic:
## [1] "attach.input"

Here, we see that p is composed and each function has its own controls. We access a specific control in this way:

controls(p, "First_harmonic", "attach.input")
## [1] FALSE

The option also can be changed:

controls(p, "First_harmonic", "attach.input") <- TRUE

When we call p again after changing the option, the result is:

p(pars)
## $First_harmonic
##      A:  0
## lambda:  0.367879441171442
##  omega:  0.314
##      T:  10
## 
## $Second_harmonic
##      A:  0
## lambda:  0.367879441171442
##  omega:  0.157

For the first condition, incoming parameters are attached. The second transformation still has the default behavior of only returning the explicitly defined parameters. Prominent examples for the attach.input option are observation functions. To save time during parameter estimation, attach.input would be switched off. When simulating with parameters, one might be interested in the observations and the internal states. With controls(), attach.input can be switched back on.

Prediction functions have some more options:

controls(x)
## :
## [1] "forcings"    "events"      "names"       "optionsOde"  "optionsSens"
## [6] "fcontrol"

The lonly “:” indicates that no conditions were defined for x. To access the single options, we need to specify condition = NULL, and call for example:

controls(x, NULL, "optionsSens")
## $method
## [1] "lsodes"

Conclusion

Find out all about get functions in dMod with dMod::get + TAB. Try controls(object) to see which of the options you can change at any time.

Happy exploring of options!!