rxode2 ODE solving syntax

2022-05-17

Introduction

This briefly describes the syntax used to define models that rxode2 will translate into R-callable compiled code. It also describes the communication of variables between R and the rxode2 modeling specification.

Below is a commented example to quickly show the capabilities of rxode2 syntax.

Example

   # An rxode2 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;

Syntax

An rxode2 model specification consists of one or more statements optionally 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/else if/else, while loops (can be exited by break), special statements, or printing statements (for debugging/testing)

Assignment statements can be:

Note that assignment can be done by =, <- or ~.

When assigning with the ~ operator, the simple assignments and time-derivative assignments will not be output.

Special statements can be:

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.

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).

You may also access the R’s functions in the R math libraries, like lgammafn for the log gamma function.

The rxode2 syntax is case-sensitive, i.e., ABC is different than abc, Abc, ABc, etc.

Identifiers

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:

Currently, the rxode2 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 either passed in the params argument of the integrator function rxSolve() or be in the supplied event data-set.

There are certain variable names that are in the rxode2 event tables. To avoid confusion, the following event table-related items cannot be assigned, or used as a state but can be accessed in the rxode2 code:

However the following variables are cannot be used in a model specification:

Sometimes rxode2 generates variables that are fed back to rxode2. Similarly, nlmixr generates some variables that are used in nlmixr estimation and simulation. These variables start with the either the rx or nlmixr prefixes. To avoid any problems, it is suggested to not use these variables starting with either the rx or nlmixr prefixes.

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 a standard 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 are slower than numeric expressions. Unlike R, as.numeric or as.integer for these logical statements is not only not needed, but will cause an syntax error if you try to use the function.

Interface and data handling between R and the generated C code

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 rxode2 solve() method:

m1 <- rxode2(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)

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).

Supported functions

All the supported functions in rxode2 can be seen with the rxSupportedFuns().

A brief description of the built-in functions are in the following table:

#> rxode2 2.0.7 using 4 threads (see ?getRxThreads)

Note that lag(cmt) = is equivalent to alag(cmt) = and not the same as = lag(wt)

Reserved keywords

There are a few reserved keywords in a rxode2 model. They are in the following table:

Bugs and/or deficiencies

Note

The ODE specification mini-language is parsed with the help of the open source tool , Plevyak (2015).