Select Page

# Mlxtran User Guide

### 1.Mlxtran, a human readable language for model description

This documentation is for Mlxtran for the Monolix Suite starting at 2016R1

## 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 Language Cheat Sheet

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

### 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 (which will be matched to the data), 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 result folder of Monolix.
Note that it is not allowed to do calculations directly in the output or table statement.

### 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 and DDEs. 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:

### Structural model description using PK: and EQUATION:

Administration definition and PK modelling with the PK: block: Macros for flexible PK model definition
Dynamical system modeling with the EQUATION: block.

### Observation model description using DEFINITION:

Observation models for continuous data
Observation models for discrete data

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

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 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 = t0  by the initial condition x_0, i.e. x(t0)=x_0 and by the differential equation after t0.

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.

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, a differential equation needs to be defined.
• Initial conditions can depend on
• time
• an input parameter. Therefore, initial condition values can also be estimated in Monolix.
• a regressor value. In that case, again, a differential equation needs to be defined.
• 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<=10, 2 if t<20 and 3 otherwise, write

if t<=10
c = 1
elseif t<20
c = 2
else
c = 3
end


Derivatives cannot be written within an if-else-end structure. Instead, intermediate variables should be used. For example, if a derivative of x over time should be 1 if t<=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.

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.

Example of regression variables used in Monolix

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

### 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 u(y) = u(f) + g e is considered where e is a sequence of independent random variables normally distributed with mean 0 and variance 1, and u is the transformation associated with the distribution of the observations. It is also possible to assume that the residual errors are correlated. Following is a list of distributions and residual error models that can be selected in the Monolix user interface.

#### Residual error models

• constant: constant error model $y = f + ae$
• proportional: proportional error model + power $y = f + bf^ce$
• combined1: combined error model + power $y = f + (a + b f^c)e$
• combined2: 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)

Notice that the parameter c is fixed to 1 by default. However, it can be unfixed and estimated.

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.

#### Distributions

• normal: u(y) = y. This is equivalent to no transformation.
• lognormalu(y) = log(y). Thus, for a combined error model for example, the corresponding observation model writes $$\log(y) = \log(f) + (a + b\log(f)) \varepsilon$$. It assumes that all observations are strictly positive. Otherwise, an error message is thrown. In case of censored data with a limit, the limit has to be strictly positive too.
• logitnormalu(y) = log(y/(1-y)). Thus, for a combined error model for example, corresponding observation model writes $$\log(y/(1-y)) = \log(f/(1-f)) + (a + b\log(f/(1-f)))\varepsilon$$. It assumes that all observations are strictly between 0 and 1. However, we can modify these bounds to define the logit function between a minimum and a maximum, and the function u becomes u(y) = log((y-y_min)/(y_max-y)). Again, in case of censored data with a limit, the limits has to be strictly in the proposed interval too.

Hence, the following observation models can be defined with a combination of distribution and residual error model:

• exponential error model: $u(y) = \log(y)$ and $y = fe^{ae}$ constant error model and a lognormal distribution
• logit error model $u(y) = \log(\frac{y}{1-y})$ constant error model and a logitnormal distribution
• band(0,10): $u(y) = \log(\frac{y}{10-y})$ constant error model and a logitnormal distribution with min and max at 0 and 10 respectively
• band(0,100): $u(y) = \log(\frac{y}{100-y})$ constant error model and a logitnormal distribution with min and max at 0 and 10 respectively

### 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 models. For example, in the previous Concentration/PCA example, we can not replace a2 by a1.

### 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)}


### 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}


Using that definition, the distribution associated to the parameters are

• Normal for th1. Elsewise, it implies that logit(P(level <=0))>0 and thus that P(level <=0).
• Lognormal for th2 and th3 to make sure that P(level <=1)>P(level <=0) and P(level <=2)>=P(level <=1) respectively.

### 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}


Using that definition, the distribution associated to the parameters are

• Logitnormal for a1 and a2 to make sure that the initial probability are well defined.
• Normal for a11, a21, and a31 to make sure that the probability is in [0, 1].
• Lognormal for a12, a22, and a32 to make sure that the cumulative probability is increasing.

### 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}


### 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}



### TTE model library

A library of typical parametric models is provided in Monolix: Complete description of the TTE model library.

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

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

• Compartment macros
• Elimination macros

The following two links provide overview tables:

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

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=, volume= and concentration= are necessarily strings.

### Purpose

The peripheral macro 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 referenced by its label. If the amount or concentration of the peripheral compartment are not outputted, then they do not need to be defined.

### Arguments

Arguments for macro peripheral are:

• kij or ki_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 kj_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 peripheral compartment.

### Example

PK:
; definition of a peripheral compartment with cmt=2 with rates k12 and k21,
; 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.

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

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

### 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, in particular as it allows to use the analytical solution, which is not the case with 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)
oral(cmt=1,ka=1)
transfer(from=1, to=2, kt)

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

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

### 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 administrations from the data set are linked with the model variables. It is the only macro that can be used with ODEs for administration without defining a compartment. With the macro depot, a bolus, an infusion (with INFUSION RATE or INFUSION duration defined in the data set), a zero order absorption, 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, infusions (with INFUSION RATE or INFUSION duration defined in the data set), zero-order absorptions, and first-order absorptions. 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:

• adm: Administration type of doses subject to the absorption process. Its default value is 1. Alias: type. Thus, when defining a treatment in Mlxplore for example, instead of defining 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 Ac, 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 be defined with a rate or an infusion timing from the data set (RATE and TINF column-types in the data set). The rules are the same as for the iv macro.

### Arguments

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

• adm: Administration type of doses subject to the absorption process. Its default value is 1. Alias: type. Thus, when defining a treatment in Mlxplore for example, instead of defining a target, the user should define an administration 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(adm=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):

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 mixed absorptions

Some drugs can exhibit atypical absorption profiles with for instance a zero-order absorption followed by a first-order absorption, or first and zero-order simultaneously.

Sequential absorption, zero-order followed by first-order

In the example below, a fraction F1 of the drug is absorbed via a zero-order process for a duration Tk0. The remaining fraction 1-F1 is then absorbed via a first-order process, which starts with a lag-time Tk0 (i.e at the end of the zero-order absorption phase).

PK:
absorption(adm=1, cmt=1, ka, p=1-F1, Tlag=Tk0)

Simultaneous first-order and zero-order absorption

In the example below, a fraction F1 of the drug is absorbed via a first-order process (with absorption rate ka). Simultaneously the remaining fraction 1-F1 is absorbed via a zero-order process.

PK:
absorption(adm=1, cmt=1, Tk0, p=1-F1)

A lag time for one or the other process can be added if necessary.

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)
elimination(cmt=1, k=1)

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

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

EQUATION:
ddt_A1 = 0
ddt_A2 = 0
ddt_A3 = 0

<DESIGN>

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

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.

### 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.
• adm: Administration type of doses subject to the absorption process. Its default value is 1. Alias: type. 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


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)
elimination(cmt=1, k=1)

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

<DESIGN>

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

### 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 adm= 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

### Purpose

The bioavailability parameter p, available in the administration macros (‘depot’, ‘absorption’, and ‘iv’), defines the fraction of 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 a process with mixed zero and first-order absorptions.

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

<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:

### 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)

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

<DESIGN>

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

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

Example: PK model with dual elimination pathways
The following model implemented with PK macros includes two compartments, an oral absorption and a dual elimination pathway with parallel linear and Michaelis-Menten eliminations. An equivalent model, implemented with ODEs, is defined in the TMDD model library: it corresponds to the Michaelis-Menten approximation of a TMDD model.

[LONGITUDINAL]
input = {ka, V, Vm, Km, Cl, Q, V2}

PK:
kel = Cl/V
k12 = Q/V
k21 = Q/V2
compartment(cmt=1, concentration=Cc, volume=V)
absorption(cmt=1, ka)
peripheral(k12, k21)
elimination(cmt=1, k=kel)
elimination(cmt=1, Vm, Km)

OUTPUT:
output={Cc}



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

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

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

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.

### 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 section or from the executing program that can be Mlxplore or an 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 parameter is done with the EQUATION: and DEFINITION: blocks. The EQUATION: block contains mathematical equations and the DEFINITION: block is used to definite probability distributions. The following syntax applies to define a probability distribution for the random variable X:

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

The arguments to the probability distribution definition are

• distributionType: is one of the following reserved keywords: normal, lognormal, logitnormal, or probitnormal. For use in Simulx, the keyword uniform is also accepted.
• 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
• min: the lower bound of the interval for logitnormal or probitnormal distributions (default is 0)
• max: the upper bound of the interval for logitnormal or probitnormal distributions (default is 1)

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:

$\phantom{abc} 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 \log(X) \sim {\cal N}(\mu_{pop},\sigma^2)$

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

#### Examples

• The parameter ka below is defined with a log-normal distribution, a typical value ka_pop and a standard deviation for the random effect omega_ka:

ka = {distribution=logNormal, typical=ka_pop, sd=omega_ka}
• The parameter F below is defined with a logit-normal distribution in the interval [0,1], a typical value F_pop and no random effect.

F = {distribution=logitNormal, typical=F_pop, no-variability}
• The parameter V below is defined with a logit-normal distribution in the interval [0.2,5], a typical value V_pop and a standard deviation for the random effect omega_V:
V = {distribution=logitNormal, min=0.2, max=5, typical=V_pop, sd=omega_V}
• The parameter fu below is defined with a uniform distribution in the interval [0.2,0.6] (not accepted in Monolix):

fu = {distribution=uniform, min=0.2, max=0.6}

### 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 not 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}

### 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 section in Mlxplore and in the treatment definition in Simulx. 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: standardDeviation Standard deviation of the associated normal distribution (standardDeviation and sd are synonymous keywords) In any distribution definition in a block DEFINITION: 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: 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 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: variance Variance of the associated normal distribution (variance and var are synonymous keywords) In any distribution definition in a block DEFINITION: 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:

### 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)
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
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

### 8.Examples

Different examples of full models are presented here to show how to use the Mlxtran language to define a model. When relevant, an Mlxplore project is also given, for model exploration.