---
title: "RxODE Modeling Syntax"
author: "Melissa Hallow and Wenping Wang"
date: "`r Sys.Date()`"
output: rmarkdown::html_document
vignette: >
  %\VignetteIndexEntry{RxODE Modeling Syntax}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
library(knitr)
```

# `RxODE` Modeling Syntax

## Introduction

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

## 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;
```

## Syntax

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

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

## 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 `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.

## Bugs and/or deficiencies

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

