Last modified date:6/26/19
Legal Notice | Contact Certara
© 2019 Certara USA, Inc. All rights reserved.
Custom text expressions, equations, and PML code can be included in Phoenix models by using code blocks in the graphical model editor, or by entering model code in the Model panel when using the Phoenix model in text model mode. All custom code is referred to as user code.
Many model blocks allow users to add custom text expressions and statements to the drug model. Note that a distinction is made between an expression, which is a numeric value expressed in algebraic terms, and a statement, which is a complete equation or action and can include an assignment operator, “=”.
Expression blocks
The Expression block represents one variable, whose value is set by a text expression inside the block.
Use a procedure block to enter assignment statements and differential equations, and to create new structural parameters. These statements are inserted in the model, alongside automatically generated statements. For example, users can define new structural parameters Q and R, and then enter this code written in the block:
deriv(B=-B*Q)
D=B/R
It is important not to write code that depends on time “t” or other continuously changing variables to equal exact values, such as:
x=((t==4)?xxx:yyy)
because this code is executed very frequently, including every time a derivative evaluation is performed. Time “t” takes on many values, along with other continuously changing variables, but cannot be relied on to equal any particular value, or even to advance monotonically. However, covariates, if not interpolated, use the specific values that they are set to by the input data.
Also, it is not a good idea to write code containing discontinuities, such as
x=((t>=4)?xxx:yyy)
because x discontinuously changes from xxx to yyy at time 4. Assuming x enters the model in some way, it can either cause the ODE solver or the modeling engine to be faced with a discontinuity. If the ODE solver encounters a discontinuity, it responds by adjusting the step size to as small a value as possible in order to minimize error, which can greatly slow model performance. If the modeling engine encounters a discontinuity, it responds by trying (and failing) to make a continuous model in the region of the discontinuity, resulting in a troublesome fit and possible lack of standard errors. Use the sequence statement in the PML to schedule events when discrete actions can be taken.
Syntax for text expressions and statements
Case sensitivity: Code blocks are case sensitive, as is every other part of the drug model. For example, the following two variable names are treated as unique: variable_x and Variable_X
Comments: Enter descriptive comments and notes after the pound symbol, “#”, in any statement or expression. Text to the right of the pound symbol, to the end of a line, is treated as a comment.
Example:
p=exp(a)/(1+exp(a)) # uses the inverse logit to compute the probability, p
Identifiers: Variable names for existing drug model variables, such as block inputs and outputs and covariates, can be referenced in expressions and statements.
Discrete variable values in user code: Discrete covariate values can be referred to using their number representation. Each value is represented by a whole number, starting with 0 (zero) for the first value listed in the Covar. Type tab, which is located in the Parameters tab.
Example expression using a discrete covariate:
The values of a covariate baseline_pain are low, moderate, and severe, in that order. They are represented internally by the Phoenix as 0, 1, and 2.
An Expression block called “pain_effect” might contain a conditional expression as follows:
Baseline_pain > 0 ? -1:0
This expression reads: if baseline pain is greater than zero (the index for the first discrete value, low), the expression value is negative one; else, zero.
The equality operator (==) can also be used to build expressions from discrete covariates or model variables such as:
CL=tvCL+(renal_necrosis==1)*renNC
An expression represents a single numerical quantity in algebraic terms. It does not contain an assignment, or “=”.
An expression may include any combination of the following:
Numbers
Optional decimal point: 999 9.99 .999 999. 0.999
Followed by optional exponent: 1e999 99e-999
Limits: IEEE double precision (about 13 decimal places)
Identifiers (variable names, function names)
Identifiers used within expressions must be valid model variables or function names.
Unary minus (negative sign)
Syntax: -expression
Example: -exp(-ETA1), where ETA1 is a variable in the model
Factors
Syntax: expression*expression
or expression/expression
Sums
Syntax: expression+expression
or expression-expression
Exponential terms
Syntax: expression^expression
or expression**expression
Example: Emax*C^gamma/(EC50^gamma+C^gamma)
where Emax, C, EC50 and gamma are variables in the model.
Numeric Comparisons
The value of an expression using a comparison is one if the comparison is true, zero if false. Comparison operators allowed within expressions are:
- greater than or equal to: >=
- less than or equal to: <=
- not equal to: !=
- is equal to: ==
- greater than: >
- less than: <
Syntax: expression1 == expression2
Example: probability_pain_relief >= chance
Choice operator
Syntax: expression1 ? expression2:expression3
Example (conditional expression): bodyweight < 300 ? 0:1
If bodyweight is less than 300, the value is zero, else the value is one.
Statements can follow each other on a single line or be set on different lines.
statement statement …
The most common type of statement is an assignment, for example:
x=5+y;
This statement assigns the variable x the value 5+y. Note that x and y must be valid drug model variables. The semicolon character (;) separating statements is optional.
Differential equations can be created only by using deriv statements inside a Procedure block. Note that the variable t, the time variable, can be used inside of a deriv statement. t represents subject time, which is the elapsed time since the first event experienced by the subject.
For available logical operators and functions that can be used in statements, see “Supported Operators”, “Supported Math Functions”, and “Supported Special Functions”.
The NLME engine used by the Phoenix Model Object can be used for analyzing pooled data. This approach fits one set of model parameters to all individuals in a dataset. There are some requirements that must be met to properly configure a pooled model:
Do not map any profile data for individuals. Using profile data causes multiple models to be estimated.
If the model includes differential equations, such as the “deriv” statements in the Phoenix Modeling Language:
•Make sure that the data are sorted by individual then by time, so that all the observations for any individual are in consecutive and ascending time order. Then clear the Sort Input? checkbox on the Run Options tab.
•Select the Reset? checkbox in the Input Options tab and include a column with an indicator for the initial time.
•Dosing information must be placed in the observation data. The Dosing Panel does not function properly for Pooled data.
Last modified date:6/26/19
Legal Notice | Contact Certara
© 2019 Certara USA, Inc. All rights reserved.