<!–html_preserve–><!–/html_preserve–>
This briefly describes the syntax used to define models
that RxODE
will translate into R-callable compiled code. It also
describes the communication of variables between R
and the
RxODE
modeling specification.
# An RxODE model specification (this line is a comment).
if(comed==0){ # concomitant medication (con-med)?
F = 1.0; # full bioavailability w.o. con-med
}
else {
F = 0.80; # 20% reduced bioavailability
}
C2 = centr/V2; # concentration in the central compartment
C3 = peri/V3; # concentration in the peripheral compartment
# ODE describing the PK and PD
d/dt(depot) = -KA*depot;
d/dt(centr) = F*KA*depot - CL*C2 - Q*C2 + Q*C3;
d/dt(peri) = Q*C2 - Q*C3;
d/dt(eff) = Kin - Kout*(1-C2/(EC50+C2))*eff;
An RxODE
model specification consists of one or more
statements terminated by semi-colons ;
and
optional comments (comments are delimited by #
and an
end-of-line).
A block of statements is a set of statements delimited by
curly braces, { ... }
.
Statements can be either assignments, conditional if
statements, or
printing statements (for debugging/testing). Assignment statements can
be:
d/dt(depot)
:depot(0) = 0
d/dt(y) = dy
, then a Jacobian for this
compartment can be specified as df(y)/dy(dy) = 1
. There may be
some advantage to obtaining the solution or specifying the Jacobian
for very stiff ODE systems. However, for the few stiff systems we
tried with LSODA, this actually slightly slowed down the solving.Note that assignment can be done by =
or <-
.
Additionally, assignment can be done with the ~
operator, which
causes RxODE to use the variable/expression while solving but suppress
output to either the matrix or data-frame returned in R. The
suppression works with simple assignments and time-derivative
assignments. All other variable/assignments do not produce output,
but are used for the solving.
An example model is shown below:
# simple assignment
C2 = centr/V2;
# time-derivative assignment
d/dt(centr) = F*KA*depot - CL*C2 - Q*C2 + Q*C3;
Expressions in assignment and if
statements can be numeric or logical,
however, no character nor integer expressions are currently supported.
Numeric expressions can include the following numeric operators +, -,
*, /, ^
and those mathematical functions defined in the C or the R
math libraries (e.g., fabs
, exp
, log
, sin
, abs
). In addition, the
factorial operator and function (either !
or factorial
as in R)
can be used. Notice that the modulo operator %
is currently
unsupported.
You may also access the R's functions in
the
R math libraries,
like lgammafn
for the log gamma function
The RxODE
syntax is case-sensitive, i.e., ABC
is different
than abc
, Abc
, ABc
, etc.
Like R, Identifiers (variable names) may consist of one or more alphanumeric,
underscore _
or period .
characters, but the first character
cannot be a digit or underscore _
.
Identifiers in a model specification can refer to:
t
(time), tlast
(last time point), and
podo
(oral dose, in the undocumented case of absorption transit
models).pi
or
R's predefined constants.ka
rate of absorption, CL
clearance, etc.)Currently, the RxODE
modeling language only recognizes system state
variables and “parameters”, thus, any values that need to be passed
from R to the ODE model (e.g., age
) should be passed in the params
argument of the integrator function solve()
.
Sometimes RxODE generates variables that are fed back to RxODE. These
variables start with the rx
prefix. To avoid any problems, it is
suggested to not use these variables starting with the rx
prefix.
Users specify which variables are the dynamic system's state variables
via the d/dt(identifier)
operator as part of the model specification,
and which are model parameters via the params=
argument in RxODE
solve()
method:
m1 <- RxODE(model = ode, modName = "m1")
# model parameters -- a named vector is required
theta <-
c(KA=0.29, CL=18.6, V2=40.2, Q=10.5, V3=297, Kin=1, Kout=1, EC50=200)
# state variables and their amounts at time 0 (the use of names is
# encouraged, but not required)
inits <- c(depot=0, centr=0, peri=0, eff=1)
# qd1 is an eventTable specification with a set of dosing and sampling
# records (code not shown here)
m1$solve(theta, event = qd1, inits = inits)
The values of these variables at pre-specified time points are
saved during model fitting/integration and returned as part of the
fitted values (see the function eventTable
, in particular its
member function add.sampling
function to define a set of time points when
to capture the values of these variables) and returned as
part of the modeling output.
The ODE specification mini-language is parsed with the help of the open source tool DParser, Plevyak (2015).
The modulo operator %
is currently unsupported.