Mlxtran User Guide

1.Mlxtran, a human readable language for model description

Version 2016R1

This documentation is for Mlxtran for the Monolix Suite 2016R1

©Lixoft

MlxTran

MlxTran is a declarative, human-readable language for the description of the structural and statistical elements of non-linear mixed effects model typically found in pharmacometrics modelling and simulation. MlxTran is used for data exploration with Datxplore, for model exploration with Mlxplore, for parameter estimation with Monolix and for simulation with Simulx.

Mixed effects modelling with MlxTran

The main output of every MlxTran model are the longitudinal model observations y. The observations are derived from the model prediction and the observational model (error model). The model inputs are a set of parameters (fixed effects). In the context of pharmacometric modelling the model parameters can have between patient variability and can depend on covariates.

MlxTran model types

Mlxtran can be used for the following type of models:

  • Continuous data models
  • Categorical data models
  • Count data models and
  • Time-to-event (or survival) data models.

Any combination between the different type of models is possible as well.

MlxTran model structure

Mlxtran can be used to represent models for parameter estimation with Monolix or for simulation with Simulx or Mlxplore. Because parameter estimation and simulation are different tasks, models will typically be different in some of the sections they contain. In Monolix the covariate and statistical models for the individual parameters is provided through the user interface. The design of the dosing is provided through the data set. For this reason a model for Monolix only requires the [LONGITUDINAL] section of <MODEL> as illustrated in the figure below showing the most general Mlxtran models for Monolix, Simulx and Mlxplore. Different bracket styles designate different hierarchical elements of the model.

MlxtranScheme

2.[LONGITUDINAL]

Description

In the [LONGITUDINAL] sections the structural model and the observation model (error model) are described.

Scope

The [LONGITUDINAL] section is mandatory for all Mlxtran models for Monolix, Mlxplore and Simulx.

Inputs

The input = { } list of the [LONGITUDINAL] section declares the variables that were defined outside of the [LONGITUDINAL] section and enables them. These parameters are obtained from either the calling software itself (e.g. Monolix), or the [INDIVIDUAL] section. For Monolix all parameters in the input = { } list define the parameters that are estimated or used as regressor variables. The following example shows how the inputs are declared for 4 parameters.

[LONGITUDINAL]
input = {V1, V2, Cl, reg_var1}
reg_var1 = {use = regressor}

Outputs

The output and table lists in the OUTPUT: block declare variables whose values are exported for the various tasks. The keyword output declares the main variables to output, whereas table declares the variables to record in tables.

OUTPUT:
output = {y1, y2, y3}
table = {Ap, Rin}

For Monolix, the output list identifies the predictions or the modeled outputs that are fitted against the data set observations. In case of several outputs, the order of the model predictions in the output list must match the alphabetical order of the observation identifiers used in the column-type YTYPE of the data set.
The parameters or variables listed in the table list are outputted in the files predictions.txt, finegrid.txt and fulltimes.txt, that appear in the result folder of Monolix when respectively the tables “Observation times”, “Fine-grid times” and “All times” are selected in the “Outputs to save” window of Monolix.

Usage

Along with the input= and the OUTPUT: block detailed above, [LONGITUDINAL] section can contain three different blocks. The PK: block permits to define PK models using macros, and to link the administration information of the data set with the model. The EQUATION: block is for mathematical equations including ODEs, DDEs and macros. The DEFINITION: block is used to define a random variable and its probability distribution. The OUTPUT: block contains the [LONGITUDINAL] section outputs. In the following, the different possibilities of the [LONGITUDINAL] section are explained in detail:

Observation model description using DEFINITION:

Observation models for continuous data
Observation models for discrete data

Rules and differences between software

Library of models and macros

The function pkmodel permits to define common PK models in a very concise way. The purpose of this macro is to simplify the modeling of classical pharmacokinetics. It is complementary to models that are not in the library, and/or if the user want to combined it with other models.
The PK model is inferred from the provided set of named arguments. Most of the arguments are optional, and the pkmodel function enables several parametrizations, to select different models of absorption, elimination, etc. With the pkmodel function, the most common PK models are available. The concentration within the central compartment is the main output of the function. If an effect compartment is defined, its concentration defines the second output.

In addition to the macros, Lixoft is providing model library to simplify the use of the software by decreasing the necessity of coding.

PK/PD model library

These libraries provide all the classical pharmacokinetic and pharmacodynamic models. The pharmacometric models allows to model several types of administrations (IV bolus, infusion, zero and first order absorption), any number of compartment (between 1 and 3), several elimination process (linear and Michaelis-Menten), and to manage lag-time. In addition, the some usual pharmacodynamical models are proposed.
To see the compete description, see here.

Target-mediated drug disposition (TMDD) model library

An introduction to the TMDD concepts, the description of the library’s content, a detailed explanation of the hierarchy of TMDD model approximations, and guidelines to choose an appropriate model is proposed here along with the model library.
The library contains a large number of TMDD models corresponding to different approximations, different administration routes, different parameterizations, and different outputs. In total 608 model files are available.

2.1.Input definition

The [LONGITUDINAL] section starts with the declaration of its inputs. These parameters can come from:

  • the calling software: Monolix, Simulx or Mlxplore
  • the outputs of the section [INDIVIDUAL],
  • the parameters defined in the section <PARAMETER> .

For Monolix all parameters in the input = { } list define the parameters that are estimated or used as regressor variables.  Notice that outputs from the [COVARIATE] section can not be used as inputs for the [LONGITUDINAL] section.

For example, for a model where a function f depends on a vector of input parameters \phi=(ka, V, k) and a fixed constant D is defined:

f(t) = \frac{D, k_a}{V(k_{a} - k)}(e^{-kt} - e^{-k_{a}t})

The input is defined in the following

DESCRIPTION: Model description with an analytical expression 
[LONGITUDINAL]
input = {ka, V, k}

EQUATION:
D = 100
f = D*ka/(V*(ka-k))*(exp(-k*t) - exp(-ka*t))

Notice that, in this example, the parameter D is a fixed constant of the model and is thus not defined as an input.

2.2.Basic syntax for equations

Introduction

Equations are implemented in the block EQUATION: of the [LONGITUDINAL] section. In this section parametric functions of the form  f(t;\phi) where \phi is a vector of structural parameters can be defined.

Example

We consider in this example a model where a function f depending on a vector of parameters \phi=(ka, V, k) is defined as:

f(t) = \frac{D, k_a}{V(k_{a} - k)}(e^{-kt} - e^{-k_{a}t})

where D=100 is given.This example corresponds to the analytical solution of a one compartmental model with a constant rate absorption, a linear elimination and a dose at time 0.

DESCRIPTION: Model description with an analytical expression 
[LONGITUDINAL]
input = {ka, V, k}

EQUATION:
D = 100
f = D*ka/(V*(ka-k))*(exp(-k*t) - exp(-ka*t))

The simulation is computed with Mlxplore using (ka=1, V=10, k=0.05). The result is shown in the figure below. One can see the variation of f w.r.t. time.

mlxplore_analytical

Rules and Best Practices 

  • t is a reserved keyword and represents the time. t must not be defined in the model and the name t can not be used in the model for any other parameter or variable. All Mlxtran reserved keywords are listed here.
  • Mlxplore only: make sure all your parameters are defined in the input = { } list so they become available in the user interface for the exploration of your model. By default, parameters are initialized at 0 and this value can be updated on the interface.

2.3.Modelling ODEs

Introduction
Ordinary differential equations (ODEs) can be implemented in the EQUATION: block of the [LONGITUDINAL] section. The ODEs describe a dynamical system and are defined by a set of equations for the derivative of each variable, the initial conditions, the starting time and the parameters.

Derivatives
The keyword ddt_ in front of a variable name, as ddt_x and ddt_y, defines the derivative of the ODE system. The variable names denote the components of the solution. These variables are defined at the whole [LONGITUDINAL] section level through their derivatives. The derivatives themselves aren’t variables but keywords, and cannot be referenced by other equations nor be defined under a conditional statement.

Initial conditions
The keyword t0 defines the initial time t_0 of the differential equation, while the variable names with suffix _0 define the  initial conditions of the system. More precisely, in a differential equation for the variable x, x is defined at t\leq t_0 by the initial condition x_0, i.e. x(t)=x_0 and by the differential equation after t_0.

Linking administration with ODEs
Mlxtran provides the PK macro depot() that can be used to link the administration from a data set with the model. Details and examples how to use depot() for the administration are given here.

Example
We consider in this example a first order differential equation on x defined by:

\left\{\begin{array}{l} \dot{x} = -kx \\ x(t)=V,~~\textrm{for}~~t\leq10\end{array}\right.

where (V,k)=(10,.05), this ODE is typically a linear elimination process of a volume. This model is implemented in the file mlxt_ode.txt:

DESCRIPTION: Model description with a simple ODE representing a linear elimination precess of a volume
[LONGITUDINAL]
input = {V, k}

EQUATION:
t0 = 10
x_0 = V
ddt_x = -k*x

Here, the Mlxtran model define above is used with Mlxplore with the parameters (V,k)=(10,.05). The simulation result is shown in the figure below. One can see the evolution of x w.r.t. time, one can clearly see the impact of the initialization and its timing.
mlxplore_ode

Rules and Best Practices 

  • We encourage the users to define the initial conditions explicitly, although the default initial value is x_0=0.
  • When no starting time t0 is defined in the Mlxtran model for Monolix then by default t0 is selected to be equal to the first dose or the first observation, whatever comes first.
  • If t0 is defined and no differential equation is used, an error will raise.
  • Initial conditions can depend on time
  • Initial conditions can depend on an input parameter. Therefore, initial condition values can also be estimated in Monolix.
  • Only first order differential equation can be used with Mlxtran. If you want to use a differential equation of the form \frac{d^{n}x}{dt^n}=f(x,\phi), you need to transform the higher order differential equation into a first order differential equations by defining n successive differential equations as proposed in the following “Best Practices Ex. 1: Second order differential equation”.
  • The derivatives of a ODE system cannot be conditional, i.e. ddt_ cannot be used within an if statement. Instead, conditional intermediate variables for the values of the derivatives should be used as shown in “Best Practices Ex. 2: IF statement”. A conditional statement can be built by combining the keywords if, elseif,  else and end. Several elseif keywords can be chained, and the conditions are exclusive in sequence. A default value can be provided using the keyword else, but also as a simple definition preceding the conditional structure. An unspecified conditional value is null. The enclosed variables are not local variables, which means that a variable with remaining conditional definitions is still incomplete and cannot be referenced into another definition, even under the same condition.

Best Practices Ex. 1: Second order differential equation
If you want to use a second order differential equation of the type \ddot{x} +\dot{x}+x = 0, with (x(0),\dot{x}(0))=(a,b), the structural model in Mlxtran writes

[LONGITUDINAL]
input = {a, b}

EQUATION:
t0 = 0
x_0 = a
dx_0 = b
ddt_x = dx
ddt_dx = -x-dx

Best Practices Ex. 2: IF statement
If a parameter value depends on a condition, it can be written with in Mlxtran with the usual if-else-end syntax. For example, if a parameter c should be 1 if t\leq 10 and 2 otherwise, write

if t<=10
   c = 1
else
   c = 2
end

Derivatives cannot be written within an if-else-end structure. Instead, intermediate variables should be used. For example, if a derivative \frac{dx}{dt} should be 1 if t\leq 10 and 2 otherwise, write

if t<=10
   dx = 1
else
   dx = 2
end
ddt_x = dx

2.4.Delayed differential equations (DDE)

Introduction

Delayed differential equations (DDEs) can be implemented in a block EQUATION:  of the section [LONGITUDINAL]. For that, the function delay is proposed. This function allows to delay a dynamical variable by a constant time. One can also build a model with several delays. Delays in the absorption after drug administration must be implemented using the keyword Tlag in the administration macros.

Example
We consider in this example a first order delay differential equation on x defined by:

 \dot{x}(t) = k_ax(t)-kx(t-\tau)

This DDE is typically an accumulation process with a delayed linear elimination treatment. This model is implemented in the file mlxt_dde.txt:

DESCRIPTION: Model description with a delay
[LONGITUDINAL]
input = {V, ka, k, tau}

EQUATION:
t0 = 0
x_0 = V
ddt_x = ka*x-k*delay(x,tau)

The result of the simulation is performed by Mlxplore using (V=10, k=0.5, k=.25, tau=2) and is proposed on the following figure. The interesting part in this example is that the delay has an important impact on the stability of the system. This kind of systems can thus be explored by Mlxplore.

mlxplore_dde

Rules 

  • The delay function can delay a “pure” component in a dynamical equation. There are three main things to point out and we will discuss the three of them:
    • By pure, we mean that the function can not take state calculations into account. In the previous example, if we had used delay(k*x,tau) instead of k*delay(x,tau), this would have generated an error.
    • By component, we mean that the delay function can only delay variable with a dynamic behavior (defined by a derivative equation). In the previous example,using the delay function with anything else than x would lead to an error.
    • By dynamical equation, we mean that the delay function should be called directly in a ddt_ equation. For example, if we have in addition a DDE of the form \dot{y}(t)=x(t-1)-y(t), one could be tempted to implement it in Mlxtran under the following incorrect form:
      z = delay(x,1)
      ddt_y = z-y

      It should be defined directly as

      ddt_y = delay(x,1)-y

      The first implementation would lead to an error.

  • The delay must remain constant over the time.
  • It is good practice to define the initial conditions of the DDE system (t0 and initial values for  the variables). If the initial condition is not defined, then it is set to the default value 0. Notice that you can have varying initial conditions. Note also that an initialization can be performed if the values can be analytically computed. For example, we can define  x(t)=V(1+t)~~\forall t\in[-1,0], and it would be translated in Mlxtran under the form
    x_0 = V*(1+t)

2.5.Regression variables

A regression variable is a variable x that depends on time but is not defined in the model but rather is defined in the data set in the case of Monolix. In the data set the regression variable is represented by vector  x=\left(x_1, x_2, ..., x_m \right)  and a vector  \left(t_1, t_2, ..., t_m \right), where x_j=x(t_j) is the value of x at time t_j.

Note that x is only defined at time points  \left(t_1, t_2, ..., t_m \right). For the model evaluation the regression variable must be available at any time t. For this reason the value of the regression variable at any time t is obtained by interpolation. In the current version of Mlxtran, interpolation is performed by using the last given value:

 x(t)=x_j~~\text{for}~~t_j \leq t < t_{j+1}.

Regression variables are used in the Mlxtran model by defining them as a list in the regressor block of the [LONGITUDINAL] section:

[LONGITUDINAL]
input = {reg_var1, reg_var2, ....}
reg_var1 = {use = regressor}
reg_var2 = {use = regressor}
...

For each regression variable defined in the regressor list of the Monolix Mlxtran model, there must be a column in the data set defined as a regressor column X. Regressors in the data set and in the Monolix Mlxtran model are matched by order, not by name.

2.6.Type of ODE, what is the impact ?

Introduction

A numerical algorithm providing an efficient and stable way to solve the ODEs and DDEs is used to compute the solution of the dynamical models. Different numerical algorithms can be used to solve the ODE depending on the properties of the ODE system (Adams methods for non stiff ODEs, and Backward Differentiation Formulas methods for stiff ODEs). The right numerical algorithm must be selected in order to get an accurate and stable solution within a reasonable computational time. The stiffness of an ODE systems is one of the main properties that influences the choice of the numerical algorithms. Stiff ODEs can lead to very long computational times if an inappropriate algorithm is used. Stiff ODEs are typical for models that include processes taking place at different time scales. For example models with reaction and diffusion processes are known to be stiff. Reactions can occur at the seconds time scale while diffusion processes can take hours. For such cases a dedicated numerical algorithm for stiff ODEs is available.

A solver for stiff ODEs can be selected in Mlxtran using the keyword odeType. There are two possible choices for odeType:

; ode is considered as stiff
odeType = stiff 
; ode is considered as non-stiff (default)
odeType = nonStiff

This command has to be defined in the [LONGITUDINAL] section. When odeType is not specified then the nonStiff ODE solver is used by default.

Rules and Best Practices

  • For the DDEs, the keyword odeType is ineffective.
  • For many ODEs the nonStiff solver will provide the best solution. However, it is good practice to always test both solvers to see which one is providing the shorter computational time.
  • The absolute and relative tolerance for the numerical resolutions are 1e-6 and 1e-3 respectively for nonStiff ODEs and 1e-9 and 1e-6 respectively for stiff ODEs .

2.7.Observation models for continuous data

Purpose

The observation model is the link between the prediction f of the structural model and the observation. Thus, the observational model is an error model representing the noise and the uncertainty of the measurements. The observation model can be defined in the Mlxtran model file and/or in the Monolix interface. If the observation model is defined in the Mlxtran model file, then the error model settings in the Monolix interface are disabled.

Possible observation models

For the continuous observations, the general form y = f + g e is considered where e is a sequence of independent random variables normally distributed with mean 0 and variance 1. Some extensions assume that there is a distribution t such that t(y) = t(f) + g e. It is also possible to assume that the residual errors are correlated. Following is a list of observational models that can be selected in the Monolix user interface:

  • const: constant error model y = f + ae
  • prop: proportional error model y = f + bfe
  • comb1: combined error model y = f + (a+bf)e
  • comb2: combined error model y = f + \sqrt{a^2 + (bf)^2}e (equivalent to y = f + ae_1 + bfe_2 where e1 and e2 are sequences of independent random variables normally distributed with mean 0 and variance 1)
  • propc: proportional error model + power y = f + bf^ce
  • comb1c: combined error model + power y = f + (a + b f^c)e
  • comb2c: combined error model + power y = f + \sqrt{a^2 + (bf^c)^2}e (equivalent to y = f + ae_1 + bfe_2 where e1 and e2 are sequences of independent random variables normally distributed with mean 0 and variance 1)
  • exp: exponential error model t(y) = \log(y) and y = fe^{ae}
  • logit: logit error model t(y) = \log(\frac{y}{1-y})
  • band(0,10): extended logit error model t(y) = \log(\frac{y}{10-y})
  • band(0,100): extended logit error model t(y) = \log(\frac{y}{100-y})

Notice that in the two last cases, the representation as a function can be misleading but is easier to explain the band extension.

Autocorrelated observation error
Autocorrelation can be modeled for each observational model by selecting the autocorrelation option with the checkbox “r” in the Monolix user interface. When selecting the autocorrelation, Monolix estimates the autocorrelation parameter r. Note, that when several outputs are available then the autocorrelation can be selected for each output independently.

Positive gain on the error model
The second parameter b in the observational models comb1 and comb1c can be forced to be always positive by selecting b>0.

Mlxtran observational model syntax

The DEFINITION: block in the [LONGITUDINAL] section is used to define the observational model:

DEFINITION: 
observationName = {distribution = distributionType, prediction = predictionName, errorModel = errorModel(param)}

(notice that one can use type=continuous instead of distribution = distributionType)

For example, if the observation is a concentration with a combined error model (Concentration = Cc + (a+b*Cc)*e), the observational error model is written as

DEFINITION: 
Concentration= {distribution = normal, prediction = Cc, errorModel=combined1(a, b)}

When the observational error is defined in the Mlxtran model file, the user must declare the observational model parameters (a and b in the presented example) as inputs.

 

Rules and best practices

  • The eventual arguments of the error model can not be calculations, only input names.
  • In Monolix, the user can choose the error model through the interface.
  • In Monolix, the name of the error models input parameters can not have any name.
    • The name of the input should correspond to the definition of the error model (ex. a for a constant error model, b for a proportional error model, (a,b) for a combined1 error model, …)
    • If there are several continuous outputs, the names of the error models input parameters should be linked to the order of the outputs (1 for the first error model, …)
    • For example, for a single output, a combined error model writes without any number as follows
      DEFINITION: 
      Concentration= {distribution = normal, prediction = Cc, errorModel=combined1(a, b)}
    • For example, for two outputs, a combined error model and a constant error model write as follows
      DEFINITION: 
      Concentration= {distribution = normal, prediction = Cc, errorModel=combined1(a1, b1)}
      PCA= {distribution = normal, prediction = E, errorModel=constant(a2)}
  • Notice that a parameter can not be shared by two error model. For example, in the previous Concentration/PCA example, we can not replace a2 by a1.

2.8.Observation model for count data

Use of count data

Longitudinal count data is a special type of longitudinal data that can take only nonnegative integer values {0, 1, 2, …} that come from counting something, e.g., the number of seizures, hemorrhages or lesions in each given time period. In this context, data from individual is the sequence y_i=(y_{ij},1\leq j \leq n_i) where y_{ij} is the number of events observed in the jth time interval I_{ij}.
Count data models can also be used for modeling other types of data such as the number of trials required for completing a given task or the number of successes (or failures) during some exercise. Here, y_{ij} is either the number of trials or successes (or failures) for subject i at time t_{ij}. For any of these data types we will then model y_i=(y_{ij},1\leq j \leq n_i) as a sequence of random variables that take their values in {0, 1, 2, …}.  If we assume that they are independent, then the model is completely defined by the probability mass functions \mathbb{P}(y_{ij}=k) for k \geq 0 and 1 \leq j \leq n_i. Here, we will consider only parametric distributions for count data.

Observation model syntax

Considering the observations as a sequence of conditionally independent random variables, the model is completely defined by the probability mass functions P(y_{ij}=k). An observation variable for count data is defined using the type count. Its additional field is:

  • P(Y=k): Probability of a given count value k, for the observation named Y. k is a natural number. A transformed probability can be provided instead of a direct one. The transformation can be log, logit, or probit. The bounded variable k supersedes in this scope any predefined variable k.

Example

In the proposed example, the Poisson distribution is used for defining the distribution of y_j:

y_j \sim \textrm{Poisson}(\lambda_j)

where the Poisson intensity \lambda_j is function of time \lambda_j = a+bt_j. This model is implemented as follows

[LONGITUDINAL]
input = {a,b}

EQUATION:
lambda = a+b*t

DEFINITION:
y = {type=count, P(y=k) = exp(-lambda)*(lambda^k)/factorial(k)}

2.9.Observation model for categorical data

Observation model for categorical ordinal data

Use of categorical data

Assume now that the observed data takes its values in a fixed and finite set of nominal categories \{c_1, c_2,\ldots , c_K\}. Considering the observations (y_{ij},\, 1 \leq j \leq n_i) for any individual i as a sequence of conditionally independent random variables, the model is completely defined by the probability mass functions \mathbb{P}(y_{ij}=c_k | \psi_i) for k=1,\ldots, K and 1 \leq j \leq n_i. For a given (i,j), the sum of the K probabilities is 1, so in fact only (K-1) of them need to be defined. In the most general way possible, any model can be considered so long as it defines a probability distribution, i.e., for each k, \mathbb{P}(y_{ij}=c_k | \psi_i) \in [0,1], and \sum_{k=1}^{K} \mathbb{P}(y_{ij}=c_k | \psi_i) =1. Ordinal data further assume that the categories are ordered, i.e., there exists an order \prec such that

c_1 \prec c_2,\prec \ldots \prec c_K .

We can think, for instance, of levels of pain (low \prec moderate \prec severe) or scores on a discrete scale, e.g., from 1 to 10. Instead of defining the probabilities of each category, it may be convenient to define the cumulative probabilities \mathbb{P}(y_{ij} \preceq c_k | \psi_i) for k=1,\ldots ,K-1, or in the other direction: \mathbb{P}(y_{ij} \succeq c_k | \psi_i) for k=2,\ldots, K. Any model is possible as long as it defines a probability distribution, i.e., it satisfies

0 \leq \mathbb{P}(y_{ij} \preceq c_1 | \psi_i) \leq \mathbb{P}(y_{ij} \preceq c_2 | \psi_i)\leq \ldots \leq \mathbb{P}(y_{ij} \preceq c_K | \psi_i) =1 .

It is possible to introduce dependence between observations from the same individual by assuming that (y_{ij},\,j=1,2,\ldots,n_i) forms a Markov chain. For instance, a Markov chain with memory 1 assumes that all that is required from the past to determine the distribution of y_{ij} is the value of the previous observation y_{i,j-1}., i.e., for all k=1,2,\ldots ,K,

\mathbb{P}(y_{ij} = c_k\,|\,y_{i,j-1}, y_{i,j-2}, y_{i,j-3},\ldots,\psi_i) = \mathbb{P}(y_{ij} = c_k | y_{i,j-1},\psi_i).

Observation model syntax

Considering the observations as a sequence of conditionally independent random variables, the model is again completely defined by the probability mass functions
P(y_{ij}=c_k) for each category. For a given j, the sum of the K probabilities is 1, so in fact only K-1 of them need to be defined. The distribution of ordered categorical data can be defined in the block DEFINITION: of the Section [LONGITUDINAL] using either the probability mass functions. Ordinal data further assume that the categories are ordered: c_1 \leq c_2 \leq ... \leq c_K. Instead of defining the probabilities of each category, it may be convenient to define the cumulative probabilities P(y_j \leq c_k) for k from 1 to K-1 or the cumulative logits \textrm{logit}(P(y_j \leq c_k)) for k from 1 to K-1. An observation variable for ordered categorical data is defined using the type categorical. Its additional fields are:

  • categories: List of the available ordered categories. They are represented by increasing successive integers.
  • P(Y=i): Probability of a given category integer i, for the observation named Y. A transformed probability can be provided instead of a direct one. The transformation can be log, logit, or probit. The probabilities are defined following the order of their categories. They can be provided for events where the category is a boundary, instead of an exact match. All boundaries must be of the same kind. Such an event is denoted by using a comparison operator. When the value of a probability can be deduced from others, its definition can be spared.

Example

In the proposed example, we use 4 categories and the model is implemented as follows

[LONGITUDINAL]
input =  {th1, th2, th3}

DEFINITION: 
level = { type = categorical, categories = {0, 1, 2, 3},
logit(P(level <=0)) = th1
logit(P(level <=1)) = th1 + th2
logit(P(level <=2)) = th1 + th2 + th3}

Observation model for categorical data modeled as a discrete Markov chain

Use of categorical data modeled as a Markov chain

In the previous categorical model, the observations were considered as independent for individual i. It is however possible to introduce dependence between observations from the same individual assuming that (y_{ij})_{j=1,.., n_i} forms a Markov chain.

Observation model syntax

An observation variable for ordered categorical data modeled as a discrete Markov chain is defined using the type categorical, along with the dependence definition Markov. Its additional fields are:

  • categories: List of the available ordered categories. They are represented by increasing successive integers. It is defined right after type.
  • P(Y_1=i): Initial probability of a given category integer i, for the observation named Y. This probability belongs to the first observed value. A transformed probability can be provided instead of a direct one. The transformation can be log, logit, or probit. The probabilities are defined following the order of their categories. They can be provided for events where the category is a boundary, instead of an exact match. All boundaries must be of the same kind. Such an event is denoted by using a comparison operator. When the value of a probability can be deduced from others, its definition can be spared. The initial probabilities are optional as a whole, and the default initial law is uniform.
  • P(Y=j|Y_p=i): Probability of transition to a given category integer j from a previous category i, for the observation named Y. A transformed probability can be provided instead of a direct one. The transformation can be log, logit, or probit. The probabilities are grouped by law of transition for each previous category i. Each law of transition provides the various transition probabilities of reaching j. They can be provided for events where the reached category j is a boundary, instead of an exact match. All boundaries must be of the same kind for a given law. Such an event is denoted by using a comparison operator. When the value of a transition probability can be deduced from others within its law, its definition can be spared.

Example

An example where we define an observation model for this case is proposed here

[LONGITUDINAL]
input = {a1, a2, a11, a12, a21, a22, a31, a32}

DEFINITION:
State = { type = categorical, categories = {1,2,3}, dependence = Markov
P(State_1=1) = a1
P(State_1=2) = a2
logit(P(State <=1|State_p=1)) = a11
logit(P(State <=2|State_p=1)) = a11+a12
logit(P(State <=1|State_p=2)) = a21
logit(P(State <=2|State_p=2)) = a21+a22
logit(P(State <=1|State_p=3)) = a31
logit(P(State <=2|State_p=3)) = a31+a32}

Observation model for a categorical data modeled as a continuous Markov chain

Observation model syntax

An observation variable for ordered categorical data modeled as a continuous Markov chain is also defined using the type categorical, along with the dependence definition Markov. But here transition rates are defined instead of transition probabilities. Its additional fields are:

  • categories: List of the available ordered categories. They are represented by increasing successive integers. It is defined right after type.
  • P(Y_1=i): Initial probability of a given category integer i, for the observation named Y. This probability belongs to the first observed value. A transformed probability can be provided instead of a direct one. The transformation can be log, logit, or probit. The probabilities are defined following the order of their categories. They can be provided for events where the category is a boundary, instead of an exact match. All boundaries must be of the same kind. Such an event is denoted by using a comparison operator. When the value of a probability can be deduced from others, its definition can be spared. The initial probabilities are optional as a whole, and the default initial law is uniform.
  • transitionRate(i,j): Transition rate departing from a given category integer i and arriving to a category j. They are grouped by law of transition for each departure category i. One definition of transition rate can be spared by law of transition, as they must sum to zero.

Example

An example where we define an observation model for this case is proposed here

[LONGITUDINAL]
input={p1, q12, q21}

DEFINITION:
State = { type = categorical, categories = {1,2}, dependence = Markov
P(State_1=1) = p1
transitionRate(1,2) = q12
transitionRate(2,1) = q21}

2.10.Observation model for time-to-event data

Use of time-to-event data

Here, observations are the “times at which events occur”. An event may be one-off (e.g., death, hardware failure) or repeated (e.g., epileptic seizures, mechanical incidents, strikes). Several functions play key roles in time-to-event analysis: the survival, hazard and cumulative hazard functions. We are still working under a population approach here so these functions, detailed below, are thus individual functions, i.e., each subject has its own. As we are using parametric models, this means that these functions depend on individual parameters (\psi_i).

  • The survival function S(t, \psi_i) gives the probability that the event happens to individual i after time t>t_{\text{start}}:

    S(t,\psi_i) = \mathbb{P}(T_i>t;\psi_i)

  • The hazard function h(t,\psi_i) is defined for individual i as the instantaneous rate of the event at time t, given that the event has not already occurred:

    h(t,\psi_i) \ \ = \ \ \lim_{dt\to 0} \frac{S(t,\psi_i) - S(t + dt,\psi_i)}{ S(t,\psi_i) \, dt} .

    This is equivalent to

    h(t,\psi_i) \ \ = \ \ -\frac{d}{dt} \log{S(t,\psi_i)} .

  • Another useful quantity is the cumulative hazard function H(a,b;\psi_i), defined for individual i as

H(a,b;\psi_i) \ \ = \ \ \int_a^b h(t,\psi_i) \, dt .

Note that S(t,\psi_i) = e^{-H(t_{\text{start}},t;\psi_i)}. Then, the hazard function h(t,\psi_i) characterizes the problem, because knowing it is the same as knowing the survival function S(t,\psi_i). The probability distribution of survival data is therefore completely defined by the hazard function.

Observation model syntax

An observation variable for time-to-event or repeated time to event data is defined using the type event. Its additional fields are:

  • eventType: Type of the events. The exact time of the events can be observed, or censored per interval. The respective keywords are exact and intervalCensored. By default, an exact time is assumed.
  • maxEventNumber: Maximum number of events (integer). By default the number of simulated events is unlimited. If the event is one-off (as death for instance), it is important to indicate maxEventNumber=1 to speed up simulations (including simulations for the prediction interval of the TTE plot in Monolix).
  • rightCensoringTime: Right censoring time of events (number). It is useful for simulation only, and by default it is the actual time of the last record.
  • intervalLength: Length of censoring intervals (number). It is useful for simulation only, and by default it is the tenth part of the global length.
  • hazard: Hazard function.

Example

An example where we define an observation model for this case is proposed here

[LONGITUDINAL]
input={gamma, V, Cl}

EQUATION:
Cc = pkmodel(V,Cl)
haz =  gamma*Cc

DEFINITION:
Seizure = {type = event, eventType = intervalCensored, maxEventNumber = 1, 
rightCensoringTime = 120, intervalLength = 10, hazard = haz}

2.11.What is specific in [LONGITUDINAL] to parameter estimation and to simulation ?

Purpose

Parameter estimation with Monolix and simulation with Simulx or Mlxplore are different tasks. Because of this there are some differences in what sections and blocks need to be included in a Mlxtran model used for parameter estimation with Monolix compared to a Mlxtran model used for simulation with Simulx or Mlxplore.

Mlxplore: model exploration for continuous models

The purpose of Mlxplore is the exploration and visualization of models. Mlxplore is used to study the model prediction and the inter-individual variability. The observational model (error model) is not included in Mlxplore. Because of this only continuous data models can be simulated.

Monolix: parameter estimation for non-linear mixed effect models

The purpose of Monolix is the parameter estimation in non linear mixed effects models. Monolix provides a user interface to define the statistical elements of the models. Therefore, some of the sections and blocks are not needed. For continuous data models the observational must not be defined in the Mlxtran file. The individual model and the covariate model must not be defined in the Mlxtran file. This means the following rules apply for all Mlxtran model for Monolix:

  • Except regressors, the input parameters of [LONGITIDINAL] are only the outputs of [INDIVIDUAL] and eventually parameters of the error models (if used)
  • The entire [INDIVIDUAL] section is never used
  • The entire [COVARIATE] section is never used

Simulx: clinical trial simulation

The purpose of Simulx are simulations for any non linear mixed effects models. In contrast to Mlxplore, Simulx can also be used with an observational model (error model).

3.PK:

Description

The PK: block can be included into the [LONGITUDINAL] section and can serve two main functions:

  1. It is used to provide a link between the administration information in the data set and the model.
  2. It is for the use of macros that are dedicated to the description of PK models. These macros allow the user to have an intuitive and compact representation of the most common PK models used in pharmacometrics.

Inputs and outputs

The PK: block has no inputs or outputs. It rather declares that a set of macros that define the administration and/or a PK model.

Rules

  1. Before an administration macro can be used the corresponding compartments must be defined first using a compartment macro
  2. PK macros cannot be included into an arithmetic expression
  3. PK macros cannot be enclosed within a conditional statement
  4. Macros can be used along ODE equations
  5. The PK: block must be in the [LONGITUDINAL] section

PK macros by function

The following two links provide overview tables:

3.1.Compartment macro

Purpose

The macro compartment defines a PK model compartment. Compartments can be the target of an administration, can be subject to a clearance process or can be linked with other compartments for exchange processes. The compartment amount, concentration and volume are variables.

Arguments

Arguments for the macro compartment are:

  • cmt: Unique identifier of the compartment. Its default value is 1.
  • amount: Name of variable defined as the amount within the compartment. Its dynamics are defined by dose absorptions, eliminations, and the transfer rates with other compartments. These dynamics can extend an ODE system that defines a component with this name.
  • volume: Name of predefined variable to use as the volume of the compartment. It enables to define concentration. Its default value is 1.
  • concentration: Name of the variable defined as the concentration within the compartment.

Example

PK:
; To define a compartment with ID 1, of volume V, an amount called Ac, and a concentration called Cc
compartment(cmt=1, amount=Ac, volume=V, concentration=Cc)

If no administration is involved for a compartment, and if the amount and all its dynamics are defined as an ODE component with its derivative, then the compartment macro definition is not needed.

Example with Mlxplore
In the following example, a compartment is defined in the PK: bloc and the dynamics of the amount is defined with the iv and elimination macro. The model is implemented in the file compartment.mlxplore.mlxtran available as Mlxplore demo. A snapshot of the code is shown below:

[LONGITUDINAL]
input = {V, k}

PK: 
compartment(cmt=1, amount=Ac, concentration=Cc, volume=V)
iv(cmt=1, type=1)
elimination(cmt=1, k)

The considered administration is a dose of 1 at time 5. We defined the one compartment, and the associated concentration, amount, id, are defined in it. Therefore, it is very simple to define the associated dynamics. We added an absorption process as a bolus and defined a linear elimination. The results can be seen in the following figure.

fig_Compartment

The main interest of this example is that all the parameters of the compartments are well defined and therefore their manipulation is easy.

Rules and Best Practices

  • We encourage the user to use all the fields in the macro to guarantee non confusion between concentration, amount, …
  • The compartment definition has to be done in the first place before additional macros.
  • Format restriction (non compliance will raise an exception)
    • The value after cmt= is necessarily an integer.
    • The value after amount= and concentration= are necessarily strings.
    • The value after volume= can be either a double or replaced by an input parameter. Calculations are not supported.

3.2.Peripheral macro

Purpose

The macro peripheral defines a peripheral compartment. It is equivalent to a compartment with two transfers of drug amount towards and from another base compartment. This base compartment must have been previously defined and is referenced by its label. If the amount or concentration of the peripheral compartment are not needed then the amount, volume or concentration of the peripheral compartment do not need to be defined.

Arguments

Arguments for macro peripheral are:

  • kij or k_i_j: Input rate from the compartment of label i. It also defines a label j for the peripheral compartment. Here, both labels i and j must be integers. Mandatory.
  • kji or k_j_i: Output rate to the compartment of label i. It also defines a label j for the peripheral compartment. Here, both labels i and j must be integers. Mandatory.
  • amount: Name of variable defined as the amount within the compartment. Its dynamics are defined by dose absorptions, eliminations, and the transfer rates with other compartments. These dynamics can extend an ODE system that defines a component with this name.
  • volume: Name of predefined variable to use as the volume of the compartment. It enables to define concentration. The default value is 1. If the volume is not defined, the concentration cannot be defined.
  • concentration: Name of the variable defined as the concentration within the compartment.

Example

PK:
; definition of a peripheral compartment with cmt=2 with rates k12 and k21 and an amount called Ap, a volume V2, and a concentration Cp
peripheral(k12, k21, amount=Ap, volume=V2, concentration=Cp)
; definition of a peripheral compartment with cmt=3, linked to compartment 1, with rates k13 and k31 a volume equals by default to 1
peripheral(k13, k31)

Rules and Best Practices

  • To use inter-compartment clearance Q and peripheral volume V2 as parameters instead of k12 and k21, the syntax is:
    peripheral(k12=Q/V, k21=Q/V2)
  • We encourage the user to use all the fields in the macro to guarantee non confusion between concentration, amount, …
  • Format restriction (non compliance will raise an exception)
    • The values after k are necessarily an integer (related to predefined compartment id).
    • The value after kij= can be either a double or replaced by an input parameter. Calculations are not supported.
    • The value after amount= and concentration= are necessarily strings.
    • The value after volume= can be either a double or replaced by an input parameter. Calculations are not supported.

3.3.Effect macro

Purpose

The macro effect defines an effect compartment. The effect compartment is linked to a parent compartment. The drug exchange between the effect compartment and the parent compartment does not affect the mass balance of the parent compartment. The parent compartment must be defined before the effect compartment is defined.

Arguments

Arguments for the macro effect are:

  • cmt: Label of the linked base compartment. Its default value is 1.
  • ke0: Transfer rate from the linked base compartment. Mandatory.
  • concentration: Name of the variable defined as the concentration within the effect compartment. Mandatory.

Example:

PK:
; Define an effect compartment linked to the base compartment 1, 
; with a transfer rate ke0 to the effect compartment, 
; with Ce as concentration's name
effect(cmt=1, ke0, concentration=Ce)

Example with Mlxplore:

In the following example, a compartment is defined in the PK: bloc. An iv absorption process along with a linear elimination process is added to the main compartment. An effect is added with a transfer rate ke0. The model is implemented in the file effect.mlxplore.mlxtran available in the Mlxplore demos. The code is detailed below:

<MODEL>
[LONGITUDINAL]
input = {V, k, ke0}

PK: 
compartment(cmt=1, amount=Ac, concentration=Cc, volume=V)
elimination(cmt=1, k)
iv(cmt=1)
effect(cmt=1, ke0, concentration=Ce)

<DESIGN>
[ADMINISTRATION]
admin = {time=5, amount=1, target=Ac, rate=.5}

<PARAMETER>
V = 10
ke0  = .5
k = 1

<OUTPUT>
grid = 0:.05:20
list = {Ce,Cc}

<RESULTS>
[GRAPHICS]
p = {y={Ce, Cc}, ylabel='Concentrations', xlabel='Time'}

The concentration in the base compartment and in the effect compartment are proposed in the following figure where the concentration in the main (base) compartment is in orange, and the one in the effect compartment is in blue.

fig_Effect

Rules and Best Practices:

  • We encourage the user to use all the fields in the macro to guarantee non confusion between fields.
  • A base compartment must be defined first.
  • Format restriction (non compliance will raise an exception)
    • The value after cmt= is necessarily an integer.
    • The value after ke0= can be either a double or replaced by an input parameter. Calculations are not supported.
    • The value after concentration= is necessarily a string.

3.4.Transfer macro

Purpose

The macro transfer defines a uni-directional transfer process from a base compartment to a target compartment. The base compartment and the target compartment must be defined first before the transfer can be defined. For the more common bi-directional transfer process it is better to use the macro peripheral instead of the macro transfer.

Arguments

Its named arguments are:

  • from: Label of the source compartment for the transfer. Its default value is 1.
  • to: Label of the target compartment for the transfer. Its default value is 1.
  • kt: Rate of the transfer. Mandatory.

Example

PK:
; transfer from compartment 1 to compartment 2 with a rate kt
transfer(from=1, to=2, kt)

Example with Mlxplore:

In the following example, two compartments are defined in the PK: block. A transfer from compartment 1 to compartment 2 is added, with a transfer rate kt. The model is implemented in the file transfer.mlxplore.mlxtran available in the Mlxplore demos, and shown below:

<MODEL>
[LONGITUDINAL]
input = {V1, V2, kt}

PK: 
compartment(cmt=1, amount=Ac, concentration=Cc1, volume=V1)
compartment(cmt=2, amount=Ad, concentration=Cc2, volume=V2)
oral(cmt=1,ka=1)
transfer(from=1, to=2, kt)

<DESIGN>
[ADMINISTRATION]
admin = {time=5, amount=1, target=Ac, rate=.5}

<PARAMETER>
V1 = 10
V2 = 5
kt = .5

<OUTPUT>
grid = 0:.05:20
list = {Cc1,Cc2}

<RESULTS>
[GRAPHICS]
p = {y={Cc1, Cc2}, ylabel='Concentrations', xlabel='Time'}

The concentration in the compartment and the transfer are shown in the following figure in blue and orange respectively.

fig_transfer

Best Practices:

  • We encourage the user to use all the fields in the macro to guarantee non confusion between the fields.
  • Format restriction (non compliance will raise an exception)
    • The value after from= and to= are necessarily integers.
    • The value after kt= can be either a double or replaced by an input parameter. Calculations are not supported.

3.5.Depot macro

Description

The macro depot is a multipurpose macro that can accommodate different types of administrations. It is typically used together with ODE systems to define how the administration from the data set are linked with the model variables. It is the only macro that can be used with ODEs for administration. With the macro depot, a bolus, a zero order absorption (i.e infusion), or a first order absorption (with or without transit process) can be defined.

We encourage the user to use all the fields in the macro to guarantee no confusion between parameters

Arguments

The depot macro can be used for bolus doses, zero-order absorption (i.e infusion), and first-order absorption. Some arguments are common for the three types of administrations, some are specific.

The arguments common to bolus, zero-order and first-order absorption are:

  • type: Administration type of doses subject to the absorption process. Its default value is 1. Alias: adm. Thus, when defining a treatment in Mlxplore for example, instead to define a target, the user should define a type and apply the dedicated absorption process on it.
  • target: Name of the ODE variable that is targeted by the administration. Mandatory.
  • Tlag: Lag time before the absorption. Its default value is 0.
  • p: Fraction of the absorbed amount. It can affect the effective rate of the absorption, not its duration. p can take any positive value (including > 1). Its default value is 1.

Specific arguments for bolus doses:

For bolus doses, no additional argument is needed.

The following code defines a bolus for doses of type 1 (e.g ADM=1 in the data set), applied to the ODE variable Ad, with a delay Tlag and a fraction absorbed F :

PK:
depot(type=1, target=Ad, Tlag, p=F)

 

Specific arguments for zero-order absorption (i.e infusion):

To define a zero-order absorption, the following argument must be added:

  • Tk0: Duration of the zero order absorption. Mandatory to define zero-order absorption.

The following code defines a zero-order absorption process of duration Tk0, for doses of type 2, applied to the ODE variable Ac, without lag time (Tlag=0 when not specified) and with the entire dose being absorbed (p=1 when not defined):

PK:
depot(type=2, target=Ac, Tk0)

 

Specific arguments for first-order absorption:

To define a first-order absorption, the following arguments can be added:

  • ka: Rate of the first order absorption. Mandatory to define first-order absorption.
  • Ktr: Transit rate.
  • Mtt: Mean transit compartments time for the absorption.

The following code defines a first-order absorption process with rate ka, for doses of type 1 (type=1 when not specified), applied to the ODE variable Ad, with a lag-time Tlag of 2.1, and only 30% of the dose being absorbed:

PK:
depot(target=Ac, ka, Tlag=2.1, p=0.3)

Rules

  • The value after type= must be an integer.
  • The value after target= must be a string representing the ODE variable
  • The inputs after Tlag=, p=, Tk0=, ka=, Ktr=, Mtt= can be either a
    • Double
    • Input parameter
    • Variable
    • Calculations are not supported
  • The associated treatment or administration can not be defined with a rate nor an infusion timing from the data set (RATE and TINF column-types in the dataset). If a rate or an infusion timing is needed, the user can use the iv macro and/or define a compartment to define the dynamics of the absorption.

3.6.Absorption/oral macro

Purpose

The macro absorption/oral enables to link the administration and the model, for zero-order and first-order absorption processes (for bolus administrations, use the iv macro instead). For Mlxtran the macro names ‘absorption’ and ‘oral’ can be used interchangeably. The administration can either be defined in a data set when Monolix is used, or the administration can be defined via an administration design definition when Mlxplore or Simulx are used. In order to handle models with several administrations each administration has a unique identifier called type. This identifier must be defined in the data set or in the administration design definition, and used in the absorption/oral macro.

Arguments

The absorption/oral macro can be used for zero-order and first-order absorptions. The arguments common to the two absorptions are:

  • type: Administration type of doses subject to the absorption process. Its default value is 1. Alias: adm. Thus, when defining a treatment in Mlxplore for example, instead to define a target, the user should define a type and apply the dedicated absorption process on it.
  • Tlag: Lag time before the absorption. Its default value is 0.
  • p: Final proportion of the absorbed amount. It can affect the effective rate of the absorption, not its duration. p can take any positive value (including > 1). Its default value is 1.
  • cmt: Label of the compartment called in by the absorption process. Its default value is 1.

To define a zero-order or first-order absorption, the additional arguments defined below are needed.

Arguments specific to a zero-order absorption (i.e infusion)

To define a zero-order absorption, the following argument must be added:

  • Tk0: Duration of the zero order absorption. Mandatory to define a zero-order absorption.

Example:

; zero order absorption process for the doses of type 1, in compartment 1 with a delay Tlag of 1 and a duration Tk0
absorption(type=1, cmt=1, Tlag=1, Tk0 = 2, p=1)

Arguments specific to a first-order absorption

To define a first-order absorption, the following arguments can be added:

  • ka: Rate of the first order absorption. Mandatory to define a first-order absorption.
  • Ktr: Transit rate.
  • Mtt: Mean transit time for the absorption.

Example:

PK:
; first order absorption process for the doses of type 1, in compartment 1 with a delay Tlag of 1 and a rate ka
absorption(type=1, cmt=1, Tlag=1, ka)

Note: in case of transit compartments, the mean transit time is defined as Mtt = (n+1)/Ktr with n the number of transit compartments (excluding the depot compartment and the absorption compartment):

mlxtran_transit_comp_scheme

The implementation is the same as described in Savic et al, “Implementation of a transit compartment model for describing drug absorption in pharmacokinetic studies” (2007), except that to approximate the factorial n!, we use the gamma function, which is more precise, instead of the Stirling formula.

Example with Mlxplore: Comparison of absorptions

In the presented example, we show the difference between the two absorption processes. In addition, the effect of the Ktr and Mtt parameters is explored in a third model. The model is implemented in the following file mlxplore_Absorption.txt.

<MODEL> 
[LONGITUDINAL]
input = {V, Tlag, ka, Tk0, Ktr, Mtt}

PK: 
compartment(cmt=1, amount=A1, concentration=Cc_zoa, volume=V)
absorption(cmt=1, type=1, Tk0)
elimination(cmt=1, k=1)

compartment(cmt=2, amount=A2, concentration=Cc_foa, volume=V)
absorption(cmt=2, type=1, Tlag, ka)
elimination(cmt=2, k=1)

compartment(cmt=3, amount=A3, concentration=Cc_foaT, volume=V)
absorption(cmt=3, type=1, Tlag, ka, Ktr, Mtt)
elimination(cmt=3, k=1)

EQUATION:
ddt_A1 = 0
ddt_A2 = 0
ddt_A3 = 0

<DESIGN> 
[ADMINISTRATION]
adm = {time=5, amount=1, type=1}

<PARAMETER> 
V = 10
Tlag = 2
ka = .5
Tk0 = 2
Ktr = 3
Mtt = 2

<OUTPUT> 
grid = 0:.05:20
list = {Cc_zoa, Cc_foa, Cc_foaT}

<RESULTS> 
[GRAPHICS]
p = {y={Cc_zoa, Cc_foa, Cc_foaT}, ylabel='Concentrations', xlabel='Time'}

The three concentrations are presented in the following figure.

fig_absorption

One can clearly see the differences between the zero order absorption (Cc_zoa in blue), the first order absorption (Cc_foa in orange) and the absorption with transit compartments (in purple).

Rules and Best Practices:

  • We encourage the user to use all the fields in the macro to guarantee no confusion between parameters
  • Format restriction (non compliance will raise an exception)
    • The value after cmt= and type= are necessarily integers.
    • The value after Tlag=, p=, V=, ka=, Tk0=, Ktr=, Mtt= can be either a double or replace by an input parameter. Calculations are not supported.
    • The associated treatment or administration can not be defined with a rate nor an infusion timing (RATE and TINF column-types in the data set). If a rate or an infusion timing is present, the user can use the iv macro and/or define a compartment to define the dynamics of the absorption.

3.7.IV macro

Purpose

The macro iv enables to link the administration with the model, for intravenous doses (bolus or infusion). Doses defined in the [ADMINISTRATION] section or in the data set without an administration rate or infusion time are instantaneously absorbed within the associated compartment, as an IV bolus. Doses with an administration rate or infusion time (e.g keyword ‘rate’ in the [ADMINISTRATION] section of a Mlxplore file, or column-type RATE or TINF in the data set) are absorbed according to a zero order process, as an IV infusion.

Arguments

Arguments for macro iv are:

  • cmt: Label of the compartment called in by the absorption process. Its default value is 1.
  • type: Administration type of doses subject to the absorption process. Its default value is 1. Alias: adm. Thus, when defining a treatment in Mlxplore for example, instead to define a target, the user should define a type and apply the dedicated absorption process on it.
  • Tlag: Lag time before the absorption. Its default value is 0.
  • p: Final proportion of the absorbed amount. It can affect the effective rate of the absorption, not its duration. p can take any positive value (including > 1). Its default value is 1.

Example:

PK; intravenous bolus for the doses of type 1, in compartment 1 with a delay Tlag at 1 
iv(type=1, cmt=1, Tlag=1, p=1)

Example with Mlxplore

In the presented example, we show the difference two iv processes with and without a rate in the administration.

<MODEL> 
[LONGITUDINAL]
input = {V, Tlag}

PK: 
compartment(cmt=1, amount=A1, concentration=Cc_iv_bolus, volume=V)
iv(cmt=1, type=1, Tlag)
elimination(cmt=1, k=1)

compartment(cmt=2, amount=A2, concentration=Cc_iv_inf, volume=V)
iv(cmt=2, type=2, Tlag)
elimination(cmt=2, k=1)

<DESIGN> 
[ADMINISTRATION]
adm_1 = {time=5, amount=1, type=1}
adm_2 = {time=5, amount=1, type=2, rate=.1}

<PARAMETER> 
V = 10
Tlag = 2

<OUTPUT> 
grid = 0:.05:20
list = {Cc_iv_bolus, Cc_iv_inf}

<RESULTS> 
[GRAPHICS]
p = {y={Cc_iv_bolus, Cc_iv_inf}, ylabel='Concentrations', xlabel='Time'}

The two concentrations (Cc_iv_bolus in orange, and Cc_iv_inf in blue) are presented in the following figure.
fig_IV

Rules and Best Practices:

  • We encourage the user to use all the fields in the macro to guarantee no confusion between parameters
  • Format restriction (non compliance will raise an exception)
    • The value after cmt= and type= are necessarily integers.
    • The value after Tlag=, p= can be either a double or replaced by an input parameter. Calculations are not supported.
  • With the iv macro, it is not possible to give the rate or duration of the infusion as a parameter or fixed value. To do so, use the absorption macro with duration parameter Tk0 to define a zero-order absorption (i.e infusion).
  • When the iv macro is used in combination with a data set with a column-type RATE:
    • if RATE >0: infusion with rate RATE and duration AMT/RATE
    • if RATE <=0: bolus
  • When the iv macro is used in combination with a data set with a column-type TINF:
    • if TINF >0: infusion of duration TINF at a rate AMT/TINF
    • if TINF <=0: bolus

3.8.How to play with bioavailabiliy ?

Purpose

The bioavailability parameter p, available in the administration macros (‘depot’, ‘absorption’, and ‘iv’), defines the fraction dose absorbed by the administration type.

The bioavailability parameter can also be used to perform a unit conversion between the amount provided in the data set and the quantities represented in the model (for instance from mg to mmol). For this usage, p can take values greater than 1.

Example

In the following example, we compare a zero order absorption process, a first order absorption process, and an processes with a mixed zero-and first order absorption.

<MODEL> 
[LONGITUDINAL]
input = {V, Tlag, ka, Tk0, F}

PK: 
compartment(cmt=1, amount=A1, concentration=Cc_zoa, volume=V)
absorption(cmt=1, type=1, Tlag, Tk0, p=1)
elimination(cmt=1,k=.25)

compartment(cmt=2, amount=A2, concentration=Cc_foa, volume=V)
absorption(cmt=2, type=1, Tlag, ka, p=1)
elimination(cmt=2,k=.25)

compartment(cmt=3, amount=A3, concentration=Cc_mixed, volume=V)
absorption(cmt=3, type=1, Tlag, Tk0, p=F)
absorption(cmt=3, type=1, Tlag, ka, p=1-F)
elimination(cmt=3,k=.25)

<DESIGN> 
[ADMINISTRATION]
adm = {time=5, amount=1, type=1}

<PARAMETER> 
V = 10
Tlag = 2
ka = .5
Tk0 = 2
F = .25

<OUTPUT> 
grid = 0:.05:20
list = {Cc_zoa Cc_foa, Cc_mixed}

<RESULTS> 
[GRAPHICS]
p = {y={Cc_zoa Cc_foa, Cc_mixed}, ylabel='Concentrations', xlabel='Time'}

The zero-order absorption is shown in orange, the first-order absorption in blue and the mixed one in green, in the figure below:

fig_BioAvailability

3.9.Elimination macro

Purpose

The elimination macros permits to define different elimination processes (linear or Michaelis-Menten) for compartments. Several eliminations can be defined for the same compartment.

Arguments

Some arguments are common to the two elimination types, while some are specific to a linear or to a Michaelis-Menten type of elimination.

The arguments that are common to linear and Michaelis-Menten are:

  • cmt: Label of the compartment emptied by the elimination process. Its default value is 1.
  • V: Volume involved in the elimination process. When not specified, its default value is the volume of the compartment defined by cmt.

Additional arguments are needed to define a linear or Michaelis-Menten elimination type.

Arguments specific to a linear elimination

The use of one of the following additional arguments defines a linear elimination:

  • k: Rate of the elimination.
  • Cl: Clearance of the elimination.

Only one of k or Cl must be defined.
Note, that if no volume has been defined for the compartment and no volume has been defined for the elimination process, then the default volume V=1 is assumed.

Example:

PK:
elimination(cmt=1,k)

Arguments specific to a Michaelis-Menten elimination

The use of both of the following additional arguments defines a Michaelis-Menten elimination:

  • Vm: Maximum elimination rate
  • Km: Michaelis-Menten constant

Both arguments must be defined.

Example:

PK:
elimination(cmt=1, Vm, Km)

Example with Mlxplore : Comparison of the two eliminations
In the following example, the difference between the two elimination processes is demonstrated. The model is implemented in the file elimination.mlxplore.mlxtran, available in the Mlxplore demos and shown below:

<MODEL> 
[LONGITUDINAL]
input = {k, Vm, Km}

PK: 
compartment(cmt=1, amount=Alin, concentration=Cc_lin)
elimination(cmt=1, k)
iv(cmt=1, type=1)

compartment(cmt=2, amount=AMM, concentration=Cc_MM)
elimination(cmt=2, Vm, Km)
iv(cmt=2, type=2)

<DESIGN> 
[ADMINISTRATION]
adm_lin = {time=5, amount=1, type=1, rate=.5}
adm_MM = {time=5, amount=1, type=2, rate=.5}

<PARAMETER> 
k  = .5
Vm  = 2 
Km = .5

<OUTPUT> 
grid = 0:.05:20
list = {Cc_lin,Cc_MM}

<RESULTS> 
[GRAPHICS]
p = {y={Cc_lin,Cc_MM}, ylabel='Concentrations', xlabel='Time'}

The two concentrations are presented in the following figure, with the linear elimination in purple and the Michaelis-Menten elimination in light blue.

fig_Elimination
One can clearly see the nonlinearities in the Michaelis-Menten elimination process.

Rules and Best Practices:

  • We encourage the user to use all the fields in the macro to guarantee no confusion between parameters
  • Format restriction (non compliance will raise an exception)
    • The value after cmt= is necessarily an integer.
    • The value after V=, k=, Cl=, Km=, Vm= can be either a double or be replaced by an input parameter. Calculations are not supported.

3.10.Overview of macro input elements

Purpose

The goal is to propose an overview of macro input elements as proposed in the following table.

Several points have to be noticed

  • Macros are used in the PK: section of the Mlxtran model
  • Parameters for a macro call are matched by name, not by ordering
  • Default values are given in brackets: for example (0)
  • Before concentrations can be used the volumes MUST be defined
  • adm and type are equivalent

 

Macro input parameters Macros
Administration Compartment Process
Macro depot iv oral or absorption compartment elimination peripheral transfer effect
Identifier adm (1) adm (1) adm (1) cmt(1)
Target target cmt(1) cmt(1) cmt(1) target compartments are defined by indices from(1) to (1) cmt(1)
Rates Required ka or Tk0 k or Cl or Vm, Km (k12, k21), (kij, kji) or (k_i_j, k_j_i) kt ke0
Optional ka or Tk0
Tlag (0)
Ktr, Mtt (0)
Tlag (0) Tlag (0) or
Mtt (0), Ktr
(k13, k31)
(k23, k32)
Bioavailability of fraction of the dose absorbed p (1) p (1) p (1)
Volume volume (1) volume (1)
Concentration concentration concentration concentration
Amounts amount amount
Explanation No need to define compartments.
Used with ODEs
Target compartment must be defined first
Rate or Tinf are taken from data set
Target compartment must be defined first Defines compartment and process at the same time

3.11.Overview of PK model input parameters

 

Pkmodel function input Process Required parameter Optional parameter Excluded parameter
Administration Bolus   Tlag, p Tk0, ka, Ktr, Mtt
Zero order absorption Tk0 Tlag, p ka, Ktr, Mtt
First order absorption ka Tlag, p Tk0
Absorption with transit compartments of mean transit time Mtt and transit rate Ktr ka, Ktr, Mtt Tlag, p Tk0
Bioavailability; fraction of the dose absorbed p Tlag Tk0, ka, Ktr, Mtt
Compartment Volume V    
Elimination Linear, rate ka   Cl, Km, Vm
Linear, clearance Cl   k, Km, Vm
Michaelis Menten Km, Vm   K, Cl
Transfers Transfer rates (k12,k21)
(k13, k31 )
   
Effect compartment transfer rate constant ke0    
Output Concentration in the central compartment first output name    
Concentration in the effect compartment second output name    

4.pkmodel

Introduction

The function pkmodel permits to define common PK models in a very concise way. The purpose of this macro is to simplify the modeling of classical pharmacokinetics. The PK model is inferred from the provided set of named arguments. Most of the arguments are optional, and the pkmodel function enables several parametrizations, to select different models of absorption, elimination, etc. With the pkmodel function, the most common PK models are available. The concentration within the central compartment is the main output of the function. If an effect compartment is defined, its concentration defines the second output. The administration of the doses is always supposed to be of type 1, and the default absorption is the IV bolus one. The label of the central compartment is 1. The pkmodel function can also be used within the block EQUATION: or the block PK:.

Rules

  • Only one central compartment is allowed
  • Only one type of administration is allowed
  • Only one pkmodel function is allowed in the Mlxtran file
  • Arguments must be from the list of defined arguments for pkmodel. Arguments with different names are not recognised.
  • pkmodel can not be used together with any macros for the administration. The administration is defined exclusively with the arguments supplied to pkmodel()
  • pkmodel output can be used with ODEs or with macros.
  • pkmodel can also be defined in the PK: block or the EQUATION: block.

Examples

EQUATION:
Cc = pkmodel(V, Cl)

This simple set of named arguments for pkmodel defines a PK model with one central compartment of label 1, with the default iv bolus absorption for doses of administration type 1 and a linear elimination with the clearance parametrization in Cl. The volume of the central compartment is V. The concentration in the central compartment is the output Cc of the function. The following example shows a more complex PK model using the function pkmodel.

Example:

EQUATION:
{Cc, Ce} = pkmodel(Tlag, ka, p, V, Vm, Km, k12, k21, k13, k31, ke0)

This more complex set of named arguments for pkmodel defines a PK model of one central compartment, with a first order absorption of rate ka for doses of administration type 1, and a Michaelis-Menten elimination of parameters Vm and Km. The volume of the central compartment is V. The concentration in the central compartment is the first output Cc of the function. An effect compartment is defined with a rate ke0 and its concentration is the second output Ce. Two peripheral compartments of labels 2 and 3 are linked to the central compartment of label 1. The respective couples of exchange rates are (k12, k21) and (k13, k31). The first order absorption has a lag time Tlag and the absorbed amount is scaled with a proportion of p.

The complete set of named arguments and output for pkmodel follows. They belong to the central compartment, the absorption process, the elimination process, the exchanges with the peripheral compartments, or an effect compartment. Some arguments are mutually exclusive, or require other ones to be also defined. Most of them are optional, so the mandatory arguments are stated.

Arguments for the central compartment

    • Cc = pkmodel(…): The first output is the concentration within the central compartment. Another name can be used. Mandatory.
    • V: Volume of the central compartment. Mandatory.

Arguments for the absorption process of a standard PK model

    • Tk0: Defines a zero order absorption of duration Tk0. Excludes ka, Ktr and Mtt.
    • ka: Defines a first order absorption of rate ka. Excludes Tk0.
    • Ktr: Along with ka and Mtt, defines an absorption with transit compartments, with transit rate Ktr. Excludes Tk0.
    • Mtt: Along with ka and Ktr, defines an absorption with transit compartments, with mean transit time Mtt. Excludes Tk0.
    • Tlag: Lag time before the absorption.
    • p: Final proportion of the absorbed amount. Can affect the effective rate of the absorption, not its duration.
    • default if no argument supplied for the absorption process: iv bolus

Arguments for the elimination process of a standard PK model

    • k: Defines a linear elimination of rate k. Excludes Cl, Vm and Km.
    • Cl: Along with V, defines a linear elimination of clearance Cl. Excludes k, Vm and Km.
    • Vm: Along with V and Km, defines a Michaelis-Menten elimination of maximum elimination rate Vm. Excludes k and Cl.
    • Km: Along with V and Vm, defines a Michaelis-Menten elimination of Michaelis-Menten constant Km. Excludes k and Cl.

Arguments for the peripheral compartments of a standard PK model

    • k12: Along with k21, defines a peripheral compartment 2 of input rate k12.
    • k21: Along with k12, defines a peripheral compartment 2 of output rate k21.
    • k13: Along with k31, defines a peripheral compartment 3 of input rate k13.
    • k31: Along with k13, defines a peripheral compartment 3 of output rate k31.

Arguments for the effect compartment of a standard PK model

    • {Cc, Ce} = pkmodel(…): The second output is the concentration within the effect compartment. Another name can be used.
    • ke0: Defines an effect compartment with transfer rate ke0 from the central compartment.

Additional possibilities

Knowing the label of the central compartment (cmt=1) and the administration type supported by the function pkmodel (type=1), one can build up a custom PK model by adding other PK elements to a base standard PK model. Referencing this label and administration type of value 1 allows to connect the additional PK elements.

5.[INDIVIDUAL]

Description

The [INDIVIDUAL] section is used to define a probability distribution for model parameters. It is used to model inter-individual variability for given parameters.

Scope

The [INDIVIDUAL] section is used in Mlxtran models for simulation with Mlxplore or Simulx. It is only needed for models that have parameters with inter-individual variability. Mlxtran models for Monolix do not need this section because the parameter distributions are defined via the user interface.

Inputs

The inputs for the [INDIVIDUAL] section are the parameters that are declared in the input = { } list of the [INDIVIDUAL] section. These parameters are obtained from the [COVARIATE] section or from the executing program that can be Mlxplore or a R-script in the case of Simulx.

Outputs

Every parameter that has been defined in the [INDIVIDUAL] section can be an output. Outputs from the [INDIVIDUAL] section are always an input for the [LONGITUDINAL] section. [INDIVIDUAL] output to [LONGITUDINAL] input matching is made by matching parameter names in the [INDIVIDUAL] section with parameters in the inputs = { } list of the [LONGITUDINAL] section.

Usage

The definition of probability distribution for a model parameters is done with the EQUATION: and DEFINITION: blocks. The EQUATION: block contains mathematical equations and the DEFINITION: block is used to definite probability distribution. The following syntax applies to define a probability distribution for the random variable X:

DEFINITION:
X = {distribution= distributionType, parameter1 = Var1, covariate = c, coefficient = beta, parameter = Var2}

The arguments to the probability distribution definition are

  • distributionType: is one of the following reserved keywords: normal, lognormal, logitnormal or probitnormal
  • parameter1: is one of the following reserved keywords: mean or typical
  • parameter2: is one of the following reserved keywords: sd or var
  • Var1: is a double number or a parameter
  • Var2: is a double number or a parameter
  • c = {..}: is a list of strings referring to the covariates
  • beta = {…}: is a list of strings referring to the covariate coefficients

The reserved keywords meanings are

  • normal: normal distribution: h(X)=X
  • lognormal: log-normal distribution: h(X)=\log(X)
  • logitnormal: logit-normal distribution:  h(X)=\frac{1}{1+e^{-X}}
  • probitnormal: probit-normal distribution: h(X)=\Psi^{-1}(X), where \Psi is the cumulative distribution function of the  {\cal N}(0, 1) distribution.
  • mean: is the mean of the normal distribution
  • typical: is the transformed mean
  • sd: is the standard deviation of the normal distribution. If no variability is required, the user can set “no-variability” and no-variability will be computed
  • var: is the variance of the normal distribution

These probability distribution are all Gaussian probability distributions that are defined through the existence of a monotonic transformation h such that h(X) is normally distributed. Notice that the mean, standard deviation, and variance refer to the normal distributed variable. In pharmacometrics it is more common to use the typical value of the distribution. This is achieved by using the keyword typical instead of mean in the definition of the random variable. The relationship between the mean value and the typical value is the following:

X = \{ \textrm{distribution}=\textrm{lognormal}, \textrm{typical}=X_{pop}, \textrm{sd}=\sigma\} \Leftrightarrow X = \{ \textrm{distribution}=\textrm{lognormal}, \textrm{mean}=\mu_{pop}, \textrm{sd}=\sigma\} \Leftrightarrow \quad \log(X) \sim {\cal N}(\mu_{pop},\sigma)

where  \mu_{pop},=\log(X_{pop}) . Thus, typical is in the variable referential, while mean is in the transformed referential.

General probability distributions and inclusion of covariates

Linear Gaussian models with covariates

A linear Gaussian statistical model for the variable X assumes that there exists a transformation h, a typical value X_{\rm pop}, a vector of individual covariates (c_{1}, \ldots c_{L}), a vector of coefficients (\beta_1, \ldots, \beta_L) and a random variable \eta normally distributed such that

 h(X) = h(X_{pop}) + \sum_{\ell=1}^L \beta_\ell \, c_\ell + \eta

This model can be implemented with Mlxtran, using the keywords typical, covariate and coefficient.

input = {Xpop, beta1, beta2, c1, c2, omega}
DEFINITION:
X = {distribution=lognormal, typical=Xpop, covariate={c1,c2}, coefficient={beta1,beta2}, sd=omega}

The keyword covariate is used to define the name of the covariates used in the correlation, and the coefficient keyword is used to complete the equation. Obviously, the number of parameters in the coefficient is equal to the number of covariates.

Non linear Gaussian model with covariates

A nonlinear Gaussian statistical model for the variable X assumes that there exists a transformation h, a vector of individual covariates (c_{1}, \ldots c_{L}), a vector of coefficients (\beta_1, \ldots, \beta_M), a function \mu and a random variable \eta normally distributed such that

 h(X) = \mu(c_{1}, \ldots c_{L},\beta_1, \ldots, \beta_M) + \eta

The mean of h(X) can be defined in a block DEFINITION:, with for example \mu(\beta_1,\beta_2,c_1,c_2)=\frac{\beta_1c_1}{\beta_2+c_2}

input = {beta1, beta2, c1, c2, omega}
EQUATION:
mu = beta1*c1/(beta2 + c2)

DEFINITION:
X = {distribution=lognormal, mean=mu, sd=omega}

Non Gaussian model with covariates

Non Gaussian model for X can be defined, at the condition that X can be defined as a nonlinear function of normally distributed random variables. For example, let

X = \frac{\beta_1 + \eta_1}{1+ \beta_2 \, e^{\eta_2}}

It is not possible to express explicitly the distribution of X as a transformation of a normal distribution. We therefore need a block EQUATION for implementing this model:

input = {beta1, beta2, omega1, omega2}
DEFINITION:
eta1 = {distribution=normal, mean=0, sd=omega1}
eta2 = {distribution=normal, mean=0, sd=omega2}

EQUATION:
X = (beta1 + eta1)/(1+beta2*exp(eta2))

Rules

  • When defining a distribution with covariate, one can note define numerically the coefficients. For example, if we consider X=X_{pop}+c+\eta, one should write
    input = {c}
    EQUATION:
    beta = 1
    DEFINITION : 
    X = {distribution=normal, typical=Xpop, covariate=c, coefficient=beta, sd=omega}
    

    and define \beta = 1 in the section <PARAMETER> or define it in an EQUATION: block. Otherwise, putting directly 1 instead of \beta in the distribution definition will lead to an error.

  • We strongly advise to define the distribution in the more synthetic way. If for example, you want to define a log-normally distributed volume with a dependence w.r.t. the weight V=V_{pop}(w/70)^{\beta}, we encourage you not to define a lot of equations but to summarize it in the definition as for example
    input = {Vpop, w, beta}
    EQUATION:
    cov = w/70
    
    DEFINITION:
    V = {distribution=normal, typical=Vpop, covariate=cov, coefficient=beta, sd=omega}

6.[COVARIATE]

Description

The section [COVARIATE] defines the probability distribution of the covariates.

Scope

The [COVARIATE] section is used in Mlxtran models for simulation with Mlxplore or Simulx. It is only needed for models that have parameters that depend on covariates. Mlxtran models for Monolix do not need this section because the covariate model is defined via the user interface.

Inputs

Inputs to the [COVARIATE] section are provided through the list input = { }. The inputs are typically the list of parameters that are required for defining the covariate distributions (mean, standard deviation, . . . ). The parameters in the input list are provided through Mlxplore or through the calling R-script in the case of Simulx.

[COVARIATE]
input = {weight_pop, omega_weight}

Outputs

Every variable that has been defined in the [COVARIATE] section can be an output. Outputs from the [COVARIATE] section can be an input for the [INDIVIDUAL] section but not the [LONGITUDINAL] section. [COVARIATE] output to [INDIVIDUAL] input matching is made by matching any parameter names in the [COVARIATE] section with parameters in the inputs = { } list of the  [INDIVIDUAL] section.

Usage

All distributions that can be used to define the covariate distribution are listed in link.

A typical [COVARIATE] section has the following syntax. Here a covariate c is defined such that c = 0 if z <= -0.2533 and c = 1 otherwise, where z ~ N(0, 1). The inputs of the covariate section are weight_pop, omega_weight and the output is cz.

[COVARIATE]
     input = {weight_pop, omega_weight}
     DEFINITION: 
          z = {distribution=normal, mean=weight_pop, sd=omega_weight}
     EQUATION:
          if z<= -0.2533 ; P(z<=-0.2533)=0.4 
               cz = 0
          else 
               cz = 1
          end
          c=cz

7.Language reference

An overview on the principle of reserved keywords in Mlxtran is given in the following section: Keywords in Mlxtran. More details are provide by keyword type in the following summaries:

7.1.Keywords

Some keywords manage the complexity of the deterministic computations. Since they are used by the language, these keywords are not available for re-definition or overloading.

Keywords used to define sections in the Mlxtran model file

Here is the list of keywords reserved for the sections definition:

  • <DESCRIPTION>: This is used for the description of the project. This can be interesting to use it when you share and/or when you want to keep the history of the projects. This section is optional.
  • <DESIGN>: This section is used for the definition of the design (administration and treatment). This section is optional.
  • <MODEL> : This section is used for the model description. It contains the structural model in [LONGITUDINAL] but can also contain [INDIVIDUAL], [COVARIATE]. This section is mandatory.
  • <OUTPUT>: This section is used to define the outputs you wan to look at. This defines the name and the time you want to see the outputs. This section is mandatory.
  • <PARAMETERS>: This section is used to define the parameters. This section is mandatory. However, the model exploration is done by playing with the parameters. Therefore, you always have it.
  • <RESULTS>: This section is used to define the graphical results. It defines the graphics proposed by Mlxplore and all the associated settings. This section is mandatory.
  • <SETTINGS>: This section is used to define the settings. It allows to define the iiv actions and the percentiles configurations. This section is mandatory.

Keywords used to define subsections

Here is the list of keywords reserved for the subsections definition:

  • [ADMINISTRATION]: This keyword is used to define administrations in section <DESIGN>.
  • [COVARIATE]: This keyword is used to open the section <MODEL> for the definition of the covariates in the model. Covariates are variables that are not part of the main experimental manipulation but has an effect on the dependent variable.
  • [GRAPHICS]: This keyword is used to define the graphics in the section <RESULTS> (to define what and how to display it) and in the section <SETTINGS> (to define the iiv actions and the percentiles configurations).
  • [INDIVIDUAL]: This keyword is used to open the section for the definition of the individual parameters in the section model <MODEL>.
  • [LONGITUDINAL]: This keyword is used to open the section for the structural model description in the section <MODEL>.
  • [TREATMENT]: This keyword is used to define treatments (concatenation of administrations) in section <DESIGN>.

Keywords used to define blocks

Here is the list of keywords reserved for elements in the subsections definition:

  • DEFINITION: For sections [INDIVIDUAL], [COVARIATE], this keyword allows the explicit definition-based descriptions of probability distributions in a block.
  • EQUATION: In each section, this keyword allows flexible equation-based descriptions implemented in a block.
  • PK: In section [LONGITUDINAL], this keyword allows the used of defined macros for PK models.
  • OUTPUT: In section [LONGITUDINAL], this keyword allows the definition of the outputs under consideration.

Dedicated keywords used in each section

Section <MODEL>
In this section, only the word file is used as a keyword. It is used as a keyword to make a link to an external model file as follows

file='./path to my model'

Full list of keywords

Here is the full list of keywords in Mlxtran except

  • the keywords defined in the top of the page,
  • the keywords used for distribution definition (that are listed here)
  • the keywords used for classical mathematical definition (that are listed here)
Name    Meaning where can it be used ? link
absorption Macro used for defining the absorption process in a longitudinal model In subsection [LONGITUDINAL] after PK: link
adm Type of administration (type and adm are equivalent). In argument of the following macros: absorption, depot, iv and oral  
amount When it is used in the longitudinal model, it corresponds to the name of variable defined as the amount within the compartment
When it is used in a treatment or an administration, it corresponds to the amount(s) of drug (in Mlxplore and Simulx).
In the first use, in argument of the following macros: compartment and peripheral
In the second one, in the <DESIGN> section in Mlxplore and in the treatment definition in Simulx.
Mlxplore link, Simulx link
amtDose Amount of the last administered dose. This is a step function and is null before the first dose. In the longitudinal model, in subsection [LONGITUDINAL], in a block EQUATION: link
band Extended logit error model t(y) = \log(\frac{y-A}{B-y}) In an error model, in subsection [LONGITUDINAL], in a definition EQUATION: link
bsmm Mixture of continuous observations. It is a mixture between subjects model mixtures (BSMM). It assumes no inter individual variabilities for the proportions of each group (ı.e. the probabilities to belong to the different groups). It is relevant only for Monolix. In the longitudinal model, in subsection [LONGITUDINAL], in a block EQUATION:  
categorical Type of observation model. In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: after a type= link
categories List of the available ordered categories for a categorical observation. They are usually represented by increasing successive integers. In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is a category link
cmt Label of the compartment. In argument of the following macros: absorption, compartment, depot, effect, elimination, iv, oral
coefficient Coefficient under consideration for a distribution definition dependaing on covariates In any distribution definition in a block DEFINITION: link
combined1 Combined error model y = f + (a+b*f)e In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is continuous link
combined1c It corresponds to a combined error model y = f + (a+b*f^c)e In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is continuous link
combined2 Combined error model y = f + a*e_1+b*f*e_2 In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is continuous link
combined2c Combined error model y = f + a*e_1+b*f^c*e_2 In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is continuous link
compartment Macro used for defining a compartment In subsection [LONGITUDINAL] after PK: link
concentration Name of the variable defined as the concentration within the compartment In argument of the following macros: compartment, effect, peripheral
constant Constant error model y = f + a*e In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is continuous link
continuous Type of observation model. In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: after a type= link
count Type of observation model. In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: after a type= link
covariate Covariate under consideration for a distribution definition In any distribution definition in a block DEFINITION: link
delay It corresponds to delay function to define DDE. In the longitudinal model, in subsection [LONGITUDINAL], in a block EQUATION: link
dependence It corresponds to the label used to defined that an observation variable for ordered categorical data modelled as a Markov chain. In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is categorical link
depot It corresponds to an absorption targeting a depot. A component of an ODE system is defined as the target depot for the doses. In subsection [LONGITUDINAL] after PK: link
effect This macro defines an effect compartment. It is linked to a simple compartment and used through the variable for its effect concentration. In subsection [LONGITUDINAL] after PK: link
elimination This macro defines an elimination process. In subsection [LONGITUDINAL] after PK: link
else It is part of a conditional statement. A conditional statment can be built by combining the keywords if, elseif, else and end. In a block EQUATION:  
elseif It is part of a conditional statement. A conditional statment can be built by combining the keywords if, elseif, else and end. In a block EQUATION:  
end It is part of a conditional statement. A conditional statment can be built by combining the keywords if, elseif, else and end. In a block EQUATION:  
errorModel It corresponds to the label to define an error model for a continuous observation model In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is continuous link
event Type of observation model. In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: after a type= link
eventType Label to define the event type for an event observation model. It allows to define if the exact time of the events or censored per interval is observed. In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is an event link
exponential Exponential error model y = fe^{ae} In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is continuous link
from Label of the source compartment for the transfer. In argument of the following macro: transfer link
hazard Hazard function In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is an event link
if It is part of a conditional statement. A conditional statment can be built by combining the keywords if, elseif, else and end. In a block EQUATION:  
inftDose The keyword inftDose defines the infusion time of the last administered dose. This is a step function. The rate of the final absorption can be different from the rate of the administration process. It is null before the first dose. In the longitudinal model, in subsection [LONGITUDINAL], in a block EQUATION: link
input It corresponds to the definition of the inputs in a subsection In subsections [LONGITUDINAL], [INDIVIDUAL], and [COVARIATE] link
intervalCensored Argument of eventType. In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is an event link
intervalLength Label to length of censoring intervals in an event observation model. It is useful for simulation only, In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is an event link
iv The macro iv defines an absorption for intravenous doses. Doses without an administration rate or infusion time are instantaneously absorbed within the associated compartment, as an IV bolus. In subsection [LONGITUDINAL] after PK: link
linear It is an argument of odeType= and allows to define the dynamical system as linear In the longitudinal model, in subsection [LONGITUDINAL], in a block EQUATION: link
Markov It corresponds to the dependence of a categorical observation model. It allows to define that the observation model is based on a Markov chain In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: after a dependence= link
maxEventNumber Maximum number of events in an event observation model. It is useful for simulation only In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is an event link
mean Mean of the associated normal distribution. In any distribution definition in a block DEFINITION: link
nonStiff It is an argument of odeType= and allows to define the dynamical system is nonStiff and thus yields to an adapted numerical scheme for the resolution In the longitudinal model, in subsection [LONGITUDINAL], in a block EQUATION: link
odeType It is the label that allows to define the type of ODE. In the longitudinal model, in subsection [LONGITUDINAL], in a block EQUATION: link
oral It is a macro used for defining the absorption process in a longitudinal model In subsection [LONGITUDINAL] after PK: link
output It allows to define the outputs of a structural model In the longitudinal model, in subsection [LONGITUDINAL], in a block OUTPUT:
P The majuscule P corresponds to the definition of a probability In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: link
p It corresponds to the bio availability in an absorption process In argument of the following macro: absorption, depot, iv, and oral
peripheral The macro peripheral defines a peripheral compartment. It is equivalent to a simple compartment with two transfers of amount towards and from another compartment. In subsection [LONGITUDINAL] after PK: link 
PK It defines where the macros are defined In subsection [LONGITUDINAL] link
pkmodel It defines the macro pkmodel In subsection [LONGITUDINAL], in a block PK: or in a block EQUATION: link 
prediction It corresponds to the name of the base prediction variable In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is continuous link
proportional It corresponds to a proportional error model y = f +b*fe In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is continuous link
proportionalc It corresponds to a proportional error model y = f +b*f^ce In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is continuous link
regressor It declares the input regression values. In the longitudinal model, in subsection [LONGITUDINAL], after the input definition link 
rightCensoringTime Right censoring time of events. It is useful for simulation only In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: when the type of observation is an event link 
sd Standard deviation of the associated normal distribution (standardDeviation and sd are synonymous keywords) In any distribution definition in a block DEFINITION: link 
standardDeviation Standard deviation of the associated normal distribution (standardDeviation and sd are synonymous keywords) In any distribution definition in a block DEFINITION: link 
stiff It is an argument of odeType= and allows to define the dynamical system is nonStiff and thus yields to an adapted numerical scheme for the resolution In the longitudinal model, in subsection [LONGITUDINAL], in a block EQUATION: link 
t time In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION:  
t_0 Initialization time for the equations In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION:  
t0 Initialization time for the equations In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION:  
table This keywords declares the variables to record in tables. In the longitudinal model, in subsection [LONGITUDINAL], in a block OUTPUT:
target Name of the component of an ODE system that is shifted by the absorption. In argument of the following macro: depot  link
tDose The keyword tDose defines the time of the last administered dose. This is a step function. Its value is unaffected by any lag time Tlag. Indeed, a lag time targets the dose absorption. It is null before the first dose. In the longitudinal model, in subsection [LONGITUDINAL], in a block EQUATION: link 
to Label of the target compartment for the transfer In argument of the following macro: transfer link
transfer The macro transfer defines a transfer of amount from a first compartment to a second one. In subsection [LONGITUDINAL] after PK: link
transitionRate Transition rate departing from a given category to another one. It is used in the definition of a categorical observation model. In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION: link
type It allows the type of observation model. It can be continuous, count, categorical, or event. In the longitudinal model, in subsection [LONGITUDINAL], in a block DEFINITION:
typical It corresponds to the typical value during a distribution definition In any distribution definition in a block DEFINITION: link
use It allows to define the regressor in the longitudinal subsection. Regressors are defined as inputs at the beginning and thus are specified as regressors using use= In the longitudinal model, in subsection [LONGITUDINAL], after the input definition link
var Variance of the associated normal distribution (variance and var are synonymous keywords) In any distribution definition in a block DEFINITION: link 
variance Variance of the associated normal distribution (variance and var are synonymous keywords) In any distribution definition in a block DEFINITION: link 
volume It corresponds to the name of predefined variable to use as the volume of the compartment In argument of the following macros: compartment, effect, peripheral  
wsmm Mixture of continuous observations. It is a mixture within subjects. In the longitudinal model, in subsection [LONGITUDINAL], in a block EQUATION:  

7.2.Probability distribution summary

This page summarize the distribution available in Mlxtran and their use.

Normal distribution and the associated transformed.

The first class of distribution is the normal distribution and the associated transformation. Then, we have

  • Normal distribution, used with keyword normal (h(X)=X)
    y_norm = {distribution=normal, mean=0, sd=1}
  • Log-normal distribution, used with keyword lognormal (h(X)=log(X))
    y_ln = {distribution=lognormal, typical=1, sd=1}
  • Logit-normal distribution, used with keyword logitnormal (h(X)=\frac{1}{1+e^{-X}})
    y_lgn = {distribution=logitnormal, typical=0, sd=1}
  • Probit-normal distribution, used with keyword probitnormal (h(X)=\Psi^{-1}(X), where \Psi is the cumulative distribution function of the  {\cal N}(0, 1) distribution)
    y_pbn = {distribution=probitnormal, typical=.5, sd=1}

Notice that to clarify the use between mean and typical, additional keywords

  • meanlog, meanlogit, and meanProbit can be used to replace mean for the log-normal, the logit-normal and the probit-normal distribution respectively.
  • sdlog, sdlogit, and sdprobit can be used to replace sd for the log-normal, the logit-normal and the probit-normal distribution respectively.

This leads to a possibility to define a distribution as follows

  • Log-normal distribution,
    y_ln = {distribution=lognormal, meanlog=1, sdlog=1}
  • Logit-normal distribution,
    y_lgn = {distribution=logitnormal, meanlogit=.5, sdlogit=1}
  • Probit-normal distribution,
    y_pbn = {distribution=probitnormal, meanProbit=0.5, sdProbit=1}

These distributions can be used in Mlxplore, Monolix, and Simulx.

Continuous distribution available for simulation.

These are the following additional distribution available for simulation purpose.

  • Exponential distribution, used with keyword exponential,
    y_exp = {distribution=exponential, rate=0.7}
  • Gamma distribution, used with keyword gamma,
    y_gamma = {distribution=gamma, shape=2, scale=0.5}
  • Weibull distribution, used with keyword weibull,
    y_weibull = {distribution=weibull, shape=0.75, scale=1.2}
  • ExtremeValue distribution, used with keyword extremeValue,
    y_ev = {distribution=extremeValue,  location=-10, scale=1.8}
  • ChiSquared distribution, used with keyword chiSquared,
    y_cs = {distribution=chiSquared, df=2}
  • Cauchy distribution, used with keyword cauchy,
    y_cauchy = {distribution=cauchy, location=-5.2, scale=2.7}
  • FisherF distribution, used with keyword fisherF,
    y_fisherF = {distribution=fisherF, df1=10, df2=9}
  • StudentT distribution, used with keyword studentT,
    y_studentT = {distribution=studentT, df=2}

These distributions can be used in Mlxplore and Simulx.

Discrete distribution available for simulation.

These are the following additional distribution available for simulation purpose

  • Bernoulli distribution, used with keyword bernoulli,
    y_ber = {distribution=bernoulli, prob=0.3}
  • Discrete uniform distribution, used with keyword discreteUniform,
    y_du = {distribution=discreteUniform, min=-4, max=2}
  • Binomial distribution, used with keyword binomial,
    y_bi = {distribution=binomial, size=30, prob=0.7}
  • Geometric distribution, used with keyword geometric,
    y_ber = {distribution=geometric, prob=0.2}
  • Negative binomial distribution, used with keyword negativeBinomial,
    y_nb = {distribution=negativeBinomial, size=3, prob=0.1}
  • Poisson distribution, used with keyword poisson,
    y_nb = {distribution=poisson, lambda=0.1}

These distributions can be used only in Simulx, as Mlxplore can not manage discrete data.

7.3.Mathematical functions

The following usual mathematical functions are available. They perform scalar operations, either on integers or real numbers. These operations are performed using a double precision for their floating-point implementation.

 

Function Syntax Remarks
Smallest value min(a,b)
Largest value max(a,b)
Absolute value abs(a,b)
Square root sqrt(a)
Exponential exp(a)
Natural logarithm log(a)
Common logarithm log10(a)
Logistic function logit(a)
Inverse of the logistic function invLogit(a)
Probit function probit(a) Aliases: norminv, qnorm.
Normal CDF normcdf(a) Alias: pnorm.
Sine sin(a)
Cosine cos(a)
Tangent tan(a)
Inverse Sine asin(a)
Inverse Cosine acos(a)
Inverse Tangent atan(a)
Hyperbolic Sine sinh(a)
Hyperbolic Cosine cosh(a)
Hyperbolic Tangent tanh(a)
Four quadrant inverse tangent atan2(a,b)
Logarithm of gamma function gammaln(a) Alias: lgamma
Downward rounding floor(a)
Upward rounding ceil(a)
Factorial factorial(a)
Logarithm of factorial factln(a)
Remainder after division rem(a)

7.4.Operators

The following operators are available, under their mathematical acceptation.

Arithmetic operators
The arithmetic operators perform operations on real numbers. These operations are performed using a double precision for their floating-point implementation. The specific operations on integers have a function call syntax, e.g. factorial.

Operator Syntax Remarks
Equal a=b Defines variables
Addition a+b
Subtraction a-b
Multiplication a*b
Division a/b
Power a^b Right associative
Unitary plus +a
Unitary minus -a

Logical operators
The logical operators perform operations on boolean values. They appear as conditions within conditional statements.

Operator Syntax Other possible syntax
Negation ~a !a
Or a|b a||b
And a&b a&&b

Relational operators
The relational operators perform operations on real numbers. These operations are performed using a double precision for their floating-point implementation.

Operator Syntax Other possible syntax
Equal to a==b
Not equal to a~=b a!=b
Greater than a>b
Less than a<b
Greater or equal to a>=b
Less or equal to a<=b  2

7.5.Can I use informations from the treatment in my longitudinal model ?

Doses from the design can also be referenced through several matching independent variables. This allows for some direct calculation, especially for modelling custom single dose absorptions. Doses aren’t discriminated according to their administration types here. These values are directly related to the design, they are unaffected by the PK elements.

Time of the last administered dose

The keyword tDose defines the time of the last administered dose. This is a step function. Its value is unaffected by any lag time Tlag. Indeed, a lag time targets the dose absorption. tDose is null before the first dose.

Amount of the last administered dose

The keyword amtDose defines the amount of the last administered dose. This is a step function. Its value is unaffected by any proportional factor p, as this keyword targets the absorbed amount by the end of the whole absorption process. amtDose is null before the first dose.

Infusion time of the last administered dose

The keyword inftDose defines the infusion time of the last administered dose. This is a step function. Its value is unaffected by any proportional factor p, as this keyword targets the absorbed amount by the end of the whole absorption process. The rate of the final absorption can be different from the rate of the administration process. inftDose is null before the first dose.

Suggest Edit