new_ode_model is the function that creates a new ODE model that can be used in the
sim_ode() command. It defines the ODE system and sets some attributes for the model. The model can be specified in three different ways:
model: a string that references a model from the library included in
PKPDsim. Examples in the current library are e.g.
pk_2cmt_iv. To show the available models, run
new_ode_model()without any arguments.
code: using code specyfing derivatives for ODE specified in pseudo-R code
file: similar to
code, but reads the code from a file
Model from library
For example, a 1-compartment oral PK model can be obtained using:
pk1 <- new_ode_model(model = "pk_1cmt_oral")
new_ode_model() function without arguments to see the currently available models:
> new_ode_model() Either a model name (from the PKPDsim library), ODE code, an R function, or a file containing code for the ODE system have to be supplied to this function. The following models are available: pk_1cmt_iv pk_1cmt_iv_auc pk_1cmt_iv_mm pk_2cmt_iv pk_2cmt_iv_auc pk_1cmt_oral
Custom model from code
The custom model needs to be specified as a string or text block:
pk1 <- new_ode_model(code = " dAdt = -KA * A dAdt = +KA * A -(CL/V) * A ")
The input code should adhere to the follow rules:
- the derivaties in the ODE system are defined using
- array indices for the derivatives and compartments are indicated with
[ ]and start at 1.
- equations are defined using
- some expections apply, e.g. power functions (see below).
The input code is translated into a C++ function. You can check that the model compiled correctly by typing the model name on the R command line, which prints the model information:
> pk1 ODE definition: double KEL = CL/V; dAdt = -KA * A + rate; dAdt = +KA * A -KEL * A; ; Required parameters: CL, V, KA Number of compartments: 2 Observation compartment: 1 Dependent variable scaling: 1
If you want even more detailed information, you can also print the actual C++ function that is used under-the-hood by specifying the
cpp_show_code=TRUE argument to the
More custom model options
You can introduce new variables in your code, but you will have to define them using
declare_variables argument too:
pk1 <- new_ode_model(code = " KEL = CL/V dAdt = -KA * A dAdt = +KA * A -KEL * A ", declare_variables = c("KEL"))
Also, when you want to use covariates in your ODE system (more info on how to define covariates is in the Covariates section), you will have to define them, both in the code and in the function call:
pk1 <- new_ode_model(code = " CLi = WT/70 KEL = CLi/V dAdt = -KA * A dAdt = +KA * A -(CL*(WT/70)/V) * A ", declare_variables = c("KEL", "CLi"), covariates = c("WT"))
One exception to the input code syntax is the definition of power functions.
PKPDsim does not translate those from the pseudo-R code to valid C++ syntax automatically. C/C++ does not use the
^ to indicate power functions but uses the
pow(value, base) function instead, so e.g. an allometric model should be written as:
pk1 <- new_ode_model(code = " CLi = CL * pow((WT/70), 0.75) dAdt = -KA * A dAdt = +KA * A -(CLi/V) * A ", declare_variables = c("CLi"))
Dosing / bioavailability
The default dosing compartment and bioavailability can be specified using the
dose argument. By default, the dose will go into compartment
1, with a bioavailability of
bioav element in the list can be either a number or a character string referring a parameter.
pk1 <- new_ode_model(code = " dAdt = -KA * A dAdt = +KA * A -(CL/V) * A ", dose = list(cmt = 1, bioav = "F1"))
For dosing based on mg/kg, at currently there is no solution for that using
new_regimen(), although that might change in the future. The way to implement this at the moment is by scaling the dose by the "weight" covariate using the bioavailability:
mod <- new_ode_model(code = " dAdt = -(CL/V)*A; ", dose = list(cmt = 1, bioav = "WT"), obs = list(cmt = 1, scale = "V"), covariates = covs)
The observation compartment can be set by specifying a list to the
obs argument, with the elements
pk1 <- new_ode_model(code = " dAdt = -KA * A dAdt = +KA * A -(CL/V) * A ", obs = list(cmt = 2, scale = "V"))
scale can be either a parameter or a number, the
cmt can only be a number.
Note that the variables specified inside the differential equation block are not available as scaling parameters. E.g. for allometry you will have to redefine the scaled volume as follows:
pk1 <- new_ode_model(code = " Vi = V * (WT/70) dAdt = -KA * A dAdt = +KA * A -(CL/Vi) * A ", obs = list(cmt = 2, scale = "V * (WT/70)"))
Custom model from file
The same syntax as explained above applies, but using the
file= argument the input code is read from the specified file. This is just a convenience function, i.e. it allows you to modularize your code, and separate models and R code.
pk1 <- new_ode_model( file = "pk_1cmt_oral_nonlin_v1.txt", declare_variables = c("KEL", "CLi") )