This briefly describes the syntax used to define modelsthat RxODE
will translate into R-callable compiled code. It alsodescribes the communication of variables between R
and theRxODE
modeling specification.
6.1 Example
# 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;
6.2 Syntax
An RxODE
model specification consists of one or morestatements optionally terminated by semi-colons ;
andoptional comments (comments are delimited by #
and anend-of-line).
A block of statements is a set of statements delimited bycurly braces, { ... }
.
Statements can be either assignments, conditional if
/else if
/else
, while
loops (can be exited by break
), specialstatements, or printing statements (for debugging/testing)
Assignment statements can be:
simple assignments, where the left hand is an identifier (i.e.,variable)
special time-derivative assignments, where the left handspecifies the change of the amount in the corresponding statevariable (compartment) with respect to time e.g.,
d/dt(depot)
:special initial-condition assignments where the left handspecifies the compartment of the initial condition being specified,e.g.
depot(0) = 0
special model event changes including bioavailability(
f(depot)=1
), lag time (alag(depot)=0
), modeled rate(rate(depot)=2
) and modeled duration (dur(depot)=2
). Anexample of these model features and the event specification for themodeled infusions the RxODE data specification is found in RxODEevents section.special change point syntax, or model times. These model times arespecified by
mtime(var)=time
special Jacobian-derivative assignments, where the left handspecifies the change in the compartment ode with respect to avariable. For example, if
d/dt(y) = dy
, then a Jacobian for thiscompartment can be specified asdf(y)/dy(dy) = 1
. There may besome advantage to obtaining the solution or specifying the Jacobianfor very stiff ODE systems. However, for the few stiff systems wetried with LSODA, this actually slightly slowed down the solving.
Note that assignment can be done by =
, <-
or ~
.
When assigning with the ~
operator, the simpleassignments and time-derivative assignments will not be output.
Special statements can be:
Compartment declaration statements, which can change the defaultdosing compartment and the assumed compartment number(s) as well asadd extra compartment names at the end (useful for multiple-endpointnlmixr models); These are specified by
cmt(compartmentName)
Parameter declaration statements, which can make sure the inputparameters are in a certain order instead of ordering the parametersby the order they are parsed. This is useful for keeping theparameter order the same when using 2 different ODE models. Theseare specified by
param(par1, par2,...)
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 Rmath libraries (e.g., fabs
, exp
, log
, sin
, abs
).
You may also access the R’s functions in the R mathlibraries,like lgammafn
for the log gamma function.
The RxODE
syntax is case-sensitive, i.e., ABC
is differentthan abc
, Abc
, ABc
, etc.
6.2.1 Identifiers
Like R, Identifiers (variable names) may consist of one or more alphanumeric,underscore _
or period .
characters, but the first charactercannot be a digit or underscore _
.
Identifiers in a model specification can refer to:
- State variables in the dynamic system (e.g., compartments in apharmaco*kinetics model).
- Implied input variable,
t
(time),tlast
(last time point), andpodo
(oral dose, in the undocumented case of absorption transitmodels). - Special constants like
pi
orR’s predefined constants. - 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 statevariables and “parameters”, thus, any values that need to be passedfrom R to the ODE model (e.g., age
) should be either passed in theparams
argument of the integrator function rxSolve()
or be in thesupplied event data-set.
There are certain variable names that are in the RxODE
event tables.To avoid confusion, the following event table-related items cannot beassigned, or used as a state but can be accessed in the RxODE code:
cmt
dvid
addl
ss
rate
id
However the following variables are cannot be used in a model specification:
evid
ii
Sometimes RxODE generates variables that are fed back to RxODE.Similarly, nlmixr generates some variables that are used in nlmixrestimation and simulation. These variables start with the either therx
or nlmixr
prefixes. To avoid any problems, it is suggested tonot use these variables starting with either the rx
or nlmixr
prefixes.
6.3 Logical Operators
Logical operators support the standard R operators ==
, !=
>=
<=
>
and <
. Like R these can be in if()
or while()
statements, ifelse()
expressions. Additionally they can be in astandard assignment. For instance, the following is valid:
cov1 = covm*(sexf == "female") + covm*(sexf != "female")
Notice that you can also use character expressions in comparisons.This convenience comes at a cost since character comparisons areslower than numeric expressions. Unlike R, as.numeric
oras.integer
for these logical statements is not only not needed, butwill cause an syntax error if you try to use the function.
6.4 cmt() changing compartment numbers for states
The compartment order can be changed with the cmt()
syntax in themodel. To understand what the cmt()
can do you need to understandhow RxODE
numbers the compartments.
Below is an example of how RxODE numbers compartments
6.4.1 How RxODE numbers compartments
RxODE automatically assigns compartment numbers when parsing. Forexample, with the Mavoglurant PBPK model the following model may beused:
library(RxODE)pbpk <- RxODE({ KbBR = exp(lKbBR) KbMU = exp(lKbMU) KbAD = exp(lKbAD) CLint= exp(lCLint + eta.LClint) KbBO = exp(lKbBO) KbRB = exp(lKbRB) ## Regional blood flows # Cardiac output (L/h) from White et al (1968) CO = (187.00*WT^0.81)*60/1000; QHT = 4.0 *CO/100; QBR = 12.0*CO/100; QMU = 17.0*CO/100; QAD = 5.0 *CO/100; QSK = 5.0 *CO/100; QSP = 3.0 *CO/100; QPA = 1.0 *CO/100; QLI = 25.5*CO/100; QST = 1.0 *CO/100; QGU = 14.0*CO/100; # Hepatic artery blood flow QHA = QLI - (QSP + QPA + QST + QGU); QBO = 5.0 *CO/100; QKI = 19.0*CO/100; QRB = CO - (QHT + QBR + QMU + QAD + QSK + QLI + QBO + QKI); QLU = QHT + QBR + QMU + QAD + QSK + QLI + QBO + QKI + QRB; ## Organs' volumes = organs' weights / organs' density VLU = (0.76 *WT/100)/1.051; VHT = (0.47 *WT/100)/1.030; VBR = (2.00 *WT/100)/1.036; VMU = (40.00*WT/100)/1.041; VAD = (21.42*WT/100)/0.916; VSK = (3.71 *WT/100)/1.116; VSP = (0.26 *WT/100)/1.054; VPA = (0.14 *WT/100)/1.045; VLI = (2.57 *WT/100)/1.040; VST = (0.21 *WT/100)/1.050; VGU = (1.44 *WT/100)/1.043; VBO = (14.29*WT/100)/1.990; VKI = (0.44 *WT/100)/1.050; VAB = (2.81 *WT/100)/1.040; VVB = (5.62 *WT/100)/1.040; VRB = (3.86 *WT/100)/1.040; ## Fixed parameters BP = 0.61; # Blood:plasma partition coefficient fup = 0.028; # Fraction unbound in plasma fub = fup/BP; # Fraction unbound in blood KbLU = exp(0.8334); KbHT = exp(1.1205); KbSK = exp(-.5238); KbSP = exp(0.3224); KbPA = exp(0.3224); KbLI = exp(1.7604); KbST = exp(0.3224); KbGU = exp(1.2026); KbKI = exp(1.3171); ##----------------------------------------- S15 = VVB*BP/1000; C15 = Venous_Blood/S15 ##----------------------------------------- d/dt(Lungs) = QLU*(Venous_Blood/VVB - Lungs/KbLU/VLU); d/dt(Heart) = QHT*(Arterial_Blood/VAB - Heart/KbHT/VHT); d/dt(Brain) = QBR*(Arterial_Blood/VAB - Brain/KbBR/VBR); d/dt(Muscles) = QMU*(Arterial_Blood/VAB - Muscles/KbMU/VMU); d/dt(Adipose) = QAD*(Arterial_Blood/VAB - Adipose/KbAD/VAD); d/dt(Skin) = QSK*(Arterial_Blood/VAB - Skin/KbSK/VSK); d/dt(Spleen) = QSP*(Arterial_Blood/VAB - Spleen/KbSP/VSP); d/dt(Pancreas) = QPA*(Arterial_Blood/VAB - Pancreas/KbPA/VPA); d/dt(Liver) = QHA*Arterial_Blood/VAB + QSP*Spleen/KbSP/VSP + QPA*Pancreas/KbPA/VPA + QST*Stomach/KbST/VST + QGU*Gut/KbGU/VGU - CLint*fub*Liver/KbLI/VLI - QLI*Liver/KbLI/VLI; d/dt(Stomach) = QST*(Arterial_Blood/VAB - Stomach/KbST/VST); d/dt(Gut) = QGU*(Arterial_Blood/VAB - Gut/KbGU/VGU); d/dt(Bones) = QBO*(Arterial_Blood/VAB - Bones/KbBO/VBO); d/dt(Kidneys) = QKI*(Arterial_Blood/VAB - Kidneys/KbKI/VKI); d/dt(Arterial_Blood) = QLU*(Lungs/KbLU/VLU - Arterial_Blood/VAB); d/dt(Venous_Blood) = QHT*Heart/KbHT/VHT + QBR*Brain/KbBR/VBR + QMU*Muscles/KbMU/VMU + QAD*Adipose/KbAD/VAD + QSK*Skin/KbSK/VSK + QLI*Liver/KbLI/VLI + QBO*Bones/KbBO/VBO + QKI*Kidneys/KbKI/VKI + QRB*Rest_of_Body/KbRB/VRB - QLU*Venous_Blood/VVB; d/dt(Rest_of_Body) = QRB*(Arterial_Blood/VAB - Rest_of_Body/KbRB/VRB);})
If you look at the summary, you can see where RxODE assigned the compartment number(s)
summary(pbpk)
#> RxODE 1.0.5 model named rx_74372d99e4c72628e9dee8939b90cb49 model (✔ ready). #> DLL: /home/matt/.cache/R/RxODE/rx_74372d99e4c72628e9dee8939b90cb49__.rxd/rx_74372d99e4c72628e9dee8939b90cb49_.so#> NULL#> #> Calculated Variables:#> [1] "KbBR" "KbMU" "KbAD" "CLint" "KbBO" "KbRB" "CO" "QHT" "QBR" #> [10] "QMU" "QAD" "QSK" "QSP" "QPA" "QLI" "QST" "QGU" "QHA" #> [19] "QBO" "QKI" "QRB" "QLU" "VLU" "VHT" "VBR" "VMU" "VAD" #> [28] "VSK" "VSP" "VPA" "VLI" "VST" "VGU" "VBO" "VKI" "VAB" #> [37] "VVB" "VRB" "fub" "KbLU" "KbHT" "KbSK" "KbSP" "KbPA" "KbLI" #> [46] "KbST" "KbGU" "KbKI" "S15" "C15" #> ▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂ RxODE Model Syntax ▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂#> RxODE({#> KbBR = exp(lKbBR)#> KbMU = exp(lKbMU)#> KbAD = exp(lKbAD)#> CLint = exp(lCLint + eta.LClint)#> KbBO = exp(lKbBO)#> KbRB = exp(lKbRB)#> CO = (187 * WT^0.81) * 60/1000#> QHT = 4 * CO/100#> QBR = 12 * CO/100#> QMU = 17 * CO/100#> QAD = 5 * CO/100#> QSK = 5 * CO/100#> QSP = 3 * CO/100#> QPA = 1 * CO/100#> QLI = 25.5 * CO/100#> QST = 1 * CO/100#> QGU = 14 * CO/100#> QHA = QLI - (QSP + QPA + QST + QGU)#> QBO = 5 * CO/100#> QKI = 19 * CO/100#> QRB = CO - (QHT + QBR + QMU + QAD + QSK + QLI + QBO + QKI)#> QLU = QHT + QBR + QMU + QAD + QSK + QLI + QBO + QKI + QRB#> VLU = (0.76 * WT/100)/1.051#> VHT = (0.47 * WT/100)/1.03#> VBR = (2 * WT/100)/1.036#> VMU = (40 * WT/100)/1.041#> VAD = (21.42 * WT/100)/0.916#> VSK = (3.71 * WT/100)/1.116#> VSP = (0.26 * WT/100)/1.054#> VPA = (0.14 * WT/100)/1.045#> VLI = (2.57 * WT/100)/1.04#> VST = (0.21 * WT/100)/1.05#> VGU = (1.44 * WT/100)/1.043#> VBO = (14.29 * WT/100)/1.99#> VKI = (0.44 * WT/100)/1.05#> VAB = (2.81 * WT/100)/1.04#> VVB = (5.62 * WT/100)/1.04#> VRB = (3.86 * WT/100)/1.04#> BP = 0.61#> fup = 0.028#> fub = fup/BP#> KbLU = exp(0.8334)#> KbHT = exp(1.1205)#> KbSK = exp(-0.5238)#> KbSP = exp(0.3224)#> KbPA = exp(0.3224)#> KbLI = exp(1.7604)#> KbST = exp(0.3224)#> KbGU = exp(1.2026)#> KbKI = exp(1.3171)#> S15 = VVB * BP/1000#> C15 = Venous_Blood/S15#> d/dt(Lungs) = QLU * (Venous_Blood/VVB - Lungs/KbLU/VLU)#> d/dt(Heart) = QHT * (Arterial_Blood/VAB - Heart/KbHT/VHT)#> d/dt(Brain) = QBR * (Arterial_Blood/VAB - Brain/KbBR/VBR)#> d/dt(Muscles) = QMU * (Arterial_Blood/VAB - Muscles/KbMU/VMU)#> d/dt(Adipose) = QAD * (Arterial_Blood/VAB - Adipose/KbAD/VAD)#> d/dt(Skin) = QSK * (Arterial_Blood/VAB - Skin/KbSK/VSK)#> d/dt(Spleen) = QSP * (Arterial_Blood/VAB - Spleen/KbSP/VSP)#> d/dt(Pancreas) = QPA * (Arterial_Blood/VAB - Pancreas/KbPA/VPA)#> d/dt(Liver) = QHA * Arterial_Blood/VAB + QSP * Spleen/KbSP/VSP + #> QPA * Pancreas/KbPA/VPA + QST * Stomach/KbST/VST + QGU * #> Gut/KbGU/VGU - CLint * fub * Liver/KbLI/VLI - QLI * Liver/KbLI/VLI#> d/dt(Stomach) = QST * (Arterial_Blood/VAB - Stomach/KbST/VST)#> d/dt(Gut) = QGU * (Arterial_Blood/VAB - Gut/KbGU/VGU)#> d/dt(Bones) = QBO * (Arterial_Blood/VAB - Bones/KbBO/VBO)#> d/dt(Kidneys) = QKI * (Arterial_Blood/VAB - Kidneys/KbKI/VKI)#> d/dt(Arterial_Blood) = QLU * (Lungs/KbLU/VLU - Arterial_Blood/VAB)#> d/dt(Venous_Blood) = QHT * Heart/KbHT/VHT + QBR * Brain/KbBR/VBR + #> QMU * Muscles/KbMU/VMU + QAD * Adipose/KbAD/VAD + QSK * #> Skin/KbSK/VSK + QLI * Liver/KbLI/VLI + QBO * Bones/KbBO/VBO + #> QKI * Kidneys/KbKI/VKI + QRB * Rest_of_Body/KbRB/VRB - #> QLU * Venous_Blood/VVB#> d/dt(Rest_of_Body) = QRB * (Arterial_Blood/VAB - Rest_of_Body/KbRB/VRB)#> }) #> ▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂
In this case, Venous_Blood
is assigned to compartment 15
.Figuring this out can be inconvenient and also lead to re-numberingcompartment in simulation or estimation datasets. While it is easy andprobably clearer to specify the compartment byname, other tools only support compartmentnumbers. Therefore, having a way to number compartment easily canlead to less data modification between multiple tools.
6.4.2 Changing compartments by pre-declaring with cmt()
To add the compartments to the RxODE model in the order you desire yousimply need to pre-declare the compartments with cmt
. For examplespecifying is Venous_Blood
and Skin
to be the 1st and 2ndcompartments, respectively, is simple:
pbpk2 <- RxODE({ ## Now this is the first compartment, ie cmt=1 cmt(Venous_Blood) ## Skin may be a compartment you wish to dose to as well, ## so it is now cmt=2 cmt(Skin) KbBR = exp(lKbBR) KbMU = exp(lKbMU) KbAD = exp(lKbAD) CLint= exp(lCLint + eta.LClint) KbBO = exp(lKbBO) KbRB = exp(lKbRB) ## Regional blood flows # Cardiac output (L/h) from White et al (1968)m CO = (187.00*WT^0.81)*60/1000; QHT = 4.0 *CO/100; QBR = 12.0*CO/100; QMU = 17.0*CO/100; QAD = 5.0 *CO/100; QSK = 5.0 *CO/100; QSP = 3.0 *CO/100; QPA = 1.0 *CO/100; QLI = 25.5*CO/100; QST = 1.0 *CO/100; QGU = 14.0*CO/100; QHA = QLI - (QSP + QPA + QST + QGU); # Hepatic artery blood flow QBO = 5.0 *CO/100; QKI = 19.0*CO/100; QRB = CO - (QHT + QBR + QMU + QAD + QSK + QLI + QBO + QKI); QLU = QHT + QBR + QMU + QAD + QSK + QLI + QBO + QKI + QRB; ## Organs' volumes = organs' weights / organs' density VLU = (0.76 *WT/100)/1.051; VHT = (0.47 *WT/100)/1.030; VBR = (2.00 *WT/100)/1.036; VMU = (40.00*WT/100)/1.041; VAD = (21.42*WT/100)/0.916; VSK = (3.71 *WT/100)/1.116; VSP = (0.26 *WT/100)/1.054; VPA = (0.14 *WT/100)/1.045; VLI = (2.57 *WT/100)/1.040; VST = (0.21 *WT/100)/1.050; VGU = (1.44 *WT/100)/1.043; VBO = (14.29*WT/100)/1.990; VKI = (0.44 *WT/100)/1.050; VAB = (2.81 *WT/100)/1.040; VVB = (5.62 *WT/100)/1.040; VRB = (3.86 *WT/100)/1.040; ## Fixed parameters BP = 0.61; # Blood:plasma partition coefficient fup = 0.028; # Fraction unbound in plasma fub = fup/BP; # Fraction unbound in blood KbLU = exp(0.8334); KbHT = exp(1.1205); KbSK = exp(-.5238); KbSP = exp(0.3224); KbPA = exp(0.3224); KbLI = exp(1.7604); KbST = exp(0.3224); KbGU = exp(1.2026); KbKI = exp(1.3171); ##----------------------------------------- S15 = VVB*BP/1000; C15 = Venous_Blood/S15 ##----------------------------------------- d/dt(Lungs) = QLU*(Venous_Blood/VVB - Lungs/KbLU/VLU); d/dt(Heart) = QHT*(Arterial_Blood/VAB - Heart/KbHT/VHT); d/dt(Brain) = QBR*(Arterial_Blood/VAB - Brain/KbBR/VBR); d/dt(Muscles) = QMU*(Arterial_Blood/VAB - Muscles/KbMU/VMU); d/dt(Adipose) = QAD*(Arterial_Blood/VAB - Adipose/KbAD/VAD); d/dt(Skin) = QSK*(Arterial_Blood/VAB - Skin/KbSK/VSK); d/dt(Spleen) = QSP*(Arterial_Blood/VAB - Spleen/KbSP/VSP); d/dt(Pancreas) = QPA*(Arterial_Blood/VAB - Pancreas/KbPA/VPA); d/dt(Liver) = QHA*Arterial_Blood/VAB + QSP*Spleen/KbSP/VSP + QPA*Pancreas/KbPA/VPA + QST*Stomach/KbST/VST + QGU*Gut/KbGU/VGU - CLint*fub*Liver/KbLI/VLI - QLI*Liver/KbLI/VLI; d/dt(Stomach) = QST*(Arterial_Blood/VAB - Stomach/KbST/VST); d/dt(Gut) = QGU*(Arterial_Blood/VAB - Gut/KbGU/VGU); d/dt(Bones) = QBO*(Arterial_Blood/VAB - Bones/KbBO/VBO); d/dt(Kidneys) = QKI*(Arterial_Blood/VAB - Kidneys/KbKI/VKI); d/dt(Arterial_Blood) = QLU*(Lungs/KbLU/VLU - Arterial_Blood/VAB); d/dt(Venous_Blood) = QHT*Heart/KbHT/VHT + QBR*Brain/KbBR/VBR + QMU*Muscles/KbMU/VMU + QAD*Adipose/KbAD/VAD + QSK*Skin/KbSK/VSK + QLI*Liver/KbLI/VLI + QBO*Bones/KbBO/VBO + QKI*Kidneys/KbKI/VKI + QRB*Rest_of_Body/KbRB/VRB - QLU*Venous_Blood/VVB; d/dt(Rest_of_Body) = QRB*(Arterial_Blood/VAB - Rest_of_Body/KbRB/VRB);})
You can see this change in the simple printout
pbpk2
#> RxODE 1.0.5 model named rx_a65bdb529b0485f601cec6187b5faaf5 model (✔ ready). #> x$state: Venous_Blood, Skin, Lungs, Heart, Brain, Muscles, Adipose, Spleen, Pancreas, Liver, Stomach, Gut, Bones, Kidneys, Arterial_Blood, Rest_of_Body#> x$params: lKbBR, lKbMU, lKbAD, lCLint, eta.LClint, lKbBO, lKbRB, WT, BP, fup#> x$lhs: KbBR, KbMU, KbAD, CLint, KbBO, KbRB, CO, QHT, QBR, QMU, QAD, QSK, QSP, QPA, QLI, QST, QGU, QHA, QBO, QKI, QRB, QLU, VLU, VHT, VBR, VMU, VAD, VSK, VSP, VPA, VLI, VST, VGU, VBO, VKI, VAB, VVB, VRB, fub, KbLU, KbHT, KbSK, KbSP, KbPA, KbLI, KbST, KbGU, KbKI, S15, C15
The first two compartments are Venous_Blood
followed by Skin
.
6.4.3 Appending compartments to the model with cmt()
You can also append “compartments” to the model. Because of the ODEsolving internals, you cannot add fake compartments to the model untilafter all the differential equations are defined.
For example this is legal:
ode.1c.ka <- RxODE({ C2 = center/V; d / dt(depot) = -KA * depot d/dt(center) = KA * depot - CL*C2 cmt(eff);})print(ode.1c.ka)
#> RxODE 1.0.5 model named rx_47c1eb3facce5268a288e5652999299e model (✔ ready). #> $state: depot, center#> $stateExtra: eff#> $params: V, KA, CL#> $lhs: C2
But compartments defined before all the differential equations is not supported; So the model below:
ode.1c.ka <- RxODE({ cmt(eff); C2 = center/V; d / dt(depot) = -KA * depot d/dt(center) = KA * depot - CL*C2})
will give an error:
Error in rxModelVars_(obj) : Evaluation error: Compartment 'eff' needs differential equations defined.