RxODE
Modeling SyntaxThis vignette 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 or conditional if
statements. Assignment statements can be either simple assignments, where the left hand is an identifier (i.e., variable), or special time-derivative assignments, where the left hand specifies the change of the amount in the corresponding state variable (compartment) with respect to time
e.g., d/dt(depot)
:
# 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
). Notice that the modulo operator %
is currently unsupported.
The RxODE
syntax is case-sensitive, i.e., ABC
is different than abc
, Abc
, ABc
, etc.
Identifiers (variable names) may consist of one or more alphanumeric and underscore _
characters, but the first character cannot be a digit. NB: The dot .
character may not be used as part of an identifier.
Identifiers in a model specification can refer to: * State variables in the dynamic system (e.g., compartments in a pharmacokinetics model). * Implied input variable, t
(time), tlast
(last time point), and podo
(oral dose, in the undocumented case of absorption transit models). * Model parameters (e.g., ka
rate of absorption, CL
clearance, etc.) * Others, as created by assignments as part of the model specification; these are referred as LHS (left-hand side) variable.
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()
.
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.
Comments are not allowed inside statements, therefore the following code is syntactically incorrect:
# incorrect syntax (comments not allowed inside statements)
S2 = 1.0 # scaler for the central compartment ;
# correct syntax
S2 = 1.0; # scaler for the central compartment
The modulo operator %
is currently unsupported. Similarly, the old-style exponentiation operator **
is unsupported (use ^
).