Skip to contents

Insight on the structural model

Source: vignettes/v02_structural_model.Rmd
v02_structural_model.Rmd

This vignette attends to give a brief insight on the different statements that may be used to build a structural model, compatible with CAMPSIS.
The number of model statement types proposed in campsismod is rather limited, with the underlying idea of keeping our model simple and the translation to RxODE and mrgsolve as clean as possible. However, in a near future, new types of model statements will likely be supported.

Prerequisite

The examples below require the package campismod.

Equation

Equations are described by 3 fields:

  • lhs: the left-hand side string, which corresponds to the variable name
  • rhs: the right-hand side string, which corresponds to the formula
  • comment: a possible comment

Example:

equation <- Equation("KA", "THETA_KA * exp(ETA_KA)", comment="This is my KA parameter")

The equivalent text form is:

equation
## KA=THETA_KA * exp(ETA_KA) # This is my KA parameter

Ordinary differential equation (ODE)

Similarly, Ordinary differential equations (ODE’s) are described by 3 fields as well:

  • lhs: the left-hand side string, which corresponds to the variable name, must start with ‘A_’
  • rhs: the right-hand side string, which corresponds to the derivative formula
  • comment: a possible comment

Example:

ode <- Ode("A_DEPOT", "-KA * A_DEPOT", comment="This is my depot compartment")

The equivalent text form is:

ode
## d/dt(A_DEPOT)=-KA * A_DEPOT # This is my depot compartment

Line break

Line breaks can be added to a model to add clear separations between blocks of equations. It does not have any field.

Example:

linebreak <- LineBreak()

The equivalent text form is obviously a separation line.

Comment

Comments can be specified at any place in the model. They have a unique field:

  • x: the comment you’d like to add

Example:

comment <- Comment("This is my first comment")

The equivalent text form is:

comment
## # This is my first comment

If-statement

If-statements allow a variable to take different values according to different specified conditions.

  • condition: the given condition
  • equation: an equation (see definition above)
  • comment: a possible comment

Example:

ifStatement <- IfStatement("COV==1", Equation("COV_EFFECT", "0.2"), comment="This is an if statement")

The equivalent text form is:

ifStatement
## if (COV==1) COV_EFFECT=0.2 # This is an if statement

A common use of the if-statements is to add covariate effects into the model. Here is an example:

main <- MainRecord()
main <- main %>%
  add(Equation("COV_EFFECT", "0")) %>% # Initialisation
  add(IfStatement("COV==1", Equation("COV_EFFECT", "0.1"))) %>%  # Covariate value is 1 in dataset
  add(IfStatement("COV==2", Equation("COV_EFFECT", "0.2"))) %>%  # Covariate value is 2 in dataset
  add(IfStatement("COV==3", Equation("COV_EFFECT", "0.3")))      # Covariate value is 3 in dataset

The equivalent text would then be:

main
## [MAIN]
## COV_EFFECT=0
## if (COV==1) COV_EFFECT=0.1
## if (COV==2) COV_EFFECT=0.2
## if (COV==3) COV_EFFECT=0.3

Please note that mrgsolve require all extra variables (like COV_EFFECT in the previous example) to be initialised to a predefined value, which makes a lot of sense in general.

Additional remarks

Package campsismod does not check the equations from a grammar point of view. This work is delegated to the simulation engine (RxODE or mrgsolve) and C compiler.

In general, respecting the few rules listed below will give you a successful compatibility with both engines:

  • All formula’s and if-statement conditions must be written in C code
  • Functions included in the Math library of C are compatible (e.g. cos, sin, etc)
  • Use the pow function for writing exponents (^ is accepted in RxODE, not in mrgsolve)
  • Scientific notation for numbers is accepted (e.g. 2.51e-01)
  • Initialise all extra variables (see example in the section above)