Monolix 4.3 User Guide

Monolix 4.3 User Guide
Monolix
Version 4.3.3
September 2014
A software for the analysis of nonlinear mixed effects models
Maximum likelihood estimation
Model selection
Hypothesis testing
Graphical analysis
Data simulation
...
I
S
I
M
U
M
L
P
A
M
S
T
O
C
H
A
S
T
I
C
E
M
R
T
A
N
M
C
M
C
E
D
A
N
N
T
R
O
P
O
E
S
A
E
M
L
S
A
H
M
M
P
L
A
L
I
N
G
I
S
I
N
G
Monolixr (MOdèles NOn LInéaires à effets miXtes) is a platform of reference for modelbased drug development. It combines the most advanced algorithms with unique ease of use.
Pharmacometricians of preclinical and clinical groups can rely on Monolix for population analysis and to model PK/PD and other complex biochemical and physiological processes.
Monolix is an easy, fast and powerful tool for parameter estimation in non-linear mixed effect
models, model diagnosis and assessment, and advanced graphical representation.
Monolix is the result of a ten years research program in statistics and modeling, led by
INRIA (Institut National de la Recherche en Informatique et Automatique) on non-linear mixed
effect models for advanced population analysis, PK/PD, pre-clinical and clinical trial modeling
& simulation.
Monolix is based on the Matlab scientific environment published by Mathworks. Monolix
is also available as a full-featured standalone software compiled with Matlab libraries, and
therefore does not require to purchase Matlab licences.
Contents
1 Introduction
1.1 The objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2 Installing and running Monolixr
2.1 Downloading packages . . . . . .
2.2 Installation . . . . . . . . . . . .
2.2.1 Prerequisites . . . . . . .
2.2.2 About Installer . . . . . .
2.2.3 Directory structure . . . .
2.2.4 Running Monolix . . .
2.2.5 Installation use cases . . .
2.2.6 License . . . . . . . . . .
2.3 ChangeLog . . . . . . . . . . . .
2.4 Troubleshooting . . . . . . . . . .
2.4.1 Downloading Monolix .
2.4.2 Running Monolix . . .
8
8
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
10
10
12
12
12
14
15
16
19
30
41
41
42
3 Using Monolix
3.1 Introduction . . . . . . . . . . . . . . . . . . . . . .
3.1.1 The theophylline example . . . . . . . . . .
3.2 The main window . . . . . . . . . . . . . . . . . . .
3.3 The “Data and Model” frame . . . . . . . . . . . .
3.3.1 The data . . . . . . . . . . . . . . . . . . .
3.3.2 The model function . . . . . . . . . . . . .
3.3.3 The covariate model . . . . . . . . . . . . .
3.3.4 Creating and transforming covariates . . . .
3.3.5 Distribution of the individual parameters .
3.3.6 The covariance model of the random effects
3.3.7 The observations model . . . . . . . . . . .
3.4 The “Initialization” frame . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
43
43
43
44
46
46
48
49
50
52
52
53
53
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
CONTENTS
3.5
3.6
3.7
3.8
3.9
3.10
3.11
3.12
3.13
3.4.1 Check initial fixed effects . . . . . . . . .
3.4.2 Use the last estimates . . . . . . . . . . .
The “Algorithm” frame . . . . . . . . . . . . . . .
The “Results” frame . . . . . . . . . . . . . . . .
Executing tasks . . . . . . . . . . . . . . . . . . .
3.7.1 Estimation of the population parameters .
3.7.2 Estimation of the standard errors . . . . .
3.7.3 Estimation of the individual parameters .
3.7.4 Estimation of the log-likelihood . . . . . .
3.7.5 Computing results . . . . . . . . . . . . .
3.7.6 Running several algorithms . . . . . . . .
3.7.7 Algorithms convergence assessment . . . .
Plots and results . . . . . . . . . . . . . . . . . .
3.8.1 The graphics . . . . . . . . . . . . . . . .
3.8.2 The tables . . . . . . . . . . . . . . . . . .
3.8.3 The graphics menu bar . . . . . . . . . .
3.8.4 Main interface Graphics Menu . . . . . .
3.8.5 Stratify . . . . . . . . . . . . . . . . . . .
3.8.6 Settings . . . . . . . . . . . . . . . . . . .
Testing hypotheses . . . . . . . . . . . . . . . . .
Simulation . . . . . . . . . . . . . . . . . . . . . .
Publishing the outputs . . . . . . . . . . . . . . .
The results folder . . . . . . . . . . . . . . . . . .
Settings . . . . . . . . . . . . . . . . . . . . . . .
3.13.1 The population parameters estimation . .
3.13.2 The individual parameters estimation . .
3.13.3 The log-likelihood . . . . . . . . . . . . .
3.13.4 The results . . . . . . . . . . . . . . . . .
3.13.5 Predefined scenarios . . . . . . . . . . . .
4 Advanced features
4.1 Libraries of models . . . . . . . . . . . . . . .
4.2 Pharmacokinetic and pharmacodynamic data
4.3 Using priors on a fixed effect . . . . . . . . .
4.4 Categorical covariate model . . . . . . . . . .
4.5 Model with censored data . . . . . . . . . . .
4.5.1 Modeling BLQ data . . . . . . . . . .
4.5.2 Modeling interval censored data . . .
4.6 Model with inter-occasion variability . . . . .
4
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
54
54
54
55
56
57
58
61
62
63
64
64
66
66
74
74
74
79
80
85
87
88
88
91
91
91
92
92
92
.
.
.
.
.
.
.
.
93
93
93
94
95
96
96
97
97
Monolix 4.3.3
CONTENTS
4.7
4.8
4.9
4.10
4.11
4.12
4.13
4.14
Discrete data models . . . . . . . . . . . . . . . . . . . . .
4.7.1 ordered categorical data models . . . . . . . . . . .
4.7.2 count data models . . . . . . . . . . . . . . . . . .
4.7.3 discrete Markov models . . . . . . . . . . . . . . .
4.7.4 hidden Markov models . . . . . . . . . . . . . . . .
4.7.5 repeated time to event models (RTTE) . . . . . .
4.7.6 joint modelling of continuous and discrete outputs
Complex residual error models . . . . . . . . . . . . . . .
4.8.1 autocorrelated residual errors . . . . . . . . . . . .
4.8.2 residual errors for bounded data . . . . . . . . . .
Complex PK models . . . . . . . . . . . . . . . . . . . . .
4.9.1 Complex administrations . . . . . . . . . . . . . .
4.9.2 Steady-state . . . . . . . . . . . . . . . . . . . . . .
Mixture models and model mixtures . . . . . . . . . . . .
4.10.1 Mixture models . . . . . . . . . . . . . . . . . . . .
4.10.2 Model mixtures . . . . . . . . . . . . . . . . . . . .
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Monolix in Matlab command line or scripts . . .
Full script projects . . . . . . . . . . . . . . . . . . . . . .
Preferences . . . . . . . . . . . . . . . . . . . . . . . . . .
5 PerlMLX and the batch mode
5.1 Introduction . . . . . . . . . . . . . . . . . . . .
5.2 Environment variables . . . . . . . . . . . . . .
5.3 HMI mode . . . . . . . . . . . . . . . . . . . . .
5.4 Standalone mode . . . . . . . . . . . . . . . . .
5.4.1 Options . . . . . . . . . . . . . . . . . .
5.4.2 Setting up the configuration file . . . . .
5.5 Batch mode in depth . . . . . . . . . . . . . . .
5.5.1 Running Monolix without PerlMLX
5.5.2 Monolix Program options . . . . . . .
5.5.3 Example . . . . . . . . . . . . . . . . . .
5.6 Monolix on cluster . . . . . . . . . . . . . . .
5.6.1 Cluster filesystem . . . . . . . . . . . . .
5.6.2 Task submission mechanism . . . . . . .
5.6.3 Example . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
100
100
101
102
102
103
104
105
105
106
106
106
107
108
108
108
109
109
112
114
.
.
.
.
.
.
.
.
.
.
.
.
.
.
116
116
117
118
120
120
122
125
125
125
125
127
127
127
127
6 Validation suite
129
6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
6.2 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
5
Monolix 4.3.3
CONTENTS
6.3
6.4
6.5
Combinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Extensive coverage through the demo projects . . . . . . . . . . . . . . . . . . . . . . . . . 130
Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
7 Software plugins
135
7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
7.2 DatXPlore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
7.3 MlxPlore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
A The statistical models
A.1 The nonlinear mixed effects model . . . . . . .
A.2 Individual parameters model . . . . . . . . . .
A.2.1 Examples of transformations . . . . . .
A.2.2 Example of continuous covariate model
A.2.3 Example of categorical covariate model
A.3 The residual error model . . . . . . . . . . . . .
A.4 Multi-responses model . . . . . . . . . . . . . .
A.5 Model with censored data . . . . . . . . . . . .
A.5.1 BLQ data . . . . . . . . . . . . . . . . .
A.5.2 Interval censored data . . . . . . . . . .
A.6 Inter-occasion variability . . . . . . . . . . . . .
A.7 Discrete data models . . . . . . . . . . . . . . .
A.8 Mixture models and model mixtures . . . . . .
A.8.1 Mixture models . . . . . . . . . . . . . .
A.8.2 Model mixtures . . . . . . . . . . . . . .
A.9 Prior models . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
139
139
140
140
140
141
142
143
143
143
144
144
144
145
145
145
146
B The data-set
B.1 General description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B.2 In-depth description of column-types . . . . . . . . . . . . . . . . . . . .
B.2.1 Description of column-types used to identify subject-occasions
B.2.2 Description of column-types used to time-stamp data . . . . . . .
B.2.3 Description of column-types used to define the dose regimen . . .
B.2.4 Description of column-types used to define covariates . . . . . . .
B.2.5 Description of column-types used to define regressions . . . . . .
B.2.6 Description of column-types used to define responses . . . . . . .
B.2.7 Description of column-types used to define controls and events . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
147
147
149
149
151
154
162
164
166
169
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
C Preferences
171
C.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
6
Monolix 4.3.3
CONTENTS
C.2 Graphic settings . . . . . . . . . . . .
C.2.1 Categorized Data . . . . . . . .
C.2.2 Covariates . . . . . . . . . . . .
C.2.3 Parameters distribution . . . .
C.2.4 Individual fits . . . . . . . . . .
C.2.5 Joint distribution . . . . . . . .
C.2.6 Predictions vs observations . .
C.2.7 Residuals . . . . . . . . . . . .
C.2.8 Spaghetti . . . . . . . . . . . .
C.2.9 Prediction distribution . . . . .
C.2.10 VPC . . . . . . . . . . . . . . .
C.2.11 NPC - BLQ . . . . . . . . . . .
C.2.12 Time to event (Kaplan-Meier) .
C.2.13 Transition probabilities . . . .
C.2.14 Prior distribution . . . . . . . .
C.2.15 Individual contribution . . . .
C.2.16 Convergence of SAEM . . . . .
C.3 Session related settings . . . . . . . . .
C.3.1 session . . . . . . . . . . . . . .
C.3.2 project . . . . . . . . . . . . . .
C.3.3 gui . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
7
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
171
172
172
173
173
174
174
175
176
176
177
177
178
178
179
179
179
179
179
180
180
Monolix 4.3.3
Chapter 1
Introduction
1.1
The objectives
The objectives of Monolix are to perform:
1. Parameter estimation for nonlinear mixed effects models
- computing the maximum likelihood estimator of the population parameters, without
any approximation of the model (linearization, quadrature approximation, . . . ), using
the Stochastic Approximation Expectation Maximization (SAEM) algorithm,
- computing standard errors for the maximum likelihood estimator
- computing the conditional modes, the conditional means and the conditional standard
deviations of the individual parameters, using the Hastings-Metropolis algorithm
2. Model selection
- comparing several models using some information criteria (AIC, BIC)
- testing hypotheses using the Likelihood Ratio Test
- testing parameters using the Wald Test
3. Easy description of pharmacometric models (PK, PK-PD, discrete data) with the Mlxtran
language
4. Goodness of fit plots
5. Data simulation.
8
The objectives
Monolix handles a broad spectrum of models including models defined with differential equations, left censored data, discrete data models, repeated time to events, hidden Markov models,
mixture models,. . .
Theoretical analysis of the algorithms used in this software can be found in [9, 10, 13, 14, 1].
Several application of SAEM in agronomy [19], animal breeding [12] and PKPD analysis [4, 17,
23, 25, 27, 28, 3, 29] have been published by several members of the Monolix group and other
authors. Several applications to PKPD analysis and several extensions to complex models were
also proposed during the last PAGE (Population Approach Group in Europe) meetings ([2, 16, 15,
20, 22, 24, 26, 8, 18, 7] as well as a comparison of estimation algorithms [11], (http://www.pagemeeting.org).
The aim of the present User Guide is to help a Monolix beginner to discover the software
abilities. Chapter 2 contains the installation guide, Chapter 3 explains how to use Monolix
and its graphical interface. Advanced Features and examples are detailed in Chapter 4. And the
use of the software without the graphical interface and batch mode is described in Chapter 5.
The statistical models handled by Monolix are given in Appendix A and a list of visual
preferences for result graphics is given in Appendix C.
The user guide does not cover Mlxtran programming in details, and is therefore completed
by two additional documents:
• modelMLXTRANtutorial.pdf
models with Mlxtran .
is a slidedeck tutorial on how to describe pharmacometric
• ProjectMLXTRAN.pdf presents how to easily program and customize complete Monolix
projets with Mlxtran .
9
Monolix 4.3.3
Chapter 2
Installing and running Monolixr
2.1
Downloading packages
The Monolix packages can be downloaded through the download manager hosted at
http://download.lixoft.com. The download manager is available for users provided with an
access key. Different Monolix packages are available, depending on the Matlab version and
of the operating system. Monolix currently supports Windows XP/Vista/Seven 32bits, Linux
(all common distributions) 32/64 bits, Mac OS X 10.6 or higher.
Choice of Monolix versions
• Matlab versions:
– Linux 64 bits / Matlab R2009 to R2010a
– Linux 64 bits / Matlab R2010bSP1 to R2013b
– Linux 32 bits / Matlab R2009 to R2010a
– Linux 32 bits / Matlab R2010b to R2013b
– Windows 64 bits (XP, Seven, Vista and Windows 8.1) / Matlab R2009a to R2010a
– Windows 64 bits (XP, Seven, Vista and Windows 8.1) / Matlab R2010bSP1 to R2013b
– Windows 32 bits (XP, Seven and Vista) / Matlab R2009a to R2010a
– Windows 32 bits (XP, Seven and Vista) / Matlab R2010bSP1 to R2013b recommanded
to use Matlab 2010b-SP1.
– Mac OS X 10.6 or higher / Matlab R2010bSP1 to R2011b
• Standalone versions:
10
Downloading packages
– Linux (32 bits)
– Linux (64 bits)
– Windows (32 bits)
– Windows (64 bits)
– Mac OS X 10.6 or higher
11
Monolix 4.3.3
Installation
2.2
2.2.1
Installation
Prerequisites
perl is required to run perlScripts and the validation suite; it is not required otherwise.
Linux specifics
• install sharutils : uudecode is required to uncompress the Monolix package;
• make sure you have gcc/g++/make installed or install them.
Mac OS X 10.6 or higher specifics
• You need uudecode to uncompress, and you need install_name_tool to configure the
Monolix package (these are generally provided within the system).
• Make sure you have gcc/g++/make installed or install them by installing the command-line
tools of Xcode.
Windows 64bits specifics
The 32 bits standalone version of Monolix runs fine on Windows 7 64bits. You will need
to install the 64 bits Windows version of Monolix in any of these situations:
• On other 64 bits versions of Windows (non Windows 7, or Windows 8.1);
• If you wish to use a Matlab version of Monolix .
• If you simply prefer to use a 64bits version of standalone Monolix , although in practice
this should not have an impact on the performance.
2.2.2
About Installer
• Linux : the installer is a self-extractable archive.
– run the following command (depending on your os version):
#> sh Monolix-4.3.3-matlab2010a-linux32.bin
or
12
Monolix 4.3.3
Installation
#>
or
#>
or
#>
or
#>
or
#>
sh Monolix-4.3.3-matlab2010bSP1-linux32.bin
sh Monolix-4.3.3-standalone2008b-linux32.bin
sh Monolix-4.3.3-matlab2010a-linux64.bin
sh Monolix-4.3.3-matlab2010bSP1-linux64.bin
sh Monolix-4.3.3-standalone2008b-linux64.bin
– you can specify the target installation directory by giving the path as argument
– a directory containing Monolix will be created in the directory installation path
• Windows
– copy the installer on your Desktop or in your windows temporary directory
– Double click on the executable and follow the instructions.
• Mac OS X 10.6 or higher
– Matlab inter-active mode: the installer is a self-extractable archive. Run the following
command:
#> sh Monolix-4.3.3-R2010b.bin
– Standalone mode: Double click on Monolix-4.3.3s.pkg and follow installer instructions.
13
Monolix 4.3.3
Installation
2.2.3
Directory structure
The Monolix directory structure is divided in two parts:
• the software directory containing the Monolix program (/Path/To/.../runtime)
• the personal user directory containing the Monolix workspace and documentation
(/Path/To/.../lixoft)
Installation directory
Monolix.....................................................Monolix root directory
monolix433...........................................Monolix version directory
bin............................................................tools directory
config.....................................................configuration files
graphics..........................................graphics configurations
listOfGraphics...................graphics predefined configurations
project .............. graphics default configurations for Mlxtran
settings..............................graphics default configurations
scenario ............................................... predefined scenarii
system ..................................... Monolix system configuration
factory ................................................... Mlxtran C++ API
jar ............................................................... Java library
lib ...............................................................C++ library
matlab ................................................Monolix main program
libraries ............................................. libraries of models
mlxCore ................Monolix core: all algorithms (SAEM, FIM, ...)
mlxDelegate ........glue to present Monolix project (HMI, batch, ...)
mlxIO ................input / output components (read .mat, .xmlx, ...)
mlxMath .....................................misc mathematical functions
mlxTools ....................................... some tools (mat to xmlx)
mlxUseful .............................................generic components
perlScripts ......................................................Perl scripts
resources ......................................... documentation and demos
mlxeditor .............. documentation and demos for Mlxtran editor
monolix ........................ documentation and demos for Monolix
config .............................reference for configuration files
demos .............................................................. demos
doc ...................................................... documentation
14
Monolix 4.3.3
Installation
User directory
The user directory is created after the first launch of Monolix. This directory contains the
basic configuration of Monolix, documentation, demos, log files, license file, ...
lixoft.......................................................Lixoft tools directory
monolix.................................................Monolix root directory
config.....................................................configuration files
license.................................................................licenses
monolix433........................................Monolix version directory
demos ..................................................... modifiable demos
log ................................................................. log files
modules........................................compiled Mlxtran modules
perlScripts ...................................................Perl scripts
tmp ......................................................... temporary files
2.2.4
Running Monolix
• Linux
– Matlab version
∗ start Matlab
∗ go to directory ’<install path>/matlab’ and type monolix.
– Standalone version: go to ’<install path>/bin’ and type ./Monolix.sh.
• Windows
– Matlab version
∗ start Matlab
∗ go to directory <install path>\matlab’ and type monolix.
– Standalone version: go to ’<install path>\bin’ and type Monolix.bat.
• Mac OS X 10.6 or higher
– Matlab version
∗ start Matlab
∗ go to directory ’<install path>/matlab’ and type monolix.
– Standalone version: go to the Applications folder of your computer (or where you
have placed the executable), double click on Monolix-4.3.3s.app
15
Monolix 4.3.3
Installation
2.2.5
Installation use cases
Desktop
Monolix is installed on the computer of the user and the user has a personal activation key (see
Section 2.2.6 Desktop license). After the installation or during the first startup of Monolix a
popup titled ’Lixoft Activate’ appears and asks the activation key. When the activation procedure
is finished, Monolix will be configured (typically a directory ‘/Path/To/.../lixot/monolix’
is created in the user home directory) and launched.
Desktop with a shared Monolix installation
Monolix is installed on a remote server and the user accesses to Monolix through a shared
directory (via CIFS, Network drive, NFS, ...) and the user has a personal activation key (see
Section 2.2.6 Desktop license).
During the first startup of Monolix a popup title ‘Lixoft Activate’ appears and asks the activation key. When the activation procedure is finished, Monolix will be configured (typically a
directory ‘/Path/To/.../lixot/monolix’ is created in the user home directory) and launched.
Application server with a shared Monolix installation
Monolix is installed on a remote server using the procedure described in Section 2.2.6 ’Floating
license’. The license file (obtained during activation procedure) is copied in the directory
• <monolix user install path>/config/system/access for the Matlab version of Monolix
• or <monolix install path>/bin/Monolix_mcr/runtime/config/system/access for the
standalone version of Monolix .
The user accesses to Monolix through a shared directory (via CIFS, Network drive, NFS, ...).
The user runs Monolix directly, no activation is required. Nevertheless, when a user runs
Monolix a license token is taken.
If all license tokens are used (too many users run Monolix in the same time), a popup titled
’Lixoft activate’ appears and the user is supposed to wait until at least one token is released.
Application server with a remote connection
With a floating license Monolix is installed on a remote server using the procedure described in Section 2.2.6 ’Floating license’. The license file (obtained during activation procedure)
is copied in the directory
• <monolix user install path>/config/system/access for the Matlab version of Monolix
• or <monolix install path>/bin/Monolix_mcr/runtime/config/system/access for the
standalone version of Monolix .
16
Monolix 4.3.3
Installation
The user accesses to Monolix using a remote desktop application.
The user runs Monolix directly, no activation is required. Nevertheless, when a user runs
Monolix a license token is taken.
If all license tokens are used (too many users run Monolix in the same time), a popup titled
’Lixoft activate’ appears and the user is supposed to wait until at least one token is released.
With desktop licenses Monolix is installed on a remote server, the user accesses to Monolix
using a remote desktop application and has a personal activation key (see Section 2.2.6 Desktop
license).
During the first startup of Monolix a popup title ‘Lixoft Activate’ appears and asks the activation key. When the activation procedure is finished, Monolix will be configured (typically a
directory ‘/Path/To/.../lixot/monolix’ is created in the user home directory) and launched.
Application server with a desktop installation
Monolix is installed on a remote server using the procedure described in Section 2.2.6 ’Floating
license’. Each Monolix user is supposed to have a copy of the license file obtained during the
activation procedure. After the installation or during the first startup of Monolix , a popup
titled ‘Lixoft Activate’ appears. The tab ’With License file’ has to be selected. The user is
supposed to browse to the copy of the license file to activate Monolix . When a user runs
Monolix a license token is taken.
If all license tokens are used (too many users run Monolix in the same time), a popup titled
’Lixoft activate’ appears and the user is supposed to wait until at least one token is released.
Cluster installation with a shared Monolix installation
Monolix is installed on a master server using the procedure described in Section 2.2.6 ’Floating
license’. The license file (obtained during activation procedure) is copied in the directory
• <monolix user install path>/config/system/access for the Matlab version of Monolix
• or <monolix install path>/bin/Monolix_mcr/runtime/config/system/access for the
standalone version of Monolix .
Each cluster node accesses to Monolix through a shared directory (via CIFS, Network drive,
NFS, ...).
The user runs Monolix directly, no activation is required. Nevertheless, when a user runs
Monolix a license token is taken (there is no limit of runs on cluster nodes).
If all license tokens are used (too many users run Monolix in the same time), a popup titled
’Lixoft activate’ appears and the user is supposed to wait until at least one token is released.
Cluster installation with Monolix installed on each node
License server (RLM) has to be installed on a master server and the license file is download using
the procedure described in Section 2.2.6 ’Floating license’. Monolix is installed on each cluster.
17
Monolix 4.3.3
Installation
During this installation it is not necessary to activate Monolix when the popup titled ’Lixoft
activate’ appears (just close the popup). The license file (obtained previously) is supposed copied
in the directory
• <monolix user install path>/config/system/access for the Matlab version of Monolix
• or <monolix install path>/bin/Monolix_mcr/runtime/config/system/access for the
standalone version of Monolix
of each node.
18
Monolix 4.3.3
Installation
2.2.6
License
Monolix licenses can be of the following types:
• Individual license - named user. The named user can install and run Monolix on a
predetermined number of different computers.
• Floating license - concurrent access. The license is hosted by a license server, and Monolix
can either run on a server or individual workstations.
Remark: the former license management tool uses a license file (license.ini); this type of
license is deprecated since Monolix version 4.1.3.
Desktop license
The activation key (provided by Lixoft ) must be entered in the dialog box titled ‘Lixoft
license activation’ (‘With activation key’ tab). This dialog box only appears when no license is
available on the user’s computer or when the license expires.
Floating license
The use of a floating license requires to set up a license server. In this case there are two
installation strategies for Monolix users:
• install Monolix on a directory shared by all Monolix users,
• install Monolix on each user’s computer and copy the license file obtained as described
below into the directory:
– <monolix user install path>/config/system/access for the Matlab version of
Monolix ,
– or <monolix install path>/bin/Monolix_mcr/runtime/config/system/access for
the standalone version of Monolix .
After the installation process, when the ’Lixoft activate window’ appears just close the window
(do not enter the activation key of the floating license). Then, start the RLM server, located at:
19
Monolix 4.3.3
Installation
• <monolix install path>/tools/rlm/rlm{.exe} for the Matlab version of Monolix ,
• or <monolix install path>/bin/Monolix_mcr/runtime/tools/rlm/rlm{.exe} for the
standalone version of Monolix .
At this step there is no license available yet; the IT manager should use the RLM web server to
download the license by following the procedure below:
1. In the web browser, type <IP>:5054, where <IP> is the IP address of the computer hosting
the RLM server (e.g. 192.168.46.248:5054).
Notice that the RLM server opens two ports : 5053 and 5054. The first port (5053) is a
service port used for the transactions of licenses. The second port (5054) is the RLM web
server port used to access to the RLM configuration through a web browser.
It is possible that one or both ports may have been used by another application.
• If the web server port (5054) is not available you can launch RLM server with a new
port by using the program option -ws (e.g: rlm -ws 5055) in this case, the access
to RLM configuration through a web browser is done using the address <IP>:<NEW
PORT> (e.g. 192.168.46.248:5055).
• If the server port (5053) is not available, a file config.conf has to be created in the
rlm directory and has to contain the following information:
HOST <IP> <MAC ADDRESS> <NEW PORT>
e.g.
HOST 192.168.46.245 a8c0f82e 5060
20
Monolix 4.3.3
Installation
2. Begin license activation:
21
Monolix 4.3.3
Installation
3. Enter the RLM activation url : activate.lixoft.net. And click on Next button.
If the rlm server does not have Internet access, the license has to be created by Lixoft .
Send a mail to [email protected] with the following informations:
• Mac address of the computer hosting the RLM server
• IP address of the computer hosting the RLM server
22
Monolix 4.3.3
Installation
Lixoft will send in return a ’.lic’ file which has to be copied in the directory
• <monolix install path>/config/system/access (Matlab version of Monolix )
• <monolix install path>/bin/Monolix_mcr/runtime/config/system/access (standalone version of Monolix ).
At this step, the installation of Monolix is complete.
4. Activate the license.
Fill the ISV input with the string ’lixoft’ (without the quotes) and the License activation
key with the activation key provided by Lixoft (key format is xxxx-xxxx-xxxx-xxxx)
23
Monolix 4.3.3
Installation
5. Enter (at maximum) the number of bought licenses, then click on Next button
Notice, the number of licenses cannot exceed the number of bought licenses.
24
Monolix 4.3.3
Installation
6. Select the license directory and file.
In the field named License file to create write the full path to license file
<monolix install path>/config/system/access/myfloat.lic for the Matlab version
of Monolix
or <monolix install path>/bin/Monolix_mcr/runtime/config/system/access for the
standalone version.
e.g: if the Monolix (matlab version) installation directory is /media/share/monolix the
input field name License file to create should contain
/media/share/monolix/config/access/myfloat.lic
This license file has to be copied on each installation of Monolix :
• If Monolix is installed on a shared space (i.e. each node of the cluster has an access
to this directory), copy the license file into the directory
<monolix install path>/config/system/access/ for the Matlab version of Monolix
or <monolix install path>/bin/Monolix_mcr/runtime/config/system/access for
the standalone version.
Make sure that the Monolix directory is accessible from each cluster node.
25
Monolix 4.3.3
Installation
Example (with a Matlab version of Monolix )
– Monolix is installed on the computer master-computer in the directory:
/usr/local/monolix/.
The license is in the directory :
/usr/local/monolix/config/access/
– The RLM server is run on the computer master-computer.
– Cluster computers mount the directory /usr/local/monolix/.
– Each monolix user runs Monolix from the previously mounted directory.
• If Monolix is installed on each node of the cluster, copy the license file on each
computer in the directory <monolix install path>/config/system/access for the
Matlab version of Monolix or
<monolix install path>/bin/Monolix_mcr/runtime/config/system/access for the
standalone version.
Example
– The RLM server is executed on the computer master-server.
– Monolix is installed on each cluster node of the cluster.
– The license file is copied on each cluster node in the directory <monolix
install path>/config/system/access/ for the Matlab version of Monolix
or <monolix install path>/bin/Monolix_mcr/runtime/config/system/access
for the standalone version.
– Each monolix user runs Monolix from the cluster node.
26
Monolix 4.3.3
Installation
7. Stop the server manually and restart it from the directory (or use option -c)
• <monolix install path>/config/system/access/ for the Matlab version
• <monolix install path>/bin/Monolix_mcr/runtime/config/system/access for the
standalone version of Monolix .
Now RLM is running with the provided license. This is verified in the web interface by
clicking on status button.
27
Monolix 4.3.3
Installation
8. RLM Server : server hostname and port considerations.
If for any reason, the server port or the server hostname is not registered in a DNS, it is
possible to change these informations directly on licence file.
The line HOST <hostname> <mac> <port> can be changed by HOST <rlm server ip> <mac>
<new port>.
9. RLM Server : firewall considerations.
If the RLM server is behind a firewall, the port 5053, 5054 and the ISV port have to be
opened.
The ISV port can be set directly in license file by changing the ISV line as follow:
...
ISV lixoft port=<your ISV port>
...
10. Managing RLM server :
The documentation of the management of the RLM server provided by Reprise Software
is available at
http://www.reprisesoftware.com/RLM_Enduser.html
28
Monolix 4.3.3
Installation
Roaming license
RLM has the ability to allow a floating license to roam to a system which will subsequently be
disconnected from the network for a short period of time. The resulting license can be used for the
number of days specified when the license was set to roam, and is checked back in automatically
at the end of this. In addition the user can return the roamed license back to license pool early
if this is desired.
See License activate tools (which can be launched from the Monolix interface, in tools
menu)
This feature is enabled on demand. An extra activation key will be provided by Lixoft and the
procedure to get the roaming license feature is identical to the installation of a floating license. To
enable this feature, the file system.xmlx (stored in directory <monolix install path>/config/
-Matlab version- or <monolix install path>/bin/Monolix_mcr/runtime/config/ -standalone
version of Monolix - must be modified by setting to "on" the roaming option:
<?xml version="1.0" encoding="utf-8"?>
<monolix>
<preference>
<session>
<userPath windows="%USERPROFILE%" linux="$HOME"/>
<license activation="http://activate.lixoft.net" roaming="on"/>
</session>
</preference>
</monolix>
29
Monolix 4.3.3
ChangeLog
2.3
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
ChangeLog
Monolix 4.3.3 (2014 -09)
Bug fixes :
- bug fix : fixed effects where not correctly initialized when they
were not simulated
- bug fix : problems estimating autocorrelation ( SAEM ) and the
corresponding Fisher information matrix
- bug fix : limits of the confidence intervals in VPC
- bug fix : performance loss on Windows
- bug fix : multiple runs of the Stand Alone version in a Windows ".
bat " script lengthened its " PATH " variable . It could get commands
ignored for being too long .
- bug fix : On Windows 64 bits , spaces in user account ’ s name
prevented the compilation for Mlxtran
- minor bug fix : Display of the version of Monolix in Matlab help
- bug fix : overlooked eliminations in secondary compartments for
analytical solutions
Enhancements :
- add configuration option for sysadmin to enforce number of
structural model threads and maximum computational matlab threads
- change of the coefficient of simulated annealing
- compatibility with Matlab 2014 a
- default naming convention changed to avoid extra use of ’_ ’:
- covcategory instead of cov_category in parameter names
- transformed covariates are called as tCov instead of t_Cov
- latent covariate by default are now called lcat , lcat1 , etc
- Mlxtran compilation is shielded against system - wide configurations
set by compiler g95
- warning for macro " elimination ( Cl ) " if the volume isn ’ t defined in
the base compartment " cmt ". The default volume is still " volume
=1".
21
22
23
24
25
26
27
28
29
30
Monolix 4.3.2 (2014 -05)
Bug Fixes :
- bug fix : several latent covariates made algorithms crash
- bug fix : Fixed parameters are no longer modified in convergence
assessment
- bug fix : in presence of several regresors , the x - label were not
correct set in some graphics
- bug fix : datasets with EVID =2 or 3 were not correctly filtered when
some subjects did not have observations causing an error
- bug fix : Covariates graphics represented simulated individual
parameters untransformed instead of the transformed ones when the
simulated ones were chosen
- bug fix : autocorrelations were not correctly bounded when all the
subjects had only one observation
- bug fix : license activate with combo
30
Monolix 4.3.3
ChangeLog
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
- bug fix : License Manager : when a license already existed ( and was
not expired ) , the licence Manager Interface did not download a
new license file
- bug fix : License Manager : when a license file from < USERPATH >/
lixoft / monolix / license was copied on itself the content of the
file was erased
- bug fix : Matlab 2013 compatibility produced a loss of performances
Monolix 4.3.1 (2014 -03)
Bugs Fixes :
- bug fix : Matlab 2013 compatibility
- bug fix : the ’ TASKS ’ section of the Monolix project was not
correctly parsed when graphicSetting or algorithmSetting
contained ’_a ’ , ’_b ’ , ’_c ’ which are tokens for the error model
- bug fix : Analyical Solution : pkmodel ( ka ,V , Cl ) failed when ka =1 , Cl
=1 and V =1
- bug fix : tte graphics better grid adjustement
- bug fix : cond . mode estimation in presence of mixtures and other
covariates were biased
- bug fix : fisher information matrix estimation could fail when only
one parameter were estimated
- bug fix : SAEM failed when using variances set as " fixed " and
covariate dependent variances .
- bug fix : problem preparing results in presence of priors with MAP
- bug fix : simulation with estimator uncertainty failed in presence
of correlations between individual parameters
46
47
48
49
50
51
52
53
54
55
56
Enhancements :
- add an option ’-- log - file ’ to specify the location of the log file
- results
- population parameter names where changed to be more consistent
with other Lixoft tools like mlXplore
- tables with estimations are now separated in :
- estimations . txt population parameters , standard errors ( s . e )
and relative standard errors ( r . s . e )
- fim_lin . txt Fisher information matrix estimated by
linearisation
- fim_sa . txt Fisher information matrix estimated by stochastic
approximation
- tables with estimations includes now also the effects for
reference categories ( fixed to zero ) .
57
58
59
60
61
Monolix 4.3 (2014 -02)
Bugs Fixes :
- bug fix : when using estimators uncertainty , the correlations were
only simulated in 0 ,1 ( instead of -1 ,1) .
31
Monolix 4.3.3
ChangeLog
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
- bug fix : predictions calculations can take too much time ( even hang
) in presence of RTTE data
- bug fix : error when removing covariates from the project
- bug fix : error when all the observations of one subject are null in
combined2 ( Fisher information matrix estimation )
Enhancements :
- GUI
- addition : monolix remembers now the last options selected in
simulation interface
- addition : checkbox for the user to choose among saving the
paths as relative or absolute addresses
- Algo
- Tables of population parameters and fisher after storing of
results
- Graphics
- new setting in RTTE graphic : accuracy of grid
- stratify saved in graphics with projects
- settings ( axes , labels ) saved in projects , and stored while
using the graphics
- export of graphics data
- MLXTran
- analytical solutions : ODE replaced by analytical solution when
keywords ( as pkmodel , compartment , ...) are used . This
improves the processing time .
- DDE solver
- distribution functions ( Student , Log - Normal ...)
- ODE initial values can depend on time
Monolix 4.2.1 (2013 -02 -15)
Bugs Fixes :
- MLXTRAN Project : in STRUCTURAL_MODEL section resolved problem
with path relative to % MLXPROJECT %
- mlxEditor , mlxPerlScript : under Suse Linux OS , conflict with
libstdc ++ and Qt librairies installed on the OS .
- Graphics : Kaplan Meier
- mean normalization
- survival curve : case of censured data
- simulations where wrong in presence of correlation between
individual parameters
- MLXTRAN Model :
- Events could be close at a numerical epsilon for the solver
, but not for the solver driver
Rarely , it resulted into an explicit integration failure ,
returning " NaN "
- For the simulation of RTTE models , the ordering of the
output names had to be alphabetical
32
Monolix 4.3.3
ChangeLog
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
- Not declaring all regression variables that where selected
from the data set crashed the application .
- Declaring some PK without actual doses within the data set
raised an error .
- Using the deprecated syntax with several lagged
compartments returned " NaN "
- Algorithms
- Error when some subjects had no doses in conditinal mode
computation
- GUI
- " Display the data " button did not update the information
when the dataset was changed after running algorithms
- Convergence assessment GUI failed when there was only one
individual parameter
- structural models with several dots (.) were not compiled
when clicking in the compile button in the Model
selection GUI
- projects with more outputs in structural model than
observations in dataset caused an error when it was
loaded
- the editor was not saved in the preference file
- Convergence assessment graphics did not handled
correctly when there was not variance on some
parameters or their covariate dependence
Enhancements :
- add possibility to configure the compiler ( used to create
Structural Model plugins ) through the file ’ system . xmlx ’
- user API :
- it is now possible to use matlab function " ver " to know
Monolix version and Monolix API version
- mlxEditor :
- allow multiple files selection on open file dialog box
- add ’ Find and replace ’
- set tabs movable
- MLXTRAN Model :
- Continuous observations can be declared within the model .
- Macro for a depot absorption , with a target ODE component .
- Permutation kernel for mcmc included
Other :
- Licensing system : ’. ini ’ files desactivated ( only the ’. lic ’
files are allowed )
- residual error models in main interface are now displayed with
their full name ( those used in MLXTRAN project and model )
-------------Monolix 4.2.0 (2012 -11 -26)
33
Monolix 4.3.3
ChangeLog
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
Bugs Fixes :
- MLXTRAN Project : in OBSERVATION section when a prediction has
the same name as an individual parameter the project parses
fail
- PerlScript : bug with parameter ’-- use - matlab = false ’ was taken
as ’ true ’
- Identity line works in observations vs predictions graphic
- Prediction distribution : percentiles are correctly displayed
- Color when stratify in covariables graphic
- Problem with prior ( by default prior is Variance and not
Standard Deviation , this implies a syntax error (
stan dardDevia tion <-> variance )
- Wrong data file for the demonstration project
r t t e W e i b u l l C o u n t _ p ro j e c t . mlxtran
- " Display the data " button did not work
- bug when unchecking and checking " random effects " variability
in simulation interface
Enhancements :
- Interval censoring for continous data
- Extended priors on fixed effects
- Mlxtran model and Mlxtran project editor
- Perl script HMI
- Autosave
- Multiple covariate definitions
- Add batch - mode demo
- Add a doc package and a rlm server package ( floating license
server )
- Graphic
- BLQ graphic : possibility to choose its own interval of
censored data
- Reorganisation of panel for the list of graphics
- Background color for each graphic in preferences
- When split , limits are the same for all axes
- Obs . vs Pred . , observations can be relied by individual
- Optimal bandwidth setting for parameter distribution
- CvSaem graphic : choice of axes number
- Interval - censored data and maximum number of events for time - to
- event and drop - out data models
- Markov chain for categorical data
- Continuous - time Markov process for categorical data
- probit and normal cdf for Mlxtran model
- New user API including simulation - estimation , convergence
assessment and simulations tools
- Possibility to define new covariates as transformation of
already defined ones
162
34
Monolix 4.3.3
ChangeLog
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
New graphics :
- Posterior and prior functions for bayesian
- Individual contribution for the LL
- Transition probabilities
- Kaplan - Meier survival function
New tables :
- Individual contribution to log - likelihood
- Covariates summary
-------------Monolix 4.1.4 (2012 -07 -16)
Bugs Fixes :
- Saving preferences from tools menu failed .
- Display remaining time ( license ) correctly .
- Problem with license activation file path .
- Add license agreement into Linux installer .
- The horizontal slider in " Check initial fixed effects "
interface did not appear for some number of individual
parameters .
Enhancements :
- Windows 64 RC .
- Management of the maximum number of threads for MLXTran models
( can be set from the preference tools : MonolixGUI - > Tools - >
Preference )
- License activate : inform user to not set activation key
if the license is a floating license .
- Documentation :
* Installation guide : Windows 64 bits .
* User Guide : Cluster section revised .
* Model MLxTRAN : list of keywords of the language .
-------------Monolix 4.1.3 - sp2 (2012 -05 -29)
Enhancements :
- system . xmlx : possibility to hide Lixoft Activate display .
- Lixoft Activate : add the possibility to send an email with
encoded computer information to create license @Lixoft .
- Lixoft Activate : manage " cannot connect to url " error by
asking user to go on a web site or tosend an email .
Bugs Fixes :
- IOV Problem with R2010bSP1
35
Monolix 4.3.3
ChangeLog
205
206
207
208
209
210
211
212
- perlScripts : bug in the management of the configuration file
for [ program - execute - options ] and run on a cluster .
- add ’ rlmutil . exe ’ for windows packages ( forgotten in previous
packages ) .
- problem floating license .
- warnings for occasions without dose were removed .
- when the last Individual / Occasion had no dose , Monolix crashed .
- When there were syntax errors in the structural model , monolix
said that it could not find the file instead of giving the
MLXTRAN message
- NaN observations are now mentionned as error when algorithms
are launched .
- Update documentation : in batch mode section , there is a bad
path .
213
214
215
216
217
218
219
-------------Monolix 4.1.3 - sp1 (2012 -05 -21)
220
221
Bug Fixes :
- GUI :
* Check Initial Fixed Effects interface crashed when creating
covariate and parameter s sliders for some sizes
222
223
224
--------------
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
Monolix 4.1.3 (2012 -05 -02)
New Features :
- MLXTran model : allows negative categories
- License management : uses RLM as license provider
- Compiler manager : adds the possibility to choose the embedded
compiler
- The Monolix and Matlab versions are now stored in the algorithm
result files
Bug Fixes :
- MLXTRAN project :
- continuous transformation can take a mathematical
expression
- problem with structural model path
- MLXTRAN model :
- Under Linux 64 bits , due to library conflicts with Matlab
R2010b and following versions , the multi - threaded
loading of the model description for the project
occasionally fails
36
Monolix 4.3.3
ChangeLog
240
241
242
-
243
244
245
246
247
-
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
-
- The last table variable only is recorded , overwriting the
first one
Graphics :
- log / linear works on all graphics
- when log - log scale is set for " observed versus predicted " ,
the diagonal line is not displayed anymore
GUI :
- editor call did not work
Algorithms :
* bug for individuals without some type of observations and
with IOV computing conditional mode
* bug when there were continuous outputs after discrete
outputs
* Fisher Information Matrix by Stochastic Appoximation does
now handle the case better when there is
no parameter to estimate in the residual error
Session :
* when the directory monolixData / monolix < version > is renamed
during an active Monolix session , stopping
Monolix caused an exit of Matlab .
-------------Monolix 4.1.2: (2012 -03 -05)
-------------New Features :
- PerlScripts : possibility to save the results in the project
directory instead of the output directory
- In system . xmlx : automatically creates a directory hierarchy
for " monolixData " path
Enhancements :
- MLXTran ( structural model ) multi - threading processing
enhancement
268
269
270
271
272
273
274
Bug Fixes :
- Batch Processing failed when a very large number of projects
were launched
- MDV column : when MDV =2 only the regression variables were taken
into account
- Fixed a bug in graphics saving
- Fixed error when an empty result folder was timestamped
- Simulation of categorical data , whenever no category 0 is
defined
37
Monolix 4.3.3
ChangeLog
275
- Fixed take into account UserPath defined in ’ system . xmlx ’ for
the preference file saving
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
-------------Monolix 4.1.1: (2012 -02 -13)
-------------New Features :
- timestamped backup
- preferences interface
- tools menu for activating license and preferences
- option for locking structural model modifications
- Project - MLXTRAN grammar modification : initialization of
parameter is written now as beta_ { pi , cov } , pop_ { pi } , omega_ {
pi } , ...
- save graphics as png / ps / jpg / bmp or tiff
- selection of graphics / tables to be saved
Bug Fixes :
- Project - MLXTran : user can define the result folder
- LoQ difference between 3.2 and 4.1
- statistical test for error model and covariate model
- xmlx loading from 3.2 to 4.1
- correlation ( levelName consistence with IOV ) + parser error
- observation model ( prediction = observation name )
- path for MONOLIX user profile can include special characters
-------------Monolix 4.1.0: (2012 -01 -23)
-------------psmlx :
- compatible with the mlxtran format of projects
- available on Windows OS
mlxtran :
- new syntax
- PK macros
- RTTE models
license :
38
Monolix 4.3.3
ChangeLog
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
- interface to install the license file
Interface :
- setting for axes ’ limits
- information for the observation model
- shortcut for model libraries
File system :
- improved handling of special characters for filepaths
Demos :
- updated for the new mlxtran syntax
- dispatch of the model library for demos
Known Bugs :
- under Windows OS , user directory cannot contain special
characters other than spaces
-------------Monolix 4.0.1: (2011 -10 -27)
-------------psmlx :
- use - matlab option didn ’ t work in command line mode
- multi - threading : multhreading didn ’ t work
- take into account the p . coded files
mlxtran
- problem with FIM options : both linearization and
s t o c h a s t i c A p p r o x i m a t i o n appeared after a save with
s t o c h a s t i c A p p r o x i m a t i o n option set
- avoid the unloading of project when settings files does not
exist : default settings are loaded
license :
- multi write database didn ’ t work well in multi - threading mode
Interface :
- save lists
- configuration panel
- launching some graphics alone is now possible
- graphics were closed when " Use last estimates " were used
- when monolix was launched twice without loading or creating a
project , two toolbars were created
362
39
Monolix 4.3.3
ChangeLog
363
364
Algorithm and simulations :
- simulation works now with dataset without EVID column and with
MDV column
365
366
367
368
369
370
Results :
- the graphics fit now to the paper in . ps files
- xLabels were wrong for some graphics when several regression
variables were present
- some graphics crashed when launched after some hypotheses
tests were done
- Visual studio redistribuable problem
40
Monolix 4.3.3
Troubleshooting
2.4
2.4.1
Troubleshooting
Downloading Monolix
Problem: My web browser claims that the Monolix download website has insufficient reputation and suggests to stop the download.
Solution: Some browsers like Google Chrome and Internet Explorer may ask whether to keep
or remove the Monolix archive just after download because of the insufficient reputation of
the Monolix download website, simply because it is not referenced, as opposed to the Lixoft
website. Please ignore the warning and choose to keep the file. You can use a MD5 tool to verify
that the downloaded file is not corrupted.
Problem: The Monolix archive is removed just after being downloaded.
Solution: Some antivirus may consider the Monolix archive as risky and put it in quarantine or remove it. This is due to the fact that Monolix embeds a compiler for the Mlxtran
language. Two solutions are available:
1. Deactivate your antivirus auto-protection process during download and installation, or
2. Restore the file from the quarantine.
To restore the file from quarantine, please refer to the documentation of your antivirus software.
For the most common examples:
• Norton Antivirus 2012:
– Start Norton Antivirus
– Choose Advanced, then Quarantine
• Avast Antivirus 7:
– Open Avast
– Choose Maintenance, then Virus Chest
You should see the downloaded file among the quarantined files. Execute the Restore action;
the archive will be restored into the directory used for downloading. Click on the archive (ignore
a possible “malware” warning, again related to the fact that Monolix embers a compiler.), and
installation will start.
41
Monolix 4.3.3
Troubleshooting
2.4.2
Running Monolix
Problem: When launching the standalone version, my antivirus tells me that the file
mlxinitializer.exe is risky.
Solution: If your antivirus apparently removed the file mlxinitializer.exe, check if it was
actually put on Quarantine, or removed. If it is in Quarantine, please restore it by following the
same instructions as provided above. If the file was removed you will need to reinstall Monolix
.
You should be able to add this file to your antivirus Trusted Zone or Trusted files.
• Norton Antivirus 2012:
– go to folder Monolix/monolix433s/bin in installation directory: for instance
c:/ProgramData/Monolix/monolix433s/bin
– right click on mlxinitializer.exe, click on Norton Antivirus, then Norton File
Insight then look for ‘Unproven’, and click ‘Trust Now’.
• Avast 7: This software may start Monolix in a SandBox, i.e in a zone where the antivirus
avoids any modification of the system or the files. He will ask you what to do at each run.
Select Run normally.
You can also add mlxinitializer.exe to the exclusions in its Auto-Sandbox settings:
option Additional Protection/AutoSandbox and then click on Settings button.
42
Monolix 4.3.3
Chapter 3
Using Monolix
3.1
Introduction
In order to use Monolix, your problem must be described as a Monolix project. A project
specifies
• the dataset to use
• the structural model
• the statistical model, which includes
– covariate model for individual parameters
– covariance model for random effects
– observation model
• the tasks to run, their settings and initial values
The dataset is an ASCII file containing all the data for your study (see Section 3.3.1 for a
brief description) and the structural model is a function explaining the theoretical model behind your data. It can be easily described using the Mlxtran language (see the document
modelMLXTRANtutorial.pdf in Monolix documentation folder), or as a Matlab function for
a Matlab version of Monolix.
A mathematical description of the statistical models handled by the software can be found in
Appendix A.
All these informations can be set in the Monolix main window.
In this chapter, we will describe the main window and its different sections, using a simple
example.
3.1.1
The theophylline example
We will consider the theophylline data (see [6, 21]) as an example to illustrate how to use
Monolix.
43
The main window
In this case subject i receives a dose Di per kilo at time 0 and serum concentrations (yij ) are
measured at times (tij ). Serum concentration is modeled by a first-order one compartment model.
Then,
Cl
Di kai
− V i tij
−ka
t
i
ij
yij =
+ aεij
(3.1)
−e
e i
Vi kai − Cli
where kai is the absorption rate constants of subject i, Vi is the volume per kilo of subject i and
Cli is the clearance per kilo of subject i. These three parameters are nonnegative real numbers
and are assumed to be log-normally distributed. Here,
• the vector of regression (or design) variables is xij = (Di , tij ).
• the vector of individual parameters is ψi = (kai , Vi , Cli ),
• the model is assumed to be homoscedastic and g ≡ a.
The only available covariate is the weight (wi ) of the subjects.
The data file theophylline_data.txt is in the directory <demos folder>/theophylline. This
file is in the so-called “NONMEM format” and contains the ID numbers of the subjects, the
doses per kilo (Di /wi ), the times (tij ), the observed concentrations (yij ), the weights (wi ) and
the genders (si ) (this additional covariate is not in the original dataset: it was added for the
demo).
ID
1
1
1
.
.
.
AMT
4.02
.
.
.
.
.
T
0
0.25
0.57
.
.
.
DV
.
2.84
6.57
.
.
.
WEIGHT
79.6
79.6
79.6
.
.
.
SEX
M
M
M
2
2
.
.
.
4.4
.
.
.
.
0
0.27
.
.
.
.
1.72
.
.
.
72.4
72.4
.
.
.
M
M
12
5.3
24.15
1.17
60.5
F
Here, “AMT” (amount per kilo) holds for “D/w”, “T” is the time and “DV” (dependant variable)
holds for “y”.
3.2
The main window
After starting Monolix, the main window appears empty. Only the “Project” and “?” (help)
menus are available, there you need to choose or create a project to continue.
44
Monolix 4.3.3
The main window
The project can be created from scratch by clicking on
Project->New in menu or modifying a previously loaded one
(Project->Load).
It is then possible to save it with the menu Project->Save
in any of three formats: as a Mlxtran project (ASCII file
with extension .mlxtran, recommended and default for new
projects), as a binary Matlab (.mat) file or as a XML (.xmlx)
file.
Once the project is chosen, the different sections of the interface become visible. Those sections
facilitate the project definition.
All the menu options also appear and the toolbar buttons become enabled.
•
create a new project
•
load an existing project
•
save the current project (mlxtran, mat, and/or XML file)
•
see the last results for the current project
•
display the data
•
estimate the population parameters,
•
estimate the Fisher information Matrix and the standard errors,
•
estimate the individual parameters,
•
estimate the log-likelihood,
•
display a set of graphics
•
test the covariate model
•
test the covariance model
•
test the residual error model
•
simulate a new dataset
•
publish the results (not available with the standalone version)
45
Monolix 4.3.3
The “Data and Model” frame
•
about Monolix
•
quit Monolix
In our example, the project file theophylline_project.mlxtran is included in the Demos so you
can load it or create a new one from scratch.
- To load the project, use the button and select theophylline_project
in the <demos folder>/theophylline folder (go to Section 3.7 to see how to run the
algorithms).
- To create a new project to analyze the theophylline data, use the
and follow the instructions below.
3.3
3.3.1
button
The “Data and Model” frame
The data
The data file should contain a matrix in an ASCII format with or without header for each column.
The columns of this matrix contain (in any order)
1. the ID of the subjects (can be any string or number, not necessarily ordered),
2. the regression variables (xij ),
3. the observations (yij ),
4. the covariates,
5. additional information (censoring, rate, tau . . . ).
. theophylline example:
To select the theophylline dataset use the button The data . A new window is opened
• Select the data file theophylline_data.txt. The dialog box to select the dataset can be
opened with the button Data file .
46
Monolix 4.3.3
The “Data and Model” frame
• If Monolix does not recognize the different columns you can choose one of the column
delimiters from comma (“,”), semicolon (“;”) , space (“ ”), tab (“\t”):
• Since the file has a header in the first line (ID AMT T DV WEIGHT SEX), Monolix will
use the recognized columns by default. You can choose other headers for each column by
yourself. Use Use header button whenever it is desired that Monolix uses the header
from the file, instead of the current one.
• Check that Monolix has recognized the keywords (ID, AMT, T, DV) and translated them
to (ID, AMT, TIME, Y).
• The headers WEIGHT and SEX are not recognized and set to IGNORE. Nevertheless, you can
consider the weight as a continuous covariate by selecting the label COV for this column
and the gender as a categorical covariate by selecting the label CAT for this column.
• Accept the data information with the Accept button
A list of the main headers identified by Monolix is
• ID (or #ID, I) to identify subjects
• TIME (or T) for the time
• AMT (or DOSE, D) for the dose
• X (or REG, XX) for any regression variable
• Y (or DV, CONC) for the observations
• YTYPE (or ITYPE, TYPE, DVID) for the type of observations
when there are several types of observations (1 for the first
type, 2 for the second type, . . . ). YTYPE is not necessary in
the case of a single output.
• COV for the continuous covariates
• CAT for the categorical covariates
• OCCASION (or OCC) for the occasion
• ADM for the type of administration
• CENS for censored data. Can be −1 to represent right-censored
data
47
Monolix 4.3.3
The “Data and Model” frame
• LIMIT for interval-censored data. It gives the lower limit while
Y gives the upper limit
• RATE (or R) for the infusion rate
• TINF for the infusion duration
• SS for steady-state (requires column II)
• ADDL for the number of additional doses (requires column II)
• II (or TAU) for the inter-dose interval
• MDV (Missing Dependent Variable) MDV= 0 if the row contains
an observation and MDV=1 otherwise. MDV is not necessary if
a dot is used to say when a row does not contain any measurement (Y=‘·’). You can use MDV=2 to include times for regression variables updates and for prediction evaluation (see
Section 4.11).
• EVID for Dose events. EVID is not necessary if DOSE=‘·’ is used
when a row does not contain any dose information. EVID=4
resets the system to the initial state.
3.3.2
The model function
Use The model button to define the
model function. In the Model List window, it is possible to select a model from
the model library included in the software (PK library, PD library, VK library, discrete data library) by using the
Monolix Library button; or from a personal list by using the Other list button.
Refer to modelMLXTRANtutorial.pdf for more details of how to implement your own model using
Mlxtran.
When a model is selected from one of these lists, the model information is summed up in the
Model Info window: name of the function, number and names of the parameters, of design
variables and of outputs.
Edit the model with the Edit button. If you use the Matlab
version of Monolix, then the Matlab editor will be used by default.
If you use the standalone version of Monolix (or if you want to use
another editor with the Matlab version), select your own editor with
the · · · button. In standalone version, only the Mlxtran models can
be edited, and the only .m models that can be used are the built-in
models.
48
Monolix 4.3.3
The “Data and Model” frame
Note: Monolix includes now its own editor for Mlxtran projects and models. Set the editor
to ‘mlxEditor’ if you want to use it.
. theophylline example:
We use the first order oral absorption with one compartment model function
(oral1_1cpt_kaVCl) from the PK library which has 1 design variable (time), 3 parameters (ka , V , Cl) and 1 output (concentration).
Important: When a project is created (or loaded), there are two ways to change the structural
model:
• by clicking on the button The structural model .
• by right-clicking on the name of the model.
3.3.3
The covariate model
Here, m is the number of covariates and d is the number of individual parameters. Then, The
covariate model is a m × d matrix A containing only 0 and 1. For any 1 ≤ k ≤ m and any
1 ≤ ` ≤ d, Ak,` = 1 if the `-component φi,` of the individual parameter φi is function of the kth
covariate, and 0 otherwise.
. theophylline example:
Let us assume that no covariates are used in the model:
log(kai ) = µ1 + ηka,i
log(Vi ) = µ2 + ηV,i ,
log(Cli ) = µ3 + ηCl,i
Consider now that the log-volume is a linear function of the weight and that the log-clearance
depends on the gender.
log(kai ) = µ1 + ηka,i
log(Vi ) = µ2 + βW,V wi + ηV,i ,
log(Cli ) = µ3 + βS,Cl 1si =M + ηCl,i ,
Here, the reference group are the female and the population parameters are
log(Clpop,F ) = µ3
log(Clpop,M ) = µ3 + βS,Cl .
49
Monolix 4.3.3
The “Data and Model” frame
3.3.4
Creating and transforming covariates
Some times, it is needed to use some transformed version of the original covariates. It can be
done in the window opened when clicking on the button transform :
1.- transforming continuous covariates
It is possible to consider non-linear functions of the continuous covariates. Logarithmic, exponential or fractional polynomials are available and personal functions can be considered. This is
also possible to center the covariates.
. theophylline example:
Consider for example, a log-transformation of the weight, centered by the mean:
wi? = log(wi ) − log(w)
Then, the covariate model used for the volume is
Vi = V
w βW,V
i
w
eηV,i
Instead of using the mean to center the logtransformation of weights, you can normalize the
weight by some constant value a (a = 70 for example)
by centering the transformed weight by log(70):
Vi = V
w βW,V
i
70
eηV,i
50
Monolix 4.3.3
The “Data and Model” frame
Remark: The pre-defined transformations will
be removed in a future version of Monolix. We
strongly recommend to write your own transformation using the “other” option. For example, the allometric transformation of the weight proposed above
just reduces to:
2.- transforming categorical covariates
You can easily modify the groups defined by a
categorical covariate. You can also select the reference group and modify the names of the groups (just
click on Gk to change the name of the k-th group).
3.- creating new covariates
In some cases, it is needed to use different transforms of the same covariate, for instance to use
WEIGHT for some parameter and log(WEIGHT) for other. It is possible by creating a new dependent
covariates.
To create new covariates, click on Add button
and select from which covariate, among the originals
and already created ones, the new one will depend.
Then click on OK .
The new covariate is added to the list at the left so you can use them like the original ones and
define their transformations.
The new or transformed covariates receive a
name by default that can be modified by the user
at the top of the window.
It is also possible to remove the new covariates or the transformations from the original covariates
with the button Remove .
It is important to note that, the new covariates will be of the same type (continuous or categorical)
than those from which they are function of, and that new categorical covariates can only be
function of original (not transformed) categorical covariates.
Note: It is recommended to set the name of the modified or newly created covariates before
creating new ones.
51
Monolix 4.3.3
The “Data and Model” frame
3.3.5
Distribution of the individual parameters
The default distribution of the individual parameters are defined by the structural model, but it
is possible to change it in the Monolix window by clicking on the buttons below Distribution
of the individual parameters to
• N for a normal distribution ψ = ϕ
• L for a log-normal distribution
ψ = eϕ
• G for a logit-normal distribution
ψ = (1 + e−ϕ )−1
• P for a probit-normal distribution
ψ = P(N (0, 1) ≤ ϕ)
• B for a power-normal (Box&Cox) distribution
1
ψ = (Aϕ + 1) A
• C for a custom (user defined) distribution
3.3.6
The covariance model of the random effects
The covariance model of the random effect is a d × d matrix ∆ formed by 0 and 1. For
any 1 ≤ j ≤ d and any 1 ≤ l ≤ d, δjl = 1 if there is a correlation between ηij and ηil , and δjl = 0
elsewhere. δjj = 0 means that the variance of the jth random effect is 0.
A diagonal covariance matrix is obtained by setting the matrix ∆ to
Assume now that the absorption rate does not vary between subjects
and that clearance and volume are correlated. Then, ∆ should be set to
You can also assume different variances in the groups defined by a categorical covariate (click on
the button Cat.var. ).
Assume for example that the variance of the volume depends
on the gender
Remark: In the different groups, the random effects have different variances but the same correlations. In this example, the
correlation between Volume and Clearance is the same for male and
female.
52
Monolix 4.3.3
The “Initialization” frame
3.3.7
The observations model
The observations model can be defined in the structural model function (for discrete data:
count, categorical, RTTE, etc) or it can be a residual error model (for continuous data).
The observation model section shows, for each observation, the variables name and their type following the structural model definition. If
the observation name is not set in the structural model (for continuous
observations, it can be given the prediction name instead, see Mlxtran
models description) then it can be defined by the user using the interface.
For the continuous observations, we consider the general form y = f + g e where e is a sequence
of independent random variables normally distributed with mean 0 and variance 1.
Some extensions assume that there is a transformation t such that t(y) = t(f ) + g e. It is also
possible to assume that the residual errors are correlated. Here are some examples of error
models:
const:
constant error model y = f + a e
prop:
proportional error model y = f + b f e
comb1:
combined error model y = f + (a + b f )e
comb2:
combined error model y = f + a e1 + b f e2
propc:
proportional error model + power y = f + b f c e
comb1c:
combined error model + power y = f + (a + b f c )e
comb2c:
combined error model + power y = f + a e1 + b f c e2
exp:
exponential error model t(y) = log(y) and y = f ea e
logit:
logit error model t(y) = log(y/(1 − y))
band(A,B): extended logit error model t(y) = log((y − A)/(B − y))
Select the checkbox r if you want to consider autocorrelation on the residual errors.
You can also constrain the second parameter b in comb1 and comb1c
error models to be positive by checking b>0
3.4
The “Initialization” frame
Initial values are specified for the Fixed effects, for the Variances of the random effects
and for the Residual error parameters. It is usually recommended to run SAEM with different
initializations and to compare the results (see convergence assessment tool in Section 3.7.7).
A right click on an initial value displays a list with three options.
The default choice is Estimate for maximum likelihood estimation.
The choice of the “Fixed” option (initial values in pink), means that
this parameter must be kept to its initial value and so, it will not be
estimated. Use the Priors option (initial values in blue) to specify
a prior distribution for this parameter.
Only the two options Estimate and Fixed are available for the variances and residual error model
parameters
53
Monolix 4.3.3
The “Algorithm” frame
You can also switch between to estimate standard deviations or
variances
3.4.1
Check initial fixed effects
The fits obtained with the initial fixed effects are displayed for continuous observations. It can
be useful in case of complex models (e.g. defined with differential equations), in order to find
some “good” initial values. You can change the values of the parameters with the buttons + and
- and see how the fits change.
3.4.2
Use the last estimates
If you have already estimated the population parameters for this project, then you can use the
Use the last estimates button to use the previous estimates as initial values.
3.5
The “Algorithm” frame
There are several settings that control the behavior of the algorithms and the results graphics
and tables generation (see Section 3.13). The main interface gives access directly to some of
them:
• Seed: The default value of the seed used for the random numbers generator is 123456.
This seed can be randomly generated with the New seed button.
54
Monolix 4.3.3
The “Results” frame
• Number of iterations: There are two stages in the population parameters estimation
algorithm. Use K1 and K2 to define the number of iterations for each one.
If auto is selected, then algorithm will determine automatically if it can jump from one stage to the other or if it can
finish the estimation process. In this case, the numbers K1 and
K2 will represent the maximum number of iterations for each
stage. Here, these numbers will not exceed 500 and 200.
• Number of chains: When the dataset is small, just a few of subjects for instance, replicating the dataset can improve the precision of the estimation. The number of (Markov)
chains specifies how many times the dataset need to be replicated.
You can specify this number yourself,
or you can let Monolix to compute how many replicates
are needed to ensure a minimum number of subjects. In this
case, you should specify this minimum size and any time you
change the dataset, the number of chains will be updated according to the number of subjects present in the new dataset.
For instance, in the theophylline example there are only 12 subjects in the dataset. Setting
to 50 the minimum number of subjects, Monolix choose to use 5 Markov chains.
• Simulated annealing: A Simulated Annealing version of SAEM is used to estimate the
population parameters (the variances are constrained to decrease or increase slowly during
the first iterations of SAEM, see Section 3.13.1)
• Monte-Carlo Sizes: It can be specified the number of simulated samples used to compute
Prediction distribution graphic, the NPDEs (Normalized Prediction Distribution Errors)
and the VPCs (Visual Predictive Checks), the log-likelihood estimation when the Importance Sampling algorithm is used (see Section 3.7.4)
• Display: The number of iterations between two updates of the convergence graphics
produced by the algorithm (e.g. SAEM convergence window when estimating population
parameters).
3.6
The “Results” frame
• The Results folder is the folder where all the results are stored.
55
Monolix 4.3.3
Executing tasks
– Project name: the result folder is determined automatically from the name of the
project as “<project folder>/<project name>/”.
– User defined name: the name and the directory of the results folder are defined by
the user.
• Standard errors: Which algorithm to use when computing Fisher Information Matrix and
standard errors. Can be by Linearization (using a linear approximation of the model)
or by Stochastic Approximation (the observed Fisher Information Matrix of the exact
model is estimated by stochastic approximation).
• Individual parameters: says if the Conditional modes and/or Conditional means and
standard deviations should be computed when estimating the individual parameters
• Log-likelihood: says which algorithms to use when estimating the log-likelihood. Can
be by Linearization (using a linear approximation of the model) and/or by Importance
Sampling (the log-likelihood of the exact model is estimated by Monte-Carlo).
• Graphics: Use List button to choose the list of graphics to produce when the results are
computed.
3.7
Executing tasks
Monolix includes several estimation algorithms: estimation of the population parameters, the
Fisher information matrix and standard errors, the individual parameters, and log-likelihood.
Also, different types of results are available in the form of graphics and tables.
We will consider the following project with the theophylline data for illustration. Here, the
log-weight centered by the mean is used as a continuous covariate and the gender as categorical.
56
Monolix 4.3.3
Executing tasks
3.7.1
Estimation of the population parameters
Maximum likelihood estimation of the population parameters is performed with the
button.
The sequence of estimated parameters (θk ) is displayed in a figure which is automatically saved
as saem.png in the results folder at the end of the estimation. Also, the final estimations are
displayed in the Matlab command window.
This algorithm produces the file pop_parameters.txt in the result folder, with all the estimated
parameters: population parameters, variances (or standard deviations), correlations, error model
parameters, etc. It also includes the project filename, the date and hour of the run, and the
version of Monolix . The estimation of the population parameters by groups defined by the
categorical covariates used in the model are also given.
The same information is printed in the screen (Matlab command window for Matlab version
and DOS or linux terminal for standalone version). The algorithm convergence graph (saem.png),
as well as a copy of the used project in .mat and .xmlx formats are also saved. Also, if the
structural model is coded using Mlxtran, a copy of this file is included.
. theophylline example:
The final estimations for our example, and the convergence graphics for this exemple are:
We clearly see on these graphics that the trajectory of (θk ) is much more random during the
first stage than during the second stage. The number of iterations used for the SAEM algorithm
were K1 = 173 and K2 = 120.
Remark 1: This figure shows that, despite a very poor initial guess, SAEM algorithm converges
57
Monolix 4.3.3
Executing tasks
in very few iterations to the neighborhood of the solution. Thus, in this example, a good
estimation of the parameters can be obtained with very few iterations of SAEM (try for instance
with K1 = K2 = 20 and any initial guess...). Also simulated annealing is not necessary for this
project.
However it is not always the case. One can see in the figure below that the choice of the
first number K1 of iterations is crucial. In this example, the total number of iterations is
K1 + K2 = 100, with K1 = 50 on the left and K1 = 1 on the right. The second example shows
that K1 = 1 iterations is not enough to reach the neighborhood of the solution. Then, because of
the averaging during the K2 next iterations, SAEM will require many more iterations to converge
than in the first example.
Remark 2: The individual parameters of each subject are “roughly” estimated during the last
iterations of SAEM (by estimating the conditional means E(φi |y; θ̂)). These “rough” estimates
are used for the results if the individual parameters are not better estimated later.
3.7.2
Estimation of the standard errors
Computes Fisher information matrix and so the standard errors of the different estimators and
their correlation. There are two different algorithms: by linearization where the structural
model is linearized, and so the full statistical model is approximated by a gaussian model, or by
58
Monolix 4.3.3
Executing tasks
A "nice convergence" of SAEM
A "poor convergence" of SAEM
Stochastic approximation where the exact model is used, and the Fisher information matrix
(F.I.M) is approximated stochastically (slower but more precise).
The final estimations are displayed in the command Matlab window together with the popula59
Monolix 4.3.3
Executing tasks
tion parameters:
1. the estimated fixed effects, their standard-errors, the absolute and relative p-values obtained
from the Wald test (only for the coefficients of the covariates),
2. the estimated variances (or standard deviations) and their standard-errors,
3. the estimated residual error parameters and their standard-errors,
4. the estimated correlation matrix of the random effects if the covariance matrix is not
diagonal,
5. the correlation matrix of the fixed effect estimates, with the smallest and largest eigenvalues,
6. the correlation matrix of the variance components estimates, with the smallest and largest
eigenvalues,
All that information is appended to the file pop_parameters.txt.
60
Monolix 4.3.3
Executing tasks
. theophylline example:
Remark: The Wald test indicates here that βW,V and βS,Cl are not significantly different
from 0: we can consider that the log-volume is not a linear function of the log-weight, and that
the clearance of the males and females are not significatively different (of course any statistical
inference with only 12 subjects can be dubious. . . ).
3.7.3
Estimation of the individual parameters
Although the population parameter estimation algorithm gives a rough estimation of the individual parameters, it can be estimated two more precise estimators: the conditional mode and
the conditional means. Those estimators can be computed with the
button.
If the option Estimate the conditional modes is selected, the individual parameters are estimated by maximizing the conditional probabilities p(φi |yi ; θ̂).
61
Monolix 4.3.3
Executing tasks
If the option Estimate the cond. means and s.d. is selected, the conditional means and
standard deviations are estimated by MCMC. For each parameter, the mean of these quantities
over all the subjects is displayed together with a rmcmc interval.
Two files indiv_parameters.txt and indiv_eta.txt are created with the estimated individual
parameters and random effects in table format. Also, if there were defined priors on some
fixed effects, and it was selected prior distribution method for some of them, a new file called
simulatedPopParams.txt is created simulations using their posterior distribution laws.
. theophylline example:
Here, rmcmc = 5% and Lmcmc = 50
3.7.4
Estimation of the log-likelihood
The estimation of the log-likelihood is performed with the
button. Two different algorithms
are proposed to estimate the log-likelihood: by linearization and by Importance sampling.
. theophylline example:
In our example, the two different estimates of the log-likelihood are computed.
The value of the two estimated −2× log-likelihoods, the standard error of the Monte-Carlo
estimate, The AIC and the BIC are displayed in the command Matlab window:
62
Monolix 4.3.3
Executing tasks
The Monte-Carlo estimator converges to the observed log-likelihood when the size of the MonteCarlo increases. The sequence of estimates, as a function of the Monte-Carlo size, is displayed
as a Figure:
The estimated log-likelihoods are appended to pop_parameters.txt.
Remark: The log-likelihood can not be computed by linearization for discrete outputs (categorical, count, etc.) nor for mixture models or when the posterior distribution have been
estimated for some parameters with priors.
3.7.5
Computing results
Use the button
to compute produce some graphics and tables.
It is possible to specify the list of graphics (with button List at the bottom of the main interface), which of them should be saved and which tables should be produced (menu Graphics->Outputs
to save). For more details see Section 3.8.
63
Monolix 4.3.3
Executing tasks
3.7.6
Running several algorithms
With the button Run , you can executes successively several tasks. The list of tasks to run is
called “scenario” or “workflow”. You can define your own scenario by checking the corresponding
checkboxes at the left of the Run button.
For example, define the following workflow
in order to:
1. estimate the population parameters,
2. estimate the standard errors,
3. estimate the individual parameters,
4. display graphical results using the individual parameters estimated previously.
If you just want to compute the population parameters with their standard errors, define the
workflow:
3.7.7
Algorithms convergence assessment
Monolix includes a convergence assessment tool. It is possible to execute a workflow as defined
above but for different, randomly generated, initial values of fixed effects.
Click in the Assessment button on the workflow bar to
open the Assessment graphical interface.
You can enter the number of runs, or replicates, the parameters to generate initial values and
the intervals where those values should be (uniformly) simulated. Click on Run to execute the
tool.
64
Monolix 4.3.3
Executing tasks
Remarks:
• The project workflow is used (see Section 3.7.6).
• Population parameters estimation must be selected.
• A result folder is generated for each set of initial parameters.
Two kinds of graphics are given as a summary of the results,
one showing the estimated values (blue)
with the estimated standard errors (red bars) for
each replicate (if the Fisher information matrix
estimation was included in the scenario)
65
Monolix 4.3.3
Plots and results
and the superimposed convergence graphics
for each parameter. In case of F.I.M estimation
is included, then the black lines represents the
mean of the estimated s.e.
Also, a .mat file is produced with all the results used for those graphics. Press Last Results
button to reproduce the last result graphics if you already have ran the tool for the current
project, and Cancel to close the interface.
3.8
Plots and results
From the main interface toolbar, you can
• display the observed data y as a function of the regression variable (e.g. time for a PK
applications): .
• Produce several graphics and tables from the results of the algorithms:
You can select which figures to show in menu Graphics->List or button List in the
interface (see Section 3.8.4) and which figures and/or tables to save (Section 3.8.6)
You can also produce one specific graphic.
Note: By default the new projects do not save the graphics and do not produce the tables.
If you want Monolix to create some table, you must select it in menu Graphics->Output to
save.
Monolix allows to change some visual preferences determining the way the graphics are shown
(set of line colors and styles, markers, etc). It is also possible to specify the format where the
graphics should be saved. Section 4.14 shows how you can set some preferences with an interface
and Appendix C gives an overview of all the parameters that can be set and how.
3.8.1
The graphics
The proposed figures are separated in three groups:
• Reduced: Graphics rapid to create, good to have a first view of the goodness of the fits.
66
Monolix 4.3.3
Plots and results
• Simulation: Graphics requiring simulations, so the can take some time to be produced.
Includes some Visual Predictive Checks (VPC) graphics.
• Others: other graphics proposed.
Reduced :
Project Summary: displays some information about the project (date, datafile,. . . )
Spaghetti plot: displays the original data
as a “spaghetti plot”.
Individual fits: displays the individual
fits, using the population parameters with the
individual covariates (red) and the individual parameters (green) on a continuous grid.
It is also possible to display the median and
a confidence interval for (yij ) estimated with a
Monte Carlo procedure. The design and the covariates of each subject are used for the simulation.
67
Monolix 4.3.3
Plots and results
Obs. vs Pred.: displays observations versus the predictions (ŷij ) computed using the
population parameters (on the left), and with
the individual parameters (on the right)
Covariates: displays the estimators of the
individual parameters in the gaussian space, and
those for random effects, (e.g. the conditional
expectations E(ϕi` |y; θ̂) and E(ηi` |y; θ̂), 1 ≤ i ≤
N and the conditional modes) v.s. the covariates.
Parameter Distributions: displays the
estimated population distributions of the individual parameters. Settings allows you to show a
summary of the theoretical distributions (mean,
median, mode, quartiles, percentiles, standarddeviation), histograms, and a non-parametric estimation of the distribution
68
Monolix 4.3.3
Plots and results
It is also possible to display the empirical
distribution of the individual parameters and the
shrinkages computed as follows for each random
effect:
Var(η̂)
Shrinkage = 1 −
ω̂ 2
Random Effects(boxplot): displays the
distribution of the random effects with boxplots.
The horizontal dotted lines show the interquartile interval of a standard Gaussian distribution.
Random Effects(joint dist.): generates
scatter plots for each pairs of random effects.
69
Monolix 4.3.3
Plots and results
Convergence SAEM: displays the sequence of
the estimated parameters (θk ).
Simulations :
Residuals: displays the PWRES (population weighted residuals), the IWRES (individual
weighted residuals) and the NPDE (Normalized
Prediction Distribution Errors) v.s. x (top) and
v.s. the predictions (bottom).
The PWRES are computed using the
population parameters and the IWRES are
computed using the individual parameters.
For discrete outputs, only NPDE and individual
NPDE are used.
For continuous outputs, this figure shows
the empirical distributions of the weighted
residuals and the NPDE together with the
standard Gaussian pdf and qqplots to check if
the residuals are Gaussian.
70
Monolix 4.3.3
Plots and results
Diagnostic VPC: Allows to compare the
empirical distribution of the observations and
theoretical distribution (computed from simulations in observation times) inside some parameterizable bins.
NPC: Allows to compare empirical cumulative distribution function (CDF) of the observations with theoretical’s (computed from simulations).
BLQ: Shows the proportion of censored data
on time. It is possible to chose the censoring interval. This graphic is only available for projects
with censored data.
71
Monolix 4.3.3
Plots and results
Prediction distribution: Allows to compare the observations with the theoretical distribution of the predictions.
Others :
Categorized data: Allows to check the distribution of the observations in categories that
can be parameterized by the user.
Time to Event data: Shows empiric (from
observations) and theoretical (from simulations)
survival function and average number of events
for Time to event data. Only available for outputs of type event.
72
Monolix 4.3.3
Plots and results
Transition Probabilities: For discrete
observations, shows the proportion of each category knowing the previous one. Can be used on
any discrete model.
Posterior Distribution: Shows the priors (theoretical) and the posterior (simulations)
distributions for each parameter estimated by
“posterior distribution”. Requires the estimation
of the conditional means of the individual parameters.
Contribution to log-likelihood: Displays the contribution of each subject observations to the total log-likelihood. Requires the
estimation of the log-likelihood, and both estimators are shown if they have been computed.
73
Monolix 4.3.3
Plots and results
3.8.2
The tables
Monolix can produce five kinds of ASCII table files:
• Observation times contains the regression variables, the individual predictions, the population predictions, the weighted population residuals, the weighted individual residuals
and the NPDE, for all the observation times in the dataset.
• Fine-grid times contains the regression variables, the individual predictions, the population predictions in a fine (regular) grid.
• All times contains the regression variables, the individual predictions, the population
predictions for a possibly larger set of times in the dataset, including observation times,
lines where MDV column is set to 2.
• LL individuals contribution contains subject contribution to the total log-likelihood.
• Covariates summary contains a summary of all the covariates defined in the project.
The first three tables can include new columns according to the table definition in the structural
model as described in Section 4.11.
3.8.3
The graphics menu bar
The graphics menu bar proposes different options
• It is possible to save, close or print the figure and, in Windows, to copy and paste it to any
other document.
• Zoom menu activates or de-activates the zoom
• The Axes menu proposes to use semi-log or log-log scale plots. Settings option gives the
opportunity to choose labels and to change the scale of graphics. It is also possible to use
the same axis limits for the different plots of the same graphic.
• The Stratify menu opens the stratify window, see Section 3.8.5 below.
• The Settings menu opens a new window with the settings of the current graphic.
3.8.4
Main interface Graphics Menu
This menu options allows to handle the graphics configurations of the project, which are used
each time the results figures and tables are launched. Those configurations have three parts: the
list of result graphics to produce, each graphic settings and the list of graphics to save and tables
74
Monolix 4.3.3
Plots and results
to produce.
There are 5 options in Monolix Graphics menu.
• Attach the current settings to
project
• List
• Settings
• Outputs to save
• Export graphics data
Attach the current settings to project
When this option is chosen, the current settings of the opened figures are used as current project
defaults.
List
This menu allows to manage the list of graphics to display.
Three options are available :
• Load
Allows to load already defined lists. Those lists are divided in two section: Monolix
predefined lists and user defined lists.
The chosen list determines the figures that will be opened next time the results graphics
are launched (button
).
• New
Allows to define and save a list.
75
Monolix 4.3.3
Plots and results
This option opens a window that allows to create a list and then either to export to a
.xmlx file or to use in the current project.
Monolix proposes four predefined lists: Reduced, Simulation, Others as explained in
Section 3.8.1, and All. The default list is reduced.
To define the list, it should be selected which graphics to show for each output (checkboxes
at the left, each column represents an output) and how many times (at the right).
It is possible to launch a single graphic by clicking on the corresponding button.
76
Monolix 4.3.3
Plots and results
To export the defined list, use the Save button. The list should be saved in the proposed
folder to be used by Monolix.
In order to use the defined list in the current project, click on the button OK.
Remark : This window is available in Monolix main interface.
• Save
Saves project’s graphic list
77
Monolix 4.3.3
Plots and results
• Remove
Remove an user defined list.
Settings
Allows to handle predefined graphic configurations : load, save and remove.
• Load
Allows to load already defined configurations. Those configurations are divided in two
section: Monolix predefined configurations and user defined configurations.
The opened graphics are automatically updated when a configuration is loaded.
• Save
Allows to save a current configuration. The saved file will be included to the Load list.
Enter a name to save the configuration.
78
Monolix 4.3.3
Plots and results
• Remove
Remove an user defined configuration.
Export graphics data
This feature is used to export graphics data in the aim to reproduce his own graphics. For each
generated graphic, one (or severals) table(s)goresse passssssssss will be created in the results
folder.
3.8.5
Stratify
The Stratify menu allows to create and use covariates for stratification purposes. It is possible
to select a categorical covariate for splitting, filtering or coloring the dataset. Also, in the bottom
section, it can be defined a time filter
79
Monolix 4.3.3
Plots and results
3.8.6
Settings
Each graphic has its own settings, which can be accessed by Settings menu. The most common
types of options are described below.
Display options
Most of the graphical components can be made visible or hidden, allowing the user to focus on
the desired information.
For some graphics, it is possible to select which plots to show.
Prediction Distribution with two different configurations
Stratify options
Some graphics can be stratified using the filters issued from the Stratify interface mentioned in
Section 3.8.5. It is possible to activate the splits, filters, and/or colors for groups of individuals
and also to filter observations for some time interval (the first regression variable is used if no
time column exists).
80
Monolix 4.3.3
Plots and results
Residuals with 2 kinds of residuals with scatter plots (predictions) and QQ-plot chosen
Predictions Vs Observations without applying stratify
81
Monolix 4.3.3
Plots and results
Split: Predictions Vs Observations with Split option set
Individuals filter: Predictions Vs Observations with Filter (individuals) option set
82
Monolix 4.3.3
Plots and results
Color: Predictions Vs Observations with Color option set
Observations filter: Predictions Vs Observations with Filter (observations) option set
83
Monolix 4.3.3
Plots and results
Saving graphics
It is possible to choose which graphics to save. Clicking on Outputs to save in Graphics menu,
a window is opened :
The save starts after the display of the graphics.
Computations options
The user can modify some parameters required to compute the information to be represented.
This allows him to tune the graphics.
84
Monolix 4.3.3
Testing hypotheses
Figure 3.1: BLQ settings
Figure 3.2: Bins settings
Share
Some options are identical for several graphics and can be set
independently from one graphic to the other. The button Share
allows to set the current values to all the graphics sharing those
options. The following table describes links between the different
graphics. The three columns contain respectively the shared options, the Share button name, and the concerned graphics.
Option
BLQ
Button name
Share settings
BINS
Share settings
Estimators
Share selection
3.9
Graphics
Predictions Vs Observations
Residuals
VPC
NPC
Residuals
VPC
Categorized data
Parameter distribution
Random effects (boxplot)
Joint distribution
Testing hypotheses
Three kind of tests can be performed:
85
Monolix 4.3.3
Testing hypotheses
•
tests the covariate model for the fixed effects,
•
tests the covariance model for the random effects,
•
tests the residual variance model.
The
button allows to define the matrix A0 and A1 that define the covariate model under
hypotheses H0 and H1 . Consider as an example that we want to test whether the clearance of
a subject is function of his weight. Thus, assuming that the absorption rate and the volume are
not function of any covariate under both hypotheses, we want to test model H1 against model
H0 defined as follows:
The other parameters used for the model and the algorithm are those defined in the main
Monolix window.
The maximum likelihood estimate and the likelihood are computed under both hypotheses. For
b
both hypotheses, the AIC and BIC criteria are displayed, together with the deviance (−2 × log `(y; θ)).
The brackets contain the s.e. of these statistics. The Likelihood Ratio Test (LRT) is performed
and the level of significance (p-value) is displayed. Here, the log-likelihood is estimated using a
Monte-Carlo Importance Sampling algorithm. The Monte-Carlo size is defined as the “LL” size
in the Monolix window.
. theophylline example:
Here, AIC, BIC and the LRT agree with the Wald test to conclude that β(W EIGHT,Cl) is not
significant (then, there is no significant effect of the weight on the clearance).
The
button allows to define the structure of the covariance matrix Ω0 and Ω1 of the random
effects under hypothesis H0 and H1 .
The
button allows to define the residual variance models under hypothesis H0 and H1 .
A file is generated for each test with the estimations for each hypothesis test and the comparison
results.
86
Monolix 4.3.3
Simulation
3.10
Use the
datasets.
Simulation
button to open the simulation interface in order to create one or several simulated
From this interface you can simulate new datasets.
A set of (ỹij ) is simulated using the regression variables (xij ) and the covariates of the original
dataset. The simulated data has exactly the same format than in the original data. The only
difference is that the observed (yij ) are replaced with the simulated ones (ỹij ).
You are free to set the population parameters yourself or you can use the estimated values, or
the initial values given in the main interface.
By clicking on the button Design data file , you can also change the design (number of
subjects, observation times, covariate values, etc) used for simulations by selecting a new dataset
from this interface. However, the chosen dataset must contain exactly the same covariates that
were used in the main interface (same name and type among categorical or continuous).
It is also possible to simulate several replicates with the same parameters. All the replicates are
stored in the same file and a column REPL (for replicate) is added.
You can specify different sources of variability for simulating this dataset: random effects, residual
error, uncertainty of the estimates (only if the parameters were estimated).
If you want to simulate with censored data, select LOQ. The opened dialog allows to select
the censoring intervals. For each output, you can enter one number to specify the LOQ so the
observations are censored if Y sim ≤ LOQ, or an interval [A, B] to censor if A ≤ Y sim ≤ B.
87
Monolix 4.3.3
Publishing the outputs
3.11
Publishing the outputs
Beware: this feature is not available with the stand-alone version of Monolix.
Use the
button to generate a report on your project, including figures and results.
Use the edit button to modify the Matlab script which selects the different procedures that will be executed.
You can generate your report as a html, doc, xml or latex file
and all the files will be saved in the results folder.
3.12
The results folder
As explained before, several output files are generated by the different tasks. All of them are
saved in the result folder chosen by the user (see Section 3.7.5). Here we make a summary of
some of those files and when are they generated.
1. With the population parameters estimation (button ):
• results.mat is a binary "MAT-file" file that contains all the results
• project.mat and project.xmlx contain the project respectively in .mat and .xmlx. Thus,
button and running the SAEM algorithm with
this project can be reloaded with the
the
button will reproduce the same results.
• pop_parameters.txt contains the estimated population parameters.
• saem.png is a PNG file where the sequence of estimates (θk ) is plotted.
Some of the variables stored in this results.mat are:
fixed_effects : the estimated fixed effects
(for the log-parameters in the case of log-normal distributions)
cov_random
: the estimated covariance matrix of the random effects
g_abc
: the estimated parameters of the error model
2. With the Fisher information matrix estimation (button
):
• The results of population parameters estimations are completed with the estimated squared
errors (s.e), the relative s.e and the p-value for covariates coefficients as shown in Section
3.7.2 and appended to the file pop_parameters.txt.
3. With the individual parameters estimation (button
):
• A file indiv_parameters.txt which contains the estimated individual parameters is generated: the conditional modes (m(φi |y; θ̂), 1 ≤ i ≤ N ) and/or the conditional expectation
88
Monolix 4.3.3
The results folder
r
(E φi |y; θ̂ , 1 ≤ i ≤ N ) with the conditional standard deviations ( Var φi |y; θ̂ , 1 ≤ i ≤
N ) and the covariates.
• A new file indiv_eta.txt that contains the estimated random effects is generated:
the
conditional modes (m(ηi |y; θ̂), 1 ≤ i ≤ N ) and/or the conditional expectation (E ηi |y; θ̂ , 1 ≤
r
i ≤ N ) with the conditional standard deviations ( Var ηi |y; θ̂ , 1 ≤ i ≤ N ) and the covariates.
• The file simulatedPriors.txt is created whenever it is estimated the posterior distribution
of parameters with priors and the conditional distributions (means and s.d) are estimated.
It contains some samples of those parameters simulated following the posterior distribution
4. With the log-likelihood estimation (button
):
• the value of the (-2)log-likelihood together with AIC, BIC are added at the bottom of the
file pop_parameters.txt.
The last three algorithms complete the results.mat file with their own results, adding fields
like
se_fixed
: the standard-errors of the estimated fixed effects
pv_fixed
: the p-values for the estimated fixed effects
(for the log-parameters in the case of log-normal distributions)
se_random
: the standard-errors of the diagonal elements of this estimated covariance matrix
se_g_abc
: the standard-errors of the estimated parameters of the error model
logl
: the estimated log-likelihood
condmode_param : the individual conditional mode of the parameters arg maxψ P(ψ|y)
condexp_param
: the individual conditional expectation of the parameters E(ψ|y)
condsd_param
: the individual conditional standard errors of the parameters
5. With the results ( ) button:
Produced ASCII table files if the corresponding tables were selected (see Section 3.8.2):
• predictions.txt contains Observation times table.
• finegrid.txt contains Fine-grid times table.
• fulltimes.txt contains Fine-grid times table.
• individualContributionToLL.txt contains LL individuals contribution table.
• covariatesSummary.txt contains Covariates summary table.
Produced graphic files:
Depending on the chosen figure format (see Section 4.14) you will have
• for Postscript (ps format):
89
Monolix 4.3.3
The results folder
– results.ps includes a selection of graphics: spaghetti-plots, residuals, observation
vs. predictions, etc.
– individual_fits.ps includes the individual fits for all subjects, plotted in several
pages.
• Any other format:
– One file for each graphic and several files for individual fits graphic, according to
the number of subjects in the dataset.
5. Other files:
• The hypothesis tests (buttons
,
,
) generate files with each test results.
• Publish report files
• Simulated files
• One .zip file for each run containing the corresponding results if timestamping has been
activated (see Section 4.14).
Note: The graphics are saved like they are produced, i.e using current graphics settings (see
Section 3.8.4) and window size. You can change the settings and set the figure container size
before re-run the Results. Or you can modify the graphic window itself and save it with the
menu Save As.
90
Monolix 4.3.3
Settings
3.13
3.13.1
Settings
The population parameters estimation
K0 is the number of burning iterations, K1 and K2 the numbers
of SAEM iterations. If auto is checked, K1 and K2 are automatically adjusted.
The sequence of stepsizes (γk ) decreases as 1/k aj , j = 1, 2. If
a1 = 0 and a2 = 1, then γk = 1 during the first K1 iterations and
γk = 1/(k − K1 − 1) during the next K2 iterations.
lK1 , lK2 and rK2 define the stopping rules when auto is checked.
The number of iterations K1 increases with lK1 ; K2 increases with
lK2 and decreases with rK2 .
The default number of Markov chains is L = 1.
m1 , m2 , m3 and m4 are the numbers of transitions of the four
different kernels used in the MCMC algorithm. The default value
of m2 is 0. Indeed this transition is recommended only in some
specific cases, when the observed kinetics are very different (i.e.
viral kinetics of responders, non responders, rebounders, ...).
When Simulated Annealing is checked, the temperature decreases as τ1k and τ2k . Note that you can use τj > 1 to force the
estimated variance(s) to increase from a small initial value to the
estimated value. Then, τ2k > 1 can be used if you want to obtain fits
as good as possible and τ1k > 1 if you want to obtain inter-subject
variability as small as possible.
3.13.2
The individual parameters estimation
MCMC is used to estimate the conditional distributions of
the individual parameters when Estimate the cond. means and
s.d. is checked.
m1 , m2 , m3 and m4 are the numbers of transitions of the four
different kernels used in the MCMC algorithm.
Lmcmc and rmcmc define the stopping rule of the MCMC algorithm. The number of iterations of MCMC increases with Lmcmc
and decreases with rmcmc .
91
Monolix 4.3.3
Settings
3.13.3
The log-likelihood
A t−distribution is used as proposal. The degrees of freedom
number of this distribution can be either fixed or optimized. In such
a case, the default possible values are 2, 5, 10 and 20 d.f..
A distribution with a small number of d.f. (i.e. heavy tails)
should be avoided in case of stiff ODE’s defined models. We recommend to set d.f. ≥ 5.
3.13.4
The results
You can set the Monte-Carlo sizes used for the VPC and NPDE
(default value is 500) and for Prediction distribution (default is 100).
You can also set the grid size used for graphics and tables using
continuous grids (like individual fits and prediction distribution).
3.13.5
Predefined scenarios
Monolix proposes the possibility to create, load and save predefined sets of settings called workflows. Each workflow include the
scenario, the algorithms and results settings. Four of them are proposed but users can define new ones by selecting all the settings for
the current project, and then saving it as workflow.
92
Monolix 4.3.3
Chapter 4
Advanced features
The different features of Monolix 4.3.3 are illustrated with several examples available in the
Demos folder.
4.1
Libraries of models
Several libraries with a large collection of pharmacokinetic and pharmacodynamic models are
included in the Monolix software (in the folder libraries):
• PK library: 1cpt, 2cpt and 3cpts PK models; linear and nonlinear eliminations; single
dose, multiple dose or steady-state designs.
• PKe0 library: PK models (1cpt and 2cpt) with an effect compartment (to be used with
a PD model).
• PD library: immediate response and turnover PD models.
• VK library: some basic viral kinetic models (HIV and HCV).
• Discrete library: some basic models for count data, ordered categorical data, and repeated time to event (RTTE) models.
To use one of these models, click on the button structural model, or right-click on the list of
currently selected models to open the Model List window. Select the library with the button
Monolix Library and select one model from the list.
Of course, you can create your own libraries. If you use the Matlab version of Monolix, you
can write new models with Matlab or Mlxtran. If you use the standalone version, you should
write your models with Mlxtran. See modelMLXTRANtutorial.pdf for more details.
4.2
Pharmacokinetic and pharmacodynamic data
Examples
93
Using priors on a fixed effect
warfarin: warfarin_PKPD1_project, warfarin_PKPD2a_project,
warfarin_PKPD2b_project, warfarin_PKPD3_project, warfarin_PKPD4_project
It is possible to simultaneously analyze pharmacokinetic and pharmacodynamic data, with a
pharmacokinetic function fP K and a pharmacodynamic function fP D . In this context,
• The observation column of the dataset contains both pharmacokinetic and pharmacodynamic observations. The YTYPE column indicates the type of each observation (1=PK and
2=PD),
• If you are using .m models of the library, the output of the fP K function is an input of the
function fP D :
1. Choose first the fP K function and choose the corresponding error model gP K .
2. Then use the + button to add the second model fP D and choose the corresponding
error model gP D . It is possible to remove the selected model from the Monolix
window using the - button. A right click on the list, after selecting the name of the
model, allows to change this model,
Examples: warfarin_PKPD1_project, warfarin_PKPD2a_project
• If you write your own model using Mlxtran, you need to define two outputs (one to fit
the data defined with YTYPE=1 and one to fit the data defined with YTYPE=2).
Examples: warfarin_PKPD2b_project, warfarin_PKPD3_project,
warfarin_PKPD4_project
• The individual parameter vector ϕ is the union of the PK and PD parameters,
• Set the initial values for the fixed effects and the variance of random effects as usual, Set
the initial values of the two error models,
• Run the estimation algorithm,
• The button
displays the spaghetti plots for both types of observations in two figures.
• The button
output.
displays the chosen result figures and tables (see Section 3.8.4) for each
4.3
Using priors on a fixed effect
When you select to define a prior distribution on a fixed effect, a new window will open to define
its law. As for individual parameters, you can choose from some given distributions (normal,
log-normal, logit-normal and probit-normal) or you can define your own as a transform T of a
gaussian distributed variable:
94
Monolix 4.3.3
Categorical covariate model
Assuming θ to be the chosen fixed effect
θ = t(Z)
where Z ∼ N (µZ , σZ2 ) is a gaussian distributed variable.
You must specify mθ the typical value of θ
(µZ = t−1 (mθ )) and the the variance or standard deviation of Z. By default, the current initial value will
be used as typical value. Also, selecting a different
typical value will set it automatically as initial value
for the corresponding parameter.
You can also choose between two estimation methods: M.A.P. and posterior distribution.
Note: Monolix can estimate the M.A.P only for
• gaussian priors if θ is a covariate coefficient (β)
• priors with same distribution than the corresponding individual parameter if θ is an intercept. For instance, if V is set as log-normal distributed, then the M.A.P of
θ = intercept of V
can only be computed for log-normal priors on θ.
4.4
Categorical covariate model
Examples
Categorical covariates: PDsim1_project, PDsim2_project, PDsim3_project,
phenorbabital2_project
Mixed effects models categorical covariates are described in Section A.2.3.
PDsim1_project, PDsim2_project, PDsim3_project are three pharmacodynamic examples.
PDsim1_data, PDsim2_data, PDsim3_data contain simulated data obtained using an Emax
model.
SEX is used as a categorical covariate: SEX= 0 for males and SEX= 1 for females.
Different models are used C50:
• PDsim1_data and PDsim2_data:
log(C50i ) = log(C50pop ) + β 1SEXi =1 + ηC50,i
PDsim1_data was generated using β = 0 while PDsim2_data was generated generated using
β = 0.4.
• PDsim3_data:
log(C50i ) = log(C50pop ) + ηC50,i
where V ar(C50i ) = (0.1)2 if SEXi = 0 and V ar(C50i ) = (0.3)2 if SEXi = 1.
95
Monolix 4.3.3
Model with censored data
phenobarbital2_project illustrates how to transform a categorical covariate.
Here, the AP GAR score is classified
into 3 groups: Low (AP GAR <= 3),
Medium (4 <= AP GAR <= 7),
High
(AP GAR >= 8). Just click on the name
of the groups to rename them.
4.5
4.5.1
Model with censored data
Modeling BLQ data
Examples
theophylline:
theophylline_cens1_project, theophylline_cens2_project
Mixed effects models with BLQ data are described Section A.5.
As an illustration, we will consider a censored version of the theophylline data.
The data files theophylline_cens1_data.txt and theophylline_cens2_data.txt are the same
as the original data file theophylline_data.txt used in the previous section but with several
left-censored observations (yij ). The limit of quantification (LOQij ) can be the same for all the
patients (see theophylline_cens1_data.txt) or it can vary from one patient to another, and
even from one observation time to another (see theophylline_cens2_data.txt) . In the data
set which includes BLQ data, the censored observations are replaced with the LOQ values and
a new column CENS is added with a binary variable equal to 1 if the observation is censored and
0 otherwise.
ID
1
1
1
..
.
DOSE
4.02
.
.
..
.
TIME
0
0.25
0.57
..
.
Y
.
3.00
6.57
..
.
WEIGHT
79.6
79.6
79.6
..
.
CENS
0
1
0
..
.
2
2
2
..
.
4.4
.
.
..
.
0
0.27
0.52
..
.
.
2.5
7.91
..
.
72.4
72.4
72.4
..
.
0
1
0
..
.
12
5.3
24.15
3.00
60.5
1
In the Data Information window, this new column is referenced with the CENS header.
Then, Monolix can be used as usual. The button
displays the same figures as the usual
MCMC-SAEM with points associated to a censored observation displayed differently.
96
Monolix 4.3.3
Model with inter-occasion variability
4.5.2
Modeling interval censored data
Examples
censored_data:
censored_project
In order to handle right-censored data, the column CENS can take −1 as value to tell that
(cens)
yij
≥ LOQij where LOQij is the value given in the dataset on the corresponding line of
column Y.
To give both limits of interval censored data, a new column LIMIT is needed to specify the lower
limit while the Y value gives the upper limit. For this, the CENS column must be 1.
For instance, assume that we have the following dataset
(1)
(2)
(3)
(4)
(5)
ID
1
1
1
1
..
.
TIME
0
0
0.5
1
..
.
AMT
50.00
.
.
.
..
.
Y
.
90
2
2
..
.
YTYPE
.
2
1
1
..
.
LIMIT
.
.
.
1
..
.
CENS
.
-1
1
1
..
.
(2)
Line (3) says that the observation of type Y T Y P E = 2 at time 0 is right-censored (y11 ≥ 90),
(1)
line (4) says that the first observation of type Y T Y P E = 1 is left-censored (y11 ≤ 2), and line
(1)
(5) says that the observation is interval censored (y12 ∈ (1, 2)) because of the existence of a
numerical value in column Limit
4.6
Model with inter-occasion variability
Examples
IOV: iov1_project, iov2_project, iov3_project, iov4_project
Mixed effects models with IOV are described Section A.6.
Occasions are defined in the datafile, using a column OCC or a column EVID.
Then inter-occasion variabilility (IOV) can be introduced in the model with the IOV button. The
covariate model and the covariance structure of the IOV are defined in a new window. According
to the model described in Section A.6, we consider two kinds of covariates. The covariates that
do not change with the occasion are displayed in the main Monolix window and the covariates
that change with the occasion are displayed in the IOV window.
Example 1: iov1_project
A cross-over study was simulated. The data set iov1a_data.txt contains the column OCC and
two categorical covariates, TREAT for treatment and SEX. Since the first time for each occasion is
0, Monolix guesses that there is no “overlapping” between the occasions.
97
Monolix 4.3.3
Model with inter-occasion variability
Here, the treatment (A or B) changes with the occasion. Thus, TREAT is a covariate that will
appear in the IOV window as well as OCC. Furthermore, the sequence of treatments is not the
same for all the subjects (A-B for some patients and B-A for the other ones). Thus, the treatment
sequence (denoted S-TREAT) can be considered as a new covariate (this does not change with the
occasion). Monolix automatically creates this new categorical covariate and displays it in the
main Monolix window.
On the other hand, S-OCC is not created as a new categorical covariate because all the subjects
have the same sequence 1-2 in this example.
SAEM estimates the two covariance matrices and the coefficient of the different covariates:
98
Monolix 4.3.3
Model with inter-occasion variability
Example 2: iov2_project
We use the same simulated data as in the previous example (iov1_data.txt). Here, the occasions are defined with EVID=4 and the initial times for each occasion are arbitrary.
Example 3: iov3_project
Data with several occasions without wash-out was simulated. Here, the occasions are defined
with the column OCC. Without EVID=4 and with increasing times, Monolix guesses that there
is some “overlapping” between the occasions
Important: Overlapping between occasions can only be handled with a model defined by a system of differential equations using Mlxtran. Analytic solution of the PK model (i.e. Matlab
models of the PK library) cannot be used in this situations.
Example 4: iov4_project
There is an additional level of inter-occasion variability. Data was simulated with
covariance structure:





0 0 0
1 0 0
1 0
(2)
(1)





0 1 0
0 0 0
0 1
, IOV
=
IIV =
, IOV
=
0 0 1
0 0 1
0 0
the following

0
0 
0
Running population parameter estimations, you will see that, for each variability level, the
estimated variances are closed to 0 for those parameters that where simulated without variability
at that levels.
Note: When there is OCC column or EVID= 4, it is not possible to use the simulation interface,
nor hypothesis tests on covariance models.
99
Monolix 4.3.3
Discrete data models
4.7
Discrete data models
Examples
discrete data: categorical1_project, categorical2_project, count1_project,
count2_project, markov1a_project, markov1b_project, markov2_project,
hmm0_project, hmm1_project, rtteExpo_project,
warfarin: warfarin_cat1_project, warfarin_cat2_project
Mixed effects models for discrete data are described in Section A.7.
All the Mlxtran models shown in this section are also stored in the discreteLibrary folder.
Either Mlxtran or Matlab (if you are using the Matlab version of Monolix) can be used
to create models for discrete data. The output of the model should be the log-likelihood.
4.7.1
ordered categorical data models
In these examples, the outcome can take four possible values: 0, 1, 2, 3.
Example 1: categorical1_project
Its Mlxtran model is categorical1_mlxt.txt:
DESCRIPTION: Ordered categorical model
INPUT:
parameter = {th1, th2, th3}
regresor = {PER, DOSE}
OBSERVATION:
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
}
P (Y = 0)
=
P (Y ≤ 1)
=
P (Y ≤ 2)
=
1
1 + e−θ1
1
1 + e−θ1 −θ2
1
1 + e−θ1 −θ2 −θ3
OUTPUT:
output = level
Example 2: categorical2_project
Its Mlxtran model is categorical2_mlxt.txt:
100
Monolix 4.3.3
Discrete data models
DESCRIPTION: Ordered categorical model with regression variables
INPUT:
parameter = {th1, th2, th3, th4, th5}
regresor = {PER, DOSE}
OBSERVATION:
level = {
type = categorical
categories = {0, 1, 2, 3}
logit(P(level<=0)) = th1 + th4*PER + th5*DOSE
logit(P(level<=1)) = th1 + th4*PER + th5*DOSE + th2
logit(P(level<=2)) = th1 + th4*PER + th5*DOSE + th2 + th3
}
P (Y = 0)
=
P (Y ≤ 1)
=
P (Y ≤ 2)
=
1
1 + e−θ1 −θ4 P ER−θ5 DOSE
1
1 + e−θ1 −θ4 P ER−θ5 DOSE−θ2
1
1 + e−θ1 −θ4 P ER−θ5 DOSE−θ2 −θ3
OUTPUT:
output = level
4.7.2
count data models
In these examples, the outcome can take any positive value: 0, 1, 2, 3,. . . .
The Mlxtran models are, respectively count1_mlxt.txt and count2_mlxt.txt.
Example 1: count1_project
DESCRIPTION: Basic Poisson model
INPUT:
parameter = lambda
OBSERVATION:
Y = { type = count,
log(P(Y=k)) = -lambda + k*log(lambda) - factln(k) }
P (Y = k)
=
e−λ λk
k!
OUTPUT:
output = Y
Example 2: count2_project
DESCRIPTION: Count data model, negative binomial distribution
INPUT:
parameter = {delta, lambda}
OBSERVATION:
Y = {
type = count
P (Y = k)
h1 = 1/(1+lambda*delta)
llam = log(h1)/delta
lh2 = log(1-h1)
=
1
Γ(k + 1/δ)
(1 + δλ)− δ
k! Γ(1/δ)
λ
λ + 1/δ
k
lg1 = gammaln(k+1/delta)
lg2 = gammaln(1/delta)
101
Monolix 4.3.3
Discrete data models
if (k > 0)
aux = llam + lg1 - lg2 + k*lh2 - factln(k)
else
aux = llam
end
log(P(Y=k)) = aux
}
OUTPUT:
output = Y
4.7.3
discrete Markov models
For discrete Markov models, you must specify the transition probability matrix and, optionally
the probability for the initial state.
Here we show two examples of models markov1b_mlxt.txt and markov2_mlxt.txt with 2 and
three states respectively.
INPUT:
parameter =
INPUT:
parameter =
{p, p11, p21}
OBSERVATION:
State = {
type = categorical
categories = {1,2,3}
dependence = Markov
logit(P(State<=1|State_p=1))
logit(P(State<=2|State_p=1))
logit(P(State<=1|State_p=2))
logit(P(State<=2|State_p=2))
logit(P(State<=1|State_p=3))
logit(P(State<=2|State_p=3))
}
OBSERVATION:
State = {
type = categorical
categories = {1,2}
dependence = Markov
P(State_1=1)= p
P(State=1|State_p=1) = p11
P(State=1|State_p=2) = p21
}
OUTPUT:
output=State
4.7.4
{a11, a12, a21, a22, a31, a32}
=
=
=
=
=
=
a11
a11+a12
a21
a21+a22
a31
a31+a32
OUTPUT:
output=State
hidden Markov models
• For i = 1, 2, . . . , N , let zi = (zij , j ≥ 1) be a Markov Chain with memory 1 that takes its
values in {1, 2, . . . M }:
P (zij = m|zi,j−1 , zi,j−2 , . . . zi,1 ) = P (zij = m|zi,j−1 )
• Let p`mi = P (zij = m|zi,j−1 = `) and Πi = (p`mi ) be the transition matrix of the Markov
Chain zi .
• Assume that (yij ) takes discrete values in {0, 1, 2, . . .} and that
P (yij = k|zi1 , zi2 , . . .) = Pψi (yij = k|zij )
102
Monolix 4.3.3
Discrete data models
Objective: Estimate the population distributions of the transition matrices (Πi ) and the individual parameters (ψi ).
In the following examples, mixtures of M = 2 Poisson distribution are used. The Matlab
models hmm1_mlx.m and hmm0_mlx.m are stored in the discreteLibrary folder.
Example 1: hmm1_project
The model hmm1_mlx.m assumes a HMM with M = 2 states
Here, M = 2,
p11 p12
Π =
p21 p22
1
p11 =
; p12 = 1 − p11
1 + e−β1
1
p21 =
; p22 = 1 − p21
−β
1 + e 1 +β2
and 2 Poisson distributions
if z = 1 ,
y ∼ Poisson(λ1 )
if z = 2 ,
y ∼ Poisson(λ2 )
Example 2: hmm0_project
Here, we use the same conditional distributions for (yij ) but the (zij ) are sequences of independent
random variables (Markov chain with memory 0).
p1 =
4.7.5
1
1 + e−β
;
p2 = 1 − p1
repeated time to event models (RTTE)
Examples: rtteExpo_project, rtteWeibull_project
Repeated events are observed at random times between day 0 and day 365 for 500 patients. The
first event which occurs after day 365 is not observed: the time of this event is censored. We
consider here a very simple model with a constant hazard function
h(t) = Hbase
In the data file rtte_data.txt, we use EVENT=1,2,... for the observed events and EVENT=0 for
the censored event:
103
Monolix 4.3.3
Discrete data models
ID
1
1
1
1
2
2
2
2
TIME
0
153
262
365
0
34
109
365
Y
0
1
2
0
0
1
2
0
The Mlxtran model is then
DESCRIPTION: RTTE with constant hazard function
INPUT:
parameter = Te
OBSERVATION:
Event = {type=event, hazard=1/Te}
OUTPUT:
output = Event
Other hazard functions can be defined as shown in rtteWeibull_project demo.
Note: It is not possible to use the simulation interface for RTTE data.
4.7.6
joint modelling of continuous and discrete outputs
To illustrate the ability of Monolix to model jointly continuous and discrete outputs, we use
the warfarin data assuming here that the PD of warfarin is an ordered categorical data with 3
possible scores: 1 if P CA < 30, 2 if 30 ≥ P CA ≤ 50 , 3 if P CA > 50. This new data is stored
in warfarin_cat_data.txt.
The Mlxtran models oral1_categorical_mlxt.txt and oral1_ke0_categorical_mlxt.txt
are stored in the libraryMLXTRAN folder next to the project file. Both models assume that the
probability of a high (resp. low) P CA decreases (resp. increases) with the concentration.
Example 1: warfarin_cat1_project
An immediate response model is used in this example:
DESCRIPTION: First order oral absorption with a lag-time, and ordered categorical data
INPUT:
parameter = {Tlag, ka, V, Cl, th1, th2, th3}
PK:
Cc= pkmodel(Tlag,ka,V,Cl)
OBSERVATION:
Level = {
type=categorical
104
Monolix 4.3.3
Complex residual error models
categories={1,2,3}
logit(P(Level<=1)) = -th1 + th2*Cc
logit(P(Level<=2)) = -th1 + th2*Cc + th3
}
OUTPUT:
output = {Cc, Level}
Example 2: warfarin_cat2_project
We use the same model as previously with an additional effect compartment
DESCRIPTION: First order oral absorption with a lag-time, effect compartment,
and ordered categorical data
INPUT:
parameter = {Tlag, ka, V, Cl, ke0, th1, th2, th3}
EQUATION:
{Cc,Ce}= pkmodel(Tlag,ka,V,Cl,ke0)
OBSERVATION:
Level = {
type=categorical
categories={1,2,3}
logit(P(Level<=1)) = -th1 + th2*Ce
logit(P(Level<=2)) = -th1 + th2*Ce + th3
}
OUTPUT:
output = {Cc, Level}
Demos pkrtteExpo_project and pkrtteWeibull_project are two examples where PK data is
modeled at the same time than RTTE data.
4.8
Complex residual error models
Examples
error model:
PKcorr1_project, PKcorr2_project, Emax_errorband_project
Residual error models are described in Section A.3 and their use with Monolix is described in
Section 3.3.7.
4.8.1
autocorrelated residual errors
Assuming autocorrelated residual errors is extremely easy
with Monolix. Choose your error model as usual and just
select the autocorrelation option with the checkbox:
PKcorr1_project and PKcorr2_project are two PK examples where an exponential residual
error model with autocorrelated errors (εij ) is assumed:
log(yij ) = log(f (tij ; ψi )) + εij
105
Monolix 4.3.3
Complex PK models
• Equally spaced sampling times are used in PKcorr1_data: ti,j+1 − tij = 1. Then,
0
corr(εij , εij 0 ) = ρ|j −j|
• Irregular sampling times are used in PKcorr2_data. Then,
corr(εij , εij 0 ) = ρ|tij 0 −tij |
Data was simulated using ρ = 0.5 for both examples.
4.8.2
residual errors for bounded data
Example: Emax_errorband_project
We assume in this example that the data takes continuous values in (0, 100). Then, we consider
the following residual error model:
yij
f (tij ; ψi )
log
= log
+ εij
100 − yij
100 − f (tij ; ψi )
The error model band(0,100) is predefined in Monolix and can be selected:
4.9
Complex PK models
Examples
PK models: admin1_project, admin2_project, infusion_2cpt_project,
ss1_project, admin2_project, oral0_1cpt_MD_project, oral0_2cpt_SS_project,
bolus_1cptMM_project, phenobarbital_project
4.9.1
Complex administrations
Example 1: admin1_project
The data file admin1_data.txt contains real PK data. This example is a combination of oral
and IV bolus administrations. Then the model takes into account the bioavailability.
The Mlxtran model admin1_mlxt.txt is stored in the folder libraryMLXTRAN.
DESCRIPTION: Combination of oral and IV bolus administrations.
INPUT:
parameter = {F, ka, V, CL}
106
Monolix 4.3.3
Complex PK models
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; Version 1 using PK macros
PK:
compartment(amount=Ac)
absorption(adm=1, ka, p=F)
iv(adm=2)
elimination(k=CL/V)
Cc=Ac/V
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; Version 2 using PK macros and ODEs
;PK:
;compartment(cmt=1, amount=Ad)
;compartment(cmt=2, amount=Ac)
;iv(adm=1, cmt=1, p=F)
;iv(adm=2, cmt=2)
;EQUATION:
;k=CL/V
;ddt_Ad = -ka*Ad
;ddt_Ac = ka*Ad - k*Ac
;Cc=Ac/V
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
OUTPUT:
output = Cc
Example 2: admin2_project
The data file admin2_data.txt contains real PK data. This example is a combination of 3 oral
and 1 infusion administrations. Then the model takes into account the 3 bioavailabilities.
The Mlxtran model is admin2_mlxt.txt.
4.9.2
Steady-state
Example: ss1_project
The data file ss1_data.txt contains real PK data. This example is a combination of single dose
and steady-state.
Mlxtran models do not handle steady state administrations, and PK library models only
handles this kind of doses, when all the subjects have exactly one steady doses. That is why,
Monolix adds some doses artificially as an approximation of the steady state, converting the
doses to the multiple doses case, but ensuring that no doses are added before a previous dose,
event or observation of each subject. You can define the maximum number of doses that should
be added in the preferences file (see Appendix C).
Note: Steady-state doses are treated like if there were a new occasion with EVID= 4. That
means that it is possible to add inter-occasion variability and that it will not be possible to use
the simulation interface nor the hypothesis test on covariance model.
107
Monolix 4.3.3
Mixture models and model mixtures
4.10
Mixture models and model mixtures
Examples
mixtures:
PKmixture_project, bsmm_project, wsmm_project
Mixture models and mixture of models are described in Section A.8.
4.10.1
Mixture models
Click on the mixture button to create
latent covariates and define the number of
categories for each latent covariate.
Then consider these latent covariates
that you have created as a categorical covariate and define your covariate model as
usual.
See PKmixt_project as an illustrative example: PK data were simulated using a one compartment model and assuming two categories for the volume (β = 0.5). In this simulated example,
the column GROUP contains the labels (i.e. the groups), but the column GROUP is set to IGNORE.
Project PKgroup_project uses the same data file and the same model, but using the known
categorical covariate (setting GROUP to CAT). Then, a comparison of the results provided with
these two projects can be used to validate the proposed methodology for mixtures.
Similar exercises can easily be done with the examples provided for categorical covariates in
Section 4.4.
4.10.2
Model mixtures
Between subjects model mixtures (BSMM) and within subjects model mixture (WSMM) must
be defined in the Mlxtran file using the reserved key-words BSMM or WSMM (see the examples
below).
On the other hand, the statistical models (defined with the Graphical User Interface) are slightly
different:
• BSMM assumes no inter-individual variabilities for the proportions of each group (ı.e. the
probabilities to belong to the different groups)
108
Monolix 4.3.3
Tables
• WSMM assumes inter-individual variabilities for the proportions of each model.
DESCRIPTION: Between subject model mixture
bsmm_project is an example of BSMM.
Probabilities p and 1 − p are associated to
models f1 and f2 . Here, p is an unknown population parameter (i.e. with no inter-individual
variability).
The Mlxtran file bsmm_mlxt.txt uses the
reserved key-word BSMM.
INPUT:
parameter = {a, b, c, p}
EQUATION:
f1 = a
f2 = b*exp(-c*t)
f=bsmm(f1, p, f2, 1-p)
OUTPUT:
output = f
DESCRIPTION: Within subject model mixture
wsmm_project is an example of WSMM.
Proportions p and 1 − p are associated to
models f1 and f2 . Here, p is an individual
parameter logit-normally distributed with some
inter-individual variability (to be estimated).
The Mlxtran file wsmm_mlxt.txt uses the
reserved key-word WSMM.
4.11
INPUT:
parameter = {a, b, c, p}
EQUATION:
f1 = a
f2 = b*exp(-c*t)
f=wsmm(f1, p, f2, 1-p)
OUTPUT:
output = f
Tables
The
button can generate some tables (see Section 3.8.2)) containing several informations:
predictions, residuals,. . . .
It is possible to include several additional columns in those tables by appending a table keyword
in section OUTPUT: at the end of the Mlxtran script file as explained in Mlxtran models
documentation.
For each variable set in table, a column will be created with the values of those variables for
each estimator of the individual parameters.
For instance, if you want to include the volume and the clearance used to compute the predictions,
append the line
table={V,Cl}
to the section OUTPUT: of the Mlxtran model.
4.12
Using Monolix in Matlab command line or scripts
It is provided some Matlab commands in order to access to the functionalities of Monolix
from Matlab command line. It is useful when it is not desired or possible to use the software
interface. It allows also to write some Matlab scripts to, for instance, estimate population
parameters for several projects.
109
Monolix 4.3.3
Using Monolix in Matlab command line or scripts
Important: There are two important things to know when using Monolix in command line
• The command line functions should not be used at the same time that the main interface
(in particular methods that generate graphics). It is recommended also to close all the
figures obtained for one project before creating new ones.
• Users under floating licenses must be aware that a token is reserved from first use of
Monolix commands, and it must be freed manually. For that, you can close Matlab or
call
» clear classes;
As explained in Chapter 3, Monolix requires a project and for that we provide the class
MonolixProject.
You can create one from any Monolix project file
» aMonolixProject = MonolixProject(’Path/to/myProject.mlxtran’);
or you can load a new one if the object is already created
» aMonolixProject = MonolixProject(’Path/to/myProject1.mlxtran’);
» ...
» aMonolixProject.load(’Path/to/myProject2.mlxtran’);
Once the project created, the class MonolixProject proposes methods to:
• 1) define a scenario / workflow:
– » aMonolixProject.setSaem(): to include or not population parameters estimation
on the scenario. Computes also a first, rough, estimation of the conditional mean and
conditional variance of the individual parameters.
– » aMonolixProject.setFisher(): to define if Fisher information matrix estimation
(and so standard error of estimates) should be included in the scenario and which
algorithm (linearization or stochastic approximation) must be used.
– » aMonolixProject.setIndiv(): to include or not individual parameter estimators
and says which estimator to compute among conditional mode and conditional mean
(both can be estimated at the same time). In the second case, it estimates also the
conditional standard deviation and variance.
– » aMonolixProject.setLogLikelihood(): to include or not the log-likelihood estimation and specify the algorithms to use between linearization and importance sampling. Both can be estimated at the same time.
– » aMonolixProject.setGraphics(): to include or not the graphics and tables generation on the scenario. Allows also to say which graphic to create and/or save and
which tables should be created. You can also choose the graphic format to be used
for saved figures.
• 2) execute a scenario / workflow:
110
Monolix 4.3.3
Using Monolix in Matlab command line or scripts
– » aMonolixProject.run(): runs the project scenario as explained in Section 3.7.6.
• 3) execute individual tasks:
– » aMonolixProject.runSaem(): executes only the population parameters estimation
– » aMonolixProject.runFisher(): executes only the Fisher information matrix estimation
– » aMonolixProject.runIndiv(): executes only the individual parameters estimation.
– » aMonolixProject.runLogLikelihood(): executes only the log-likelihood estimation.
– » aMonolixProject.runGraphics(): produce graphics and results tables.
– » aMonolixProject.convergenceAssessment(): executes the convergence assessment tool of the algorithms as described in Section 3.7.7 with default arguments.
It can be specified the number of replicates, the parameters to simulate the initial
values, and the intervals for simulation. It returns the .mat file holding the results.
– » aMonolixProject.simulationEstimation(): executes a project scenario on the
original dataset and on several new datasets simulated using the previously estimated
parameters. It returns a structure with all estimations so the users can make their
own analysis. This tool can not be used with Event observations type, and do not
simulate censored data. It allows to specify the number of replicates, the sources of
variability (estimator uncertainty, individual parameter model, etc), among others. In
order to reproduce the same simulated datasets, you can specify also the seed and/or
random number generator stream (see RandStream help in matlab).
– » aMonolixProject.runSimulation(): allows to simulate a dataset. Several options
are possible in order to choose the variability sources, the design, the population
parameters, etc.
• 4) control the display:
– » aMonolixProject.toggleFigures();: sets the display configuration when individual task or complete scenario is ran.
Note: if you are working in a no-desktop environment, you should enter
» aMonolixProject.toggleFigures(’OFF’);
• 5) manage objects:
– » aMonolixProject.load(): see hereabove
– to save the project in a new directory / file enter:
» aMonolixProject.save(’Path/to/myNewProject.mlxtran’);
– to overwrite the original project file:
» aMonolixProject.save();
111
Monolix 4.3.3
Full script projects
• 6) miscellaneous:
– » folder=aMonolixProject.getResultsFolder();: returns the folder in which all
the result files are saved (see description in Chapter 3)
– » aMonolixProject.setResultsFolder(’Directory’,newfolder);: to define the
folder where the resul files will be saved.
For further details on the MonolixProject class, or to see the list of available methods, type
» doc MonolixProject
or,
» help MonolixProject
In order to have more information about a given method and its arguments, type
» help MonolixProject/method
Important: The old functions proposed to user to create its own scripts are deprecated and
they will be removed in a future version. In order to adapt their scripts to Monolix evolution,
the function ver should be used to know the Monolix version from Matlab command line:
» v=ver(’monolix’);
» v.Version
For older versions of Monolix, Matlab function ver will return empty ([]).
Is it also possible to know if Matlab version is compatible with the Monolix package that has
been installed. For instance
» if mlxIsMatlabCompatible();error(’Wrong Matlab version’);end
4.13
Full script projects
As said before, there are several formats to save your projects. Besides the binary .mat format,
Monolix proposes a human readable ASCII file with .mlxtran extension, and an XML-like format
with .xmlx extension.
Saving a project in the Mlxtran format will create two .xmlx files with the advanced algorithm
and graphics settings and the .mlxtran file with the description of the project (statistical model,
dataset definition, structural model, etc):
; this script is generated automatically
DESCRIPTION:
warfarin_PK_project.mlxtran
DATA:
path = "%MLXPROJECT%/",
file ="warfarin_data.txt",
headers = {ID,TIME,DOSE,Y,YTYPE,COV,COV,CAT},
columnDelimiter = "\t"
VARIABLES:
age [use=cov],
sex [use=cov, type=cat],
wt,
t_wt = log(wt/70) [use=cov]
112
Monolix 4.3.3
Full script projects
INDIVIDUAL:
Cl = {distribution=logNormal, covariate=t_wt, iiv=yes},
V = {distribution=logNormal, covariate=t_wt, iiv=yes},
ka = {distribution=logNormal, iiv=yes},
tlag = {distribution=logNormal, iiv=yes}
STRUCTURAL_MODEL:
file = "oral1_1cpt_TlagkaVCl",
path = "%MLXPATH%/libraries/PKLibrary",
output = {Cc}
OBSERVATIONS:
concentration = {type=continuous, prediction=Cc, error=combined1}
.
.
.
In the case that the two configuration files are missing, a warning will appear when loading the
project and Monolix will use the defaults settings. For description on how to write your own
Mlxtran projects, see ProjectMLXTRAN.pdf.
The XML-like format (.xmlx extension) is composed by only one file containing all the project
information
<monolix>
<project name="warfarin_PK_project.xml">
<covariateDefinitionList>
<covariateDefinition columnName="wt" name="t_wt" transformation="log(cov/70)" type="continuous"/>
<covariateDefinition columnName="age" type="continuous"/>
<covariateDefinition columnName="sex" type="categorical">
<groupList>
<group name="0" reference="true" values="0"/>
<group name="1" values="1"/>
</groupList>
</covariateDefinition>
</covariateDefinitionList>
<settings>
<tasks>
<scenario computeResults="reduced" estimateFisherInformationMatrix="true"
estimateIndividualParameters="true" estimateLogLikelihood="false" estimatePopulationParameters="true"/>
<individualParameterAlgorithms conditionalDistribution="false" conditionalMode="true"/>
<logLikelihoodAlgorithms importantSampling="true" linearization="true"/>
<fisherInformationMatrixAlgorithms linearization="true"/>
</tasks>
<options>
<estimateVariances value="true"/>
<showStandardErrorsInPercents value="true"/>
<resultFolder uri="%MLXPROJECT%/warfarin_PK_project" value="automatic"/>
</options>
.
.
.
</project>
</monolix>
113
Monolix 4.3.3
Preferences
4.14
Preferences
There are several preferences that can be customized by each user. They are stored in
‘/Path/To/.../lixoft/monolix/config/preference.xmlx’ and are loaded at the start of Monolix.
Some of them can be set from a dialog box. It can be opened from the ‘Tools’ menu:
It allows to personalize some user directories:
• log files
• structural model libraries
• module directory (i.e. the directory containing the structural built from Mlxtran script
files)
• working directory : generally the directory containing the projects
and also:
• to limit the number of threads used by
Mlxtran (structural model) - by default this
maximum is the number of logical processors.
• to enable timestamping: backup of the current
state of the project results folder saved in results directory as a zip file.
• to configure the saved graphics format (png, ps,
jpg, bmp, tiff). Notice the ’ps’ file allows to
create a single file for several graphics, unlike
the other formats which create one file for each
graphic.
• to tell Monolix to use the current folder as the
default folder for all the directory related dialog
boxes.
Several other options are available but they must be modified directly on the file. They are
divided in two categories: graphic and session related preferences. You will find more details
about the content of this file in Appendix C.
For fast reference we mention here some of the session related settings that can not be modified
with that dialog box.
• historic_size: size of the historic list for project files, and structural models.
• editor: text editor used to edit Mlxtran models. It could be set also with · · · button
in ModelList interface (see Section 3.3.2).
114
Monolix 4.3.3
Preferences
• lockModels: set to 1 to hide all the options related to structural model modification:
options Compile and Edit on context menu on the main interface, and buttons New ,
Modify , Edit , Compile on the model selection interface.
• modelFilter: select the default filter for the structural model: use m, mlxtran or none to
filter on .m files, Mlxtran files or to not filter at all.
Others settings allows to define installation preferences and are stored in the file system.xmlx
which is located in config on the Monolix installation folder (‘/Path/To/runtime/config’).
This file is shared by all the users and administration rights may be needed to modify it.
They include:
• userPath : select the default path of the ’monolixData’ directory. The path is set by
default to ’%USERPROFILE%’ under Windows or ’$HOME’ under Linux. If this setting is
changed, make sure to keep a user-specific path.
• compiler : under Linux OS, it is possible to choose the embedded compiler of Monolix
(this setting is located in the file ’system.xmlx’). Set the argument embed to true, if the
embedded compiler has been chosen.
• compiler.build-linux : under Linux OS, it is possible to configure the compiler options
by using compilation-options tag. It is also possible to force the compiler by using
force-compiler tag (e.g. use icpc, the INTEL compiler). These options have to be used
carefully and may lead some problems.
• display-license-activate : this setting, located in the file ’system.xmlx’ allows to
disable the popup windows ’Lixoft Activate’
Note: Both preference files are read when Monolix is open, so in order to Monolix to take
the changes into account, it must be reopened. If you use Monolix from Matlab command
line, then you should do
» clear classes
115
Monolix 4.3.3
Chapter 5
PerlMLX and the batch mode
5.1
Introduction
PerlMLX is a helper tool that can be used to run
• one or several projects
• an user defined list of project files
defined through Mlxtran or via XMLX project files.
PerlMLX can be executed on Windows and Linux platforms (Matlab and standalone version of Monolix are supported) and it can launch multiple runs simultaneously (which can
reduce drastically processing time).
All these features make PerlMLX a very efficient tool for mass processing.
PerlMLX is provided with a simple HMI but some users may prefer the command-line interface (users working on clusters will have to use this command-line interface since clusters are
not managed by the HMI).
Note: PerlMLX relies on Perl scripts (hence its name !) which supposes of course that Perl
has been installed on the platform.
This chapter is organized as follows:
• Section 5.2 lists the environment variables that shall be set for PerlMLX to run (nothing
mandatory in fact but the definition of environment variables can me the scripts easier to
write)
• Section 5.3 describes PerlMLX "HMI mode"
• Section 5.4 describes PerlMLX "standalone mode"
116
Environment variables
• Section 5.5 describes how to launch Monolix without PerlMLX (the so called "Batch
mode")
• Section 5.6 describes how to use PerlMLX on cluster installations.
5.2
Environment variables
When PerlMLX is used in command-line mode, it is recommended to setup environment variables (nothing mandatory but as will be seen later these variables will make the scripts easier to
write):
• ‘MONOLIX’ to: ‘/My/Path/To/Monolix.4.3.3-standalone-linux32’
• ’MONOLIXDATA’ to: ‘/MyPath/To/runtime/resources’
These environment variables can be set with the shell commands below:
• Linux:
– type the command lines:
gandalf#> export MONOLIX=/My/Path/To/Monolix.4.3.3-standalone-linux32
– or add the following lines in your ‘.bashrc’ config file
gandalf#> gedit /.bashrc
add the following line at the end of the file ‘.bashrc’:
export MONOLIX=/My/Path/To/Monolix.4.3.3-standalone-linux32
• Under Windows (XP, Vista or 7)
– type the command lines:
c:\set MONOLIX=c:\My\Path\To\Monolix.4.3.3-standalone-win32
– or use the graphical environment to set up the path and the variable MONOLIX to
c:\My\Path\To\Monolix.4.3.3-standalone-win32
Note: by default Monolix is installed beneath c:\Document And Settings\All Users\ApplicationData
which is a hidden directory (so please refer to your operating system’s documentation if
Monolix directory does not show in your explorer)
117
Monolix 4.3.3
HMI mode
5.3
HMI mode
HMI version of PerlMLX is an executable named mlxPerlScript.
The HMI is divided in eight sections:
• Inputs control: used to define either the project files or the directories (containing the
project files) on which Monolix shall be run.
– If Directory is selected the user can enter via the text edit (or with the help of the
Browse Directory button) the directory(ies) which shall be processed. All the poject
files contained in the selected directory(ies) and its sub-directories will be processed.
– If File is selected user can enter via the text edit (or with the help of the Browse
File button) the Mlxtran or XMLX projects that shall be processed.
Whatever is the input selection mode, only the directories / files appended to the list
(through button Append directory / file to list) will be processed. Press button
See directories / files list to control this list (items can be discarded from the list
via Delete element button).
• Output directory: directory where the results will be stored.
• Working directory: directory where all intermediate and temporary files are stored.
• MONOLIX directory: directory where Monolix is installed
Something like ‘/My/Path/To/Monolix/matlab’ for MATLAB version and ‘/My/Path/To/Monolix’
(where ‘Monolix.bat/.sh’ can be found) on stand-alone installations.
• Perl Script file: directory where the Perl script toolsRunner.pl can be found.
Note: Button Test PERL installation can be used to verify that perl command can be
accessed through the HMI. When this button is pressed a call to ‘perl -v’ (perl version)
is done. If this call is unsuccessfull the STD OUT / STD ERR will be painted in yellow (perl
version will be displayed in a white background otherwise). User can then use the Set
PERL directory button to select the directory where Perl is installed.
• Matlab control: combo Use MATLAB shall be set to NO on standalone versions and YE on
Matlab verions (path to Matlab installation shall then be entered)
Note: path to Matlab installation is something like ‘Path/To/MATLAB/R2012a’. What is
important is tha a subdirectory ‘bin’ where ‘matlab.exe’ can be found exists under this
path.
• Threads control: enter the number of threads that can be opened. On multiprocessor
machines this control can be used to force PerlMLX to use the maximum processing
power (or on the contrary limited resources !).
118
Monolix 4.3.3
HMI mode
• Launcher: see below.
Note: it is recommanded to try the perl installation before pressing this button (see Perl
Script file item hereabove).
Note: it is possible to save and restore configuration via File menu, actions Export / import
mlxPerlScript Cfg
Note: light green and light red are used to distinguish between valid and invalid directories
/ files names.
User shall press the Launch Simulation button (in the Launcher group box at the bottom
of the HMI) to start the simulation. This group box can be docked and will show in the text
edit:
• exact transcript of the launched Perl process
• standard output and error from the launched Perl process
119
Monolix 4.3.3
Standalone mode
5.4
Standalone mode
To launch PerlMLX in standalone mode, user shall use script ‘toolsRunner.pl’. Several
options are made available to control this script (these options are introduced in the following
sub section). It is also possible to control these options via a reusable configuration file (which
is introduced in the second subsection).
5.4.1
Options
Here are the different options available for script ‘toolsRunner.pl’:
argument
value
–tool
execute
–toolhelp
–output-directory
<directory>
–thread
<number of thread>
–input-directories
<dir1,..dirN>
–input-project-list
<project1, ...,projectN>
–input-project-file-list
<project file list>
–use-matlab
–matlab-path
<matlab path>
–monolix-path
<path of monolix>
–working-directory
<directory>
–config
<path of configuration file>
description
name of tools to execute (required parameter)
display help documentation
output directory path, where the
results are stored
number of simultaneous projects
to run
list of input directories containing project files
input list of projects separated by
comma
input file containing list of
project files
Matlab version of Monolix instead of standalone
Matlab path (if use-matlab is
set)
Monolix path
directory where all intermediate
and temporary files are stored
config file path
Some examples of correct instruction sets are givent in the following paragraphs:
Running Monolix on a demo file
gandalf#> perl $MONOLIX/perlScripts/toolsRunner.pl \
-–tool=execute \
-–input-project-list=$MONOLIXDATA/demos/categorical_covariate/PDsim1_project.mlxtran \
-–output-directory=$MONOLIXDATA/work/output \
-–monolix-path=$MONOLIX/bin \
-–working-directory=/home/gandalf/tmp
120
Monolix 4.3.3
Standalone mode
In this example a standalone version of Monolix is launched (with the parameter ‘–monolix-path’)
using the Mlxtran project ‘PDsim1_script.mlxtran’. The output directory has been set to
‘/MyPath/To/runtime/resources/work/output’
Running Monolix on the Demos directory
gandalf#> perl $MONOLIX/perlScripts/toolsRunner.pl \
-–tool=execute \
-–input-directories=$MONOLIXDATA/demos \
-–monolix-path=$MONOLIX/bin \
-–output-directory=$MONOLIXDATA/work/output \
-–working-directory=/home/gandalf/tmp
This illustrates an execution of Monolix on all XMLX and Mlxtran projects present in the
directory ‘$MONOLIXDATA/work/Demos’
Running Monolix on a project file list
First edit a file list using a simple text editor (gedit, emacs, vim, kwrite, . . . ) :
gandalf#> gedit myslist.lst then execute ‘toolsRunner.pl’ :
gandalf#> perl $MONOLIX/perlScripts/toolsRunner.pl \
-–tool=execute \
-–input-project-file-list=./mylist.lst \
-–output-directory=$MONOLIXDATA/work/output \
-–monolix-path=$MONOLIX/bin \
-–working-directory=/home/gandalf/tmp
121
Monolix 4.3.3
Standalone mode
5.4.2
Setting up the configuration file
Script ‘toolsRunner.pl’ can also be used with ’config’ option and a ‘.ini’ configuration file (the
file can be created using a simple text editor). Here is the information that this configuration
file shall contain:
subsection
parameters
[path]
Matlab
[monolix]
Monolix
standalone
[program-generic-options]
thread
workingDirectory
[program-execute-options]
command prefix
script-embed
useProjectDirectoryToSaveResult
description
Matlab path (required for a
Matlab version of Monolix )
Monolix path
standalone version?
number of threads: it is recommended that the number of
threads is smaller or equal to the
number of processor cores available on the computer
directory used by PerlMLX to
store intermediate results
add a command prefix to a
Monolix command, this parameter is useful in cluster mode (ex:
use of ‘qsub’ before the Monolix
command)
Monolix generates a script containing a command line; this parameter is used in the cluster
mode: the qsub command is run
on a script without any command line argument, with the
command line embedded into a
script
the default directory of results
is stored in same directory as
project directory
In the following paragaphs examples of correct configuration files are given:
• example using the Matlab version under Linux OS
[path]
; Matlab version of Monolix
; Matlab path
matlab=/opt/matlab/
; directory of Monolix
122
Monolix 4.3.3
Standalone mode
monolix=/opt/Monolix-4.3.3-matlab-linux32
[monolix]
; standalone version? No
standalone=false
[program-generic-options]
; execution on the nodes
thread=2
[program-execute-options]
; PerlMLX need a temporary directory to store intermediate files
workingDirectory=/tmp
• example using the standalone version under Linux OS
[path]
; Monolix directory
monolix=/opt/Monolix-4.3.3-standalone-linux32/bin
[monolix]
; use of the standalone version
standalone=true
[program-generic-options]
; execution on the nodes
thread=2
[program-execute-options]
; PerlMLX need a temporary directory to store intermediate files
workingDirectory=/tmp
• example using the Matlab version on a Linux cluster
[path]
; Matlab version of Monolix
; Matlab path
matlab=/opt/matlab/
; directory of Monolix
monolix=/opt/Monolix-4.3.3-standalone-linux32
[monolix]
; not the standalone version
standalone=false
[program-generic-options]
; on a cluster multi-threading is not necessary:
; the cluster uses a queue to dispatch program
; execution on the nodes
thread=1
[program-execute-options]
; PerlMLX need a temporary directory to store intermediate files
123
Monolix 4.3.3
Standalone mode
workingDirectory=/tmp
; Specific options to run Monolix on a cluster
; qsub is generally the program to submit a process on a cluster
; qsub is typically applied to a script, script-embed option
; allows to create a shell script containing the Monolix command
command-prefix=qsub -V -u gandalf
script-embed=true
Then, a user working on a cluster can run Monolix as usual:
gandalf#> perl /opt/Monolix-matlab/perlScripts/toolsRunner.pl \
-–tool=execute \
-–config=$MONOLIXDATA/work/myconfig.ini \
-–input-directories=$MONOLIXDATA/demos \
-–output-directory=$MONOLIXDATA/work/output
Running Monolix on a demo file
gandalf#> perl $MONOLIX/perlScripts/toolsRunner.pl \
-–tool=execute \
-–input-project-list=$MONOLIXDATA/demos/categorical_covariate/PDsim1_project.mlxtran \
-–output-directory=$MONOLIXDATA/work/output \
-–config=$MONOLIXDATA/work/myconfig.ini
Running Monolix on the Demos directory
gandalf#> perl $MONOLIX/perlScripts/toolsRunner.pl \
-–tool=execute \
-–input-directories=$MONOLIXDATA/demos \
-–output-directory=$MONOLIXDATA/work/output \
-–config=$MONOLIXDATA/work/myconfig.ini
Running Monolix on a project file list
gandalf#> perl $MONOLIX/perlScripts/toolsRunner.pl -–tool=execute \
-–input-project-file-list=./mylist.lst \
-–output-directory=$MONOLIXDATA/work/output \
-–config=$MONOLIXDATA/work/myconfig.ini
124
Monolix 4.3.3
Batch mode in depth
5.5
Batch mode in depth
5.5.1
Running Monolix without PerlMLX
It is possible to run Monolix using a simple command line:
• with the standalone version of Monolix
$MONOLIX/bin/Monolix.sh [–nowin] \
-p <project> \
-f [run|saem|fim|ll|graphics]
• with the Matlab version of Monolix (the command has to be launched from the matlab
directory of the installation of Monolix , i.e. <monolix install path>/matlab)
matlab -wait \
-nosplash \
-nodesktop \
-r "monolix(’-nowin’, \
’-p’,’<project>’, \
’-f’,’[run|saem|fim|ll|graphics]’, \
’-destroy’ \
),exit"
5.5.2
Monolix Program options
• -nowin : without opening a window, mandatory in no-desktop environments.
• -p <project> : project to run
• -f run|saem|fim|ll|graphics
– run: run a workflow
– saem: estimate population parameters
– fim: estimate the standard errors of the estimates and Fisher information matrix
– ll: estimate the log-likelihood
– graphics: generate the result graphics
5.5.3
Example
Run the standalone version of Monolix on the project PDsim1_project.mlxtran:
$MONOLIX/bin/Monolix.sh \
–nowin \
–p $MONOLIXDATA/demos/categorical_covariates/PDsim1_script.mlxtran -f run
125
Monolix 4.3.3
Batch mode in depth
Here Monolix is executed without displaying a window (option -nowin).
Example: shell script to run Monolix on all Mlxtran files on a directory:
1
2
3
4
5
6
7
8
if
[ −d $1 ] ; then
f o r mlxtran \_i i n ’ f i n d $1 −type f | g r e p mlxtran$ ’ ; do
echo "Run Monolix in $mlxtran_i " ;
$MONOLIX/ b i n / Monolix . sh −nowin −p $mlxtran_i −f run
end
else
echo "$1 is not a directory "
fi
126
Monolix 4.3.3
Monolix on cluster
5.6
5.6.1
Monolix on cluster
Cluster filesystem
To run Monolix on a cluster, each cluster node must have access to the Monolix directory
and to the user home directory.
Each node shares a common file system containing the user directories. The common filesystem
may also contain Matlab and Monolix . However, in the case of the standalone version of
Monolix , it is recommended to have Monolix installed on a local drive for each node, since
the standalone binary is large: if installed on the network, the startup time on a cluster may
take too long.
5.6.2
Task submission mechanism
Generally, a task is submitted to the cluster using a specific command, e.g. qsub in the case of
Torque, PBS or GridEngine ( former SGE ). This command runs a script, provided as parameter,
on a cluster node choosen by the cluster scheduler.
The Monolix batch tool allows to run this command through the configuration file. To enable
the cluster functionnality, the options command-prefix and script-embed must be set in the
configuration file, where command-prefix is the command used to submit a task (generally qsub)
and script-embed allows to encapsulate the low level Monolix command (see Section 5.5.1).
At this point, when the command toolsRunner.pl is executed, each instance of Monolix takes
place on a cluster node chosen by the cluster scheduler.
5.6.3
Example
Setting up a configuration file
The following configuration file enables a cluster mode (e.g. Torque, PBS, GridEngine). A
task is submitted to the cluster using the command ’qsub’ which runs a script on a cluster mode.
127
Monolix 4.3.3
Monolix on cluster
[path]
; use a Matlab version of Monolix
; Matlab path
matlab=/opt/matlab/
; Monolix directory
monolix=/opt/Monolix-4.3.3-standalone-linux32
[monolix]
;do not use standalone version
standalone=false
[program-generic-options]
; one thread: on a cluster multi-threading is not necessary:
; the cluster uses a queue to dispatch program
; execution on the nodes
thread=1
[program-execute-options]
; PerlMLX needs a temporary directory to store intermediate files
workingDirectory=/tmp
; Specifics options to run Monolix on a cluster
; qsub is generally the program to submit a process on a cluster
; Typically qsub uses a script as the process to run; the script-embed option
; allows to create a shell script containing the Monolix command
command-prefix=qsub -V -u gandalf
script-embed=true
Submit tasks on a cluster
Here each project stored in the directory $MONOLIXDATA/monolix433/work/Demos is run on
the cluster nodes. This directory has to be shared by all nodes (typically, under Linux OS, with
NFS), with exactly the same path.
gandalf#> perl $MONOLIX/perlScripts/toolsRunner.pl –tool=execute \
–input-directories=$MONOLIXDATA/work/Demos \
–output-directory=$MONOLIXDATA/work/output \
–config=$MONOLIXDATA/work/myconfig.ini
where MONOLIX and MONOLIXDATA are environment variables defined as explained in Section 5.2.
128
Monolix 4.3.3
Chapter 6
Validation suite
6.1
Introduction
The validation suite is the highest level of the tests, and is provided on request. It consists in
a set of project runs, whose results are compared with references results. A customer can also
add his own projects in the suite. A more detailed documentation on the testing strategy and
the development processes is also available on request.
The process of the validation suite consists in taking a set of projects with predefined scenarii
and to launch them with Monolix . The result files are then compared with the reference files.
Due to the Matlab kernel, slight numerical differences can appear between two Matlab versions
for a same project. This is why the validation suite is launched for each operating system and
each Matlab version with different references. It must be executed in batch mode, i.e. via a
command line, without a graphical interface.
6.2
Prerequisites
The informations below are required to run the validation suite in batch mode:
• directory path of Monolix,
• directory path of Matlab (does not apply to standalone Monolix)
• directory path of references files
A Perl installation is also required to run the validation suite.
6.3
Combinations
As described above, several sets of references results are required to cover platform variabilities.
The combinations are listed as follows.
129
Extensive coverage through the demo projects
Monolix version
Install.exe
R2010a-Install.exe
R2010b-Install.exe
R2010b-Install.exe
R2010b-Install.exe
R2010b-Install.exe
standalone2008b-linux32.sh
matlab2010a-linux32.sh
matlab2010bSP1-linux32.sh
matlab2010bSP1-linux32.sh
matlab2010bSP1-linux32.sh
matlab2010bSP1-linux32.sh
standalone2008b-linux64.sh
matlab2010a-linux64.sh
matlab2010bSP1-linux64.sh
matlab2010bSP1-linux64.sh
matlab2010bSP1-linux64.sh
matlab2010bSP1-linux64.sh
6.4
Matlab version
2008b
2010a
2010bSP1
2011a
2011b
2012a
2008b
2010a
2010bSP1
2011a
2011b
2012a
2008b
2010a
2010bSP1
2011a
2011b
2012a
Operating system
Windows 32 bits
Windows 32 bits
Windows 32 bits
Windows 32 bits
Windows 32 bits
Windows 32 bits
Linux 32 bits
Linux 32 bits
Linux 32 bits
Linux 32 bits
Linux 32 bits
Linux 32 bits
Linux 64 bits
Linux 64 bits
Linux 64 bits
Linux 64 bits
Linux 64 bits
Linux 64 bits
Extensive coverage through the demo projects
The projects from the validation suite are designed to provide maximum coverage of the set of
functionalities of MONOLIX. The two types of structural models, Matlab and MLXTRAN, are
included in these projects. Currently, the suite includes 17 projects:
• Emax_errorband_project : transformed error model,
• iov3_project, ss2_project : inter occasion variability (IOV) with several levels,
• theophylline2_project, warfarin_PKPD1_project, warfarin_PKPD4_project,
warfarin_PK_project : methodologic cases with classical database,
• categorical1_project, count1_project : discrete observed variables,
• pkrtteExpo_project, rtteWeibullCount_project : repeated time to event,
• PKmixt_project : model of mixtures and mixture models,
• PDsim1_project, phenobarbital2_project : categorical covariates,
• bolus_1cptMM_project, demo_project, sequential_oral0_oral1_project : advanced and complex administrations.
130
Monolix 4.3.3
Execution
6.5
Execution
Program parameters
argument
–help
value
–output-directory
<directory>
–thread
<number of thread>
–reference-directory
<directory>
–use-matlab
true ou false
–matlab-path
<matlab path>
–monolix-path
–keep-output
<path of monolix>
true ou false
description
display help documentation
output directory path, where the
results are stored
number of simultaneous projects
to run
reference directory containing
project files
Matlab version of Monolix instead of standalone
Matlab path (if use-matlab is
set)
Monolix path
saves output directory
Examples
Here we set the environment variable
• ‘MONOLIXSTD’ to ‘/opt/Monolix.4.3.3-standalone-linux32’,
• ‘MONOLIX’ to ‘/opt/Monolix.4.3.3-matlab2010bSP1-linux32’,
• ‘MATLAB’ to ‘/opt/MATLAB/R2010b’ and
• ‘VALIDATIONSUITE’ to ‘/home/gandalf/validationSuite’
To set environment variables, see Section 5.2.
Running the validation suite with standalone version
Go to the validation suite directory (here /home/gandalf/validationSuite/scripts).
Then,
gandalf#> perl validationSuite.pl \
--reference-directory=$VALIDATIONSUITE/reference/lin32/2008b \
--monolix-path=$MONOLIXSTD/bin \
--output-directory=/home/gandalf/output
This illustrates an execution of Monolix on all XMLX and Mlxtran projects present in the
directory ‘$VALIDATIONSUITE/reference/lin32/2008b’. If the validation is successful, the user
should get
131
Monolix 4.3.3
Execution
Running the validation suite with matlab version
Go to the validation suite directory (here /home/gandalf/validationSuite/scripts).
Then,
gandalf#> perl validationSuite.pl --use-matlab=true \
--reference-directory=$VALIDATIONSUITE/reference/lin32/2010b \
--monolix-path=$MONOLIX/matlab \
--output-directory=/home/gandalf/output
--matlab-path=$MATLAB
132
Monolix 4.3.3
Execution
Running the validation suite with matlab version and saving output directory
In the validation fails, it can be useful to store the output directory using the option ’keep-output’:
gandalf#> perl validationSuite.pl --use-matlab=true --keep-output=true \
--reference-directory=$VALIDATIONSUITE/reference/lin32/2010b \
--monolix-path=$MONOLIX/matlab \
--output-directory=/home/gandalf/output
--matlab-path=$MATLAB
The display shows the fields in the results which are not equal to reference results, and indicates
the order of errors.
It exists two kinds of error:
• absolute error
133
Monolix 4.3.3
Execution
• relative error
During the comparison, the absolute error is used. In the case where this error is too large
(> 10−3 ), the relative error is used.
134
Monolix 4.3.3
Chapter 7
Software plugins
7.1
Introduction
Monolix can be extended with the following plug-ins:
• DatXPlore is a graphical and interactive software for the exploration and visualization
of data.
• MlxPlore is a graphical and interactive software for the exploration and visualization
of complex pharmacometric models. It also includes the ability to study the statistical
variability of the models, and to model and study complex administrations designs.
Both DatXPlore and MlxPlore are available as standalone software, however they make a
powerful combination with Monolix , sharing data and models.
7.2
DatXPlore
DatXPlore can be launched from the
Monolix graphical user interface via the entry
Tools → Data Explorer
DatXPlore opens an interface to choose and set the type of the dataset columns
135
DatXPlore
The DatXPlore graphical user interface then allows to view and manipulate data. Please refer
to the DatXPlore documentation to learn about its features.
136
Monolix 4.3.3
MlxPlore
7.3
MlxPlore
MlxPlore (version 1.1 and higher) can be
launched from the Monolix graphical user
interface via the entry Tools → Export to
MlxPlore
The model export requires to define a design:
• set the time grid (by default the grid is set by using the values of the data set)
• select the subjects which will be used to set the administration design
MlxPlore is then executed. Please refer to the MlxPlore documentation to learn about its
features.
137
Monolix 4.3.3
MlxPlore
138
Monolix 4.3.3
Appendix A
The statistical models
A.1
The nonlinear mixed effects model
Detailed and complete presentations of the nonlinear mixed effects model can be found in [5, 6,
21]. See also the many references therein.
We consider the following general nonlinear mixed effects model for continuous outputs:
yij = f (xij , ψi ) + g(xij , ψi , ξ)εij , 1 ≤ i ≤ N , 1 ≤ j ≤ ni
(A.1)
Here,
• yij ∈ R is the jth observation of subject i,
• N is the number of subjects,
• ni is the number of observations of subject i,
• the regression variables, or design variables, (xij ) are assumed to be known, xij ∈ Rnx ,
• for subject i, the vector ψi = (ψi,` ; 1 ≤ ` ≤ nψ ) ∈ Rnψ is a vector of nψ individual
parameters:
ψi = H(µ, ci , ηi )
(A.2)
where
– ci = (cim ; 1 ≤ m ≤ M ) is a known vector of M covariates,
– µ is an unknown vector of fixed effects of size nµ ,
– ηi is an unknown vector of normally distributed random effects of size nη :
ηi ∼i.i.d. N (0, Ω)
• the residual errors (εij ) are random variables with mean zero and variance 1,
• the residual error model is defined by the function g and some parameters ξ.
139
Individual parameters model
Here, the parameters of the model are θ = (µ, Ω, ξ). We will denote `(y; θ) the likelihood of the
observations y = (yij ; 1 ≤ i ≤ n , 1 ≤ j ≤ ni ) and p(y, ψ; θ) the likelihood of the complete data
(y, ψ) = (yij , ψi ; 1 ≤ i ≤ n , 1 ≤ j ≤ ni ). Thus,
Z
`(y; θ) = p(y, ψ; θ) dψ.
Let us see now the statistical model used in Monolix 4.3.3 more in details.
A.2
The statistical model for the individual parameters
In Monolix 4.3.3 , we assume that ψi is a transformation of a Gaussian random vector ϕi :
ψi = h(ϕi )
(A.3)
where, by rearranging the covariates (cim ) into a matrix Ci , ϕi can be written as
ϕi = Ci µ + ηi
A.2.1
(A.4)
Examples of transformations
Here, different transformations (h` ) can be used for the different components of ψi = (ψi,` ) where
ψi,` = h` (ϕi,` ) for ` = 1, 2, . . . , `. Let us denote by Φ(u) the cumulative distribution function of
a Gaussian distributed random variable.
• ψi,` has a log-normal distribution if h` (u) = eu ,
• assuming that ψi,` takes its values in (0, 1), we can use a logit transformation h` (u) =
1/(1 + e−u ), or a probit transformation h` (u) = Φ(u).
• assuming that ψi,` takes its values in (A, B), we can define h` (u) = A + (B − A)/(1 + e−u ),
or h` (u) = A + (B − A)Φ(u).
In the following, we will use either the parameters ψi or the Gaussian transformed parameters
ϕi = h−1 (ψi ).
The model can address continuous and/or categorical covariates.
A.2.2
Example of continuous covariate model
Consider a PK model that depends on volume and clearance and consider the following covariate
model for these two parameters:
Ai βCL,A ηi,1
Wi βCL,W
e
Wpop
Apop
Wi βV,W ηi,2
= Vpop
e
Wpop
CLi = CLpop
Vi
140
Monolix 4.3.3
Individual parameters model
Where Wi and Ai are the weight and the age of subjet i and where Wpop and Apop are some
“typical” values of these two covariates in the population. Here, ψi will denote the PK parameters
(clearance and volume) of subject i and ϕi its log-clearance and log-volume. Let
Wi
Ai
?
?
Wi = log
; Ai = log
Wpop
Apop
Then,
ϕi =
log(CLi )
log(Vi )

=
1 0 Wi? A?i
0
0 1 0
0 Wi?





log(CLpop )
log(Vpop )
βCL,W
βCL,A
βV,W

 
 + ηi,1

ηi,2

= Ci µ + ηi
A.2.3
Example of categorical covariate model
Assume that some categorical covariate Gi takes the values 1, 2, . . . , K. Assume that if patient
i belongs to group k, i.e. Gi = k, then
log(CLi ) = log(CLpop,k ) + ηi
where CLpop,k is the population clearance in group k.
Let k ? be the reference group. Then, for any group k, we will decompose the population clearance
CLpop,k as
log(CLpop,k ) = log(CLpop,k? ) + βk
where βk? = 0.
The variance of the random effects can also depend on this categorical covariate:
ηi ∼ N (0, Ωk ) if Gi = k
Remark: It is assumed in Monolix 4.3.3 that the correlation matrix of the random effect is
the same for all the groups. In other words, only the variances of the random effects can differ
from one group to another.
Monolix
Choice of the transformation is described in Section 3.3.5.
Selection of the covariate model is described in Section 3.3.3.
Examples with categorical covariates are given in Section 4.4.
141
Monolix 4.3.3
The residual error model
A.3
The residual error model
The within-group errors (εij ) are supposed to be Gaussian random variables with mean zero and
variance 1. Furthermore, we suppose that the εij and the ηi are mutually independent.
Different error models can be used in Monolix 4.3.3 :
• the constant error model assumes that g = a and ξ = a,
• the proportional error model assumes that g = b f and ξ = b,
• a combined error model assumes that g = a + b f and ξ = (a, b),
p
• an alternative combined error model assumes that g = a2 + b2 f 2 and ξ = (a, b),
• a combined error model with power assumes that g = a + b f c and ξ = (a, b, c),
• ...
Furthermore, all these error models can be applied to some transformation of the data:
t(yij ) = t(f (xij , ψi )) + g(xij , ψi , ξ)εij
(A.5)
For example:
• the exponential error model assumes that y > 0:
t(y) = log(y)
y = f egε
• the logit error model assumes that 0 < y < 1:
t(y) = log(y/(1 − y))
f
y =
f + (1 − f )e−gε
• the logit error model can be extended if we assume that A < y < B:
t(y) = log((y − A)/(B − y))
f −A
y = A + (B − A)
f − A + (B − f )e−gε
It is possible with Monolix to assume that the residual errors (εij ) are correlated:
corr(εi,j , εi,j+1 ) = ρ(xi,j+1 −xi,j )
(A.6)
Here, we assume that 0 ≤ ρ < 1 and that for any i, (xi,j , 1 ≤ j ≤ ni ) is an increasing sequence
of regression scalar variables.
142
Monolix 4.3.3
Multi-responses model
Monolix
Selection of the residual error model is described Section 3.3.7.
Several examples of residual error models are provided with the demos:
• combined error model:
warfarin/warfarin_PK_project
• exponential error model:
PK/Bolus1cptMM_project
• extended logit error model:
error model/Imax_errorband_project
• autocorrelated residual errors:
error model/infusion_correrror_project
.
A.4
Multi-responses model
The basic model can be extended to multi-responses:
(1)
yij
(L)
yij
(1)
(1)
(1)
= f1 (xij , ψi ) + g1 (xij , ψi ; ξ1 )εij
..
..
.
.
(L)
(L)
, 1 ≤ i ≤ N , 1 ≤ j ≤ ni1
(L)
= fL (xij , ψi ) + gL (xij , ψi ; ξL )εij
, 1 ≤ i ≤ N , 1 ≤ j ≤ niL
(2)
This is useful, for example, for PKPD models in which the input of the PD model xij is the
(1)
concentration, that is the output of the PK model f1 (xij , ψi ).
Monolix
How to handle models with multiple outputs is described in Section 4.2.
Several examples are provided using the warfarin data:
warfarin_PKPD1_project, warfarin_PKPD2_project, warfarin_PKPD3_project,
warfarin_PKPD4_project.
A.5
A.5.1
Model with censored data
BLQ data
In some context, because of assay limitation, when data yij are inferior to a limit of quantification
(LOQ), we do not observe yij but only the censored value LOQ. These data are usually named
BLQ (Below the Limit of Quantification) data or left-censored data.
Let denote Iobs = {(i, j)|yij ≥ LOQ} and Icens = {(i, j)|yij ≤ LOQ} the index sets of the
cens = y denote the
uncensored and censored observations respectively. For (i, j) ∈ Icens , let yij
ij
cens
unknown value of the censored observation j of subject i. Let denote yi
the vector of censored
observations of subject i. Finally, we observe
yij
if (i, j) ∈ Iobs ,
obs
yij =
LOQ if (i, j) ∈ Icens .
143
Monolix 4.3.3
Inter-occasion variability
yiobs
obs , . . . , y obs )
(yi1
ini
We denote
=
total observations dataset.
A.5.2
obs ) the
as the observations of subject i and y obs = (y1obs , . . . , yN
Interval censored data
It is possible now also to model interval censored data, i.e data where it is only known that yij is
cens ∈ [LOD , LOQ ).
above a limit of detection LODij but below the limit of quantification yij
ij
ij
The intervals could be (−∞, LOQij ) (left censored data, as above) and [LOQij , +∞) (right
censored data).
Monolix
How Monolix handles BLQ data is described in Section 4.5.
A.6
Modeling the inter-occasion variability
We will denote yikj the jth observation for subject i during occasion k:
yikj = f (ψik , tikj ) + g(ψik , tikj , ξ)εikj
(A.7)
Here, ψik = h(ϕik ) is the individual parameter of subject i at occasion k:
ϕik = Cik µ + ηi + κik
(A.8)
- Cik is the matrix of covariates of subject i at occasion k,
- ηi random effect of subject i (inter-subject variability): ηi ∼ N (0, Ω),
- κik random effect of subject i at occasion k (inter-occasion variability): κik ∼ N (0, Γ),
- ηi and κik are assumed to be independent,
- Ω inter-subject variability covariance matrix,
- Γ inter-occasion variability covariance matrix.
A.7
Discrete data models
The basic model proposed in (A.1) is a regression model used for fitting continuous data that
can be extended for categorical data or count data models. Assume that (yij ) takes its values
in {0, 1, 2, . . .}. We define the conditional likelihood of the observations using a mixed effects
model:
P(yij = k|ψi ) = f (k, xij , ψi ) , 1 ≤ i ≤ N , 1 ≤ j ≤ ni
(A.9)
In other words, for any i, the probability that yij takes the value k depends on some (unknown)
individual parameter ψi and possibly on some (known) design variable xij .
A mixed hidden Markov models (mixed HMM, or MHMM) assumes that there exists some non
observed sequences (zij ) (the states) that take their values in 1, 2, . . . L such that, for any i,
144
Monolix 4.3.3
Mixture models and model mixtures
• (zij , j ≥ 1) is a Markov Chain,
• conditionally to the sequence of states (zij ), the (yij ) are independent random variables
• the transition probabilities P(zi,j+1 = v|zij = u) and the emission probabilities (i.e. conditional probabilities) P(yij = k|zij = u) depend on some individual parameters ψi .
Monolix
How to model categorical data, count data and HMM is described respectively in
Sections Section 4.7.1, Section 4.7.2 and Section 4.7.4.
A.8
Mixture models and model mixtures
A.8.1
Mixture models
In Monolix, a mixture model assume that there exist some “latent” categorical covariate G
that takes K values. Then, the mixture model reduces to the categorical covariate model described Section A.2 but here, the categorical covariates are unknown: they are treated as random
variables and the probabilities
πk = P(Gi = k)
are part of the statistical model and should be estimated as well.
A.8.2
Model mixtures
Let f1 , f2 , . . . fK be K different structural models,
• Between Subject Model Mixture (BSMM)
We assume that some categorical covariate G takes K values and that
yij = fk (xij , ψi ) + εij ,
if Gi = k
In a BSMM model, the “latent” categorical covariates are unknown: they are treated as
random variables and the probabilities
πk = P(Gi = k)
are part of the statistical model and should be estimated as well.
• Within Subject Model Mixture (WSMM)
For any patient i, let pi,1 , pi,2 , . . . , pi,K be K proportions such that
yij
= fi (xij , ψi ) + εij
fi = pi,1 f1 + pi,2 f2 + . . . + pi,K fK
In a WSMM model, the proportions (pi,k ) are additional individual parameters that should
be modeled as well (under the constraint that the sum is 1).
145
Monolix 4.3.3
Prior models
Monolix
How to use mixture models is described in Section Section 4.10.1.
Examples of BSMM and WSMM with Monolix are presented in Section 4.10.2.
A.9
Prior models on fixed effects parameters
It is possible to define prior distribution models on the fixed effects. The allowed distributions:
• log-normal
• logit-normal
• probit-normal
• user-defined: transformation of a gaussian distribution:
h−1 (µ) ∼ N (µ0 , σµ2 )
where h is any increasing function defined for all real numbers.
Monolix
How to use priors on fixed effects is described in Section Section 4.3.
146
Monolix 4.3.3
Appendix B
The data-set
B.1
General description
The data-set structure contains for each subject measurements, dose regimen, covariates etc ...
i.e. all the information collected during the trial.
This information is organized by line (i.e. each line contains a piece of information) and each
column shall be associated to a column-type (there are fifteen different column-types which
will be described in this annex) for the software to read the data-set. It is very similar and
compatible with the structure used by the Nonmem software.
ID
1
1
1
1
...
AMT
4.02
.
.
.
...
TIME
0
0.25
0.57
1.12
...
CONC
.
2.84
6.57
10.5
...
WEIGHT
79.6
79.6
79.6
79.6
...
SEX
M
M
M
M
...
One of the first thing that the software does is to define the line type. Indeed, a line can be:
- a dose-line: a line that contains information about the dose’s regimen
- a response-line: a line that contains a measure
- a regression-line: a line that contains regression value(s) (since it is possible to have
several regression variables)
- a covariate-line: a line that contains covariate values(s) (since it is possible to have
several covariates)
- a comment-line: any line containing character ‘#’
- a title-line: it is the first line of the data-set which can be used to define column-names
(see following paragraph)
147
General description
Combinations are possible and a line can be both a dose-line and a regression-line (in other
words it is possible to define in a same line a dose regimen and the regression values). But
a line cannot be both a dose-line and a response-line. In other words two lines will be
necessary to define a dose-regimen and a measure at the same time-stamp.
The title-line is the first line of the data-set. It is free and can be used to specify column-names.
It is important to understand the difference between column-names and a column-types: as already stated the column-names are totally free but the column-types shall belong to a list of
pre-defined keywords. They are used to identify the column’s role.
For instance, fourth column of the sample data-set contains measurement information and will
then have column-type Y. A name (CONC) has been entered to indicate that the measurement
corresponds to a concentration.
It is possible to group the column-types based on their functionality:
- subject identification headers: column-types ID and OCC are used to identify subjects.
- time headers: column-types TIME and DATE (or DAT1, DAT2, DAT3) are used to time stamp
data.
- dose headers: column-types AMT (alias: DOSE), ADM, RATE, TINF, SS and II (alias: TAU)
are used to define doses (respectively dose amount, dose administration, dose rate, dose
infusion time, dose steady-state and inter-dose interval).
Note: ADM is in fact a super column-type which groups three different column-types:
ADM_TYPE, ADM_TARGET, ADM_CMT. They are grouped because all of them are relative to
administration type.
- response headers: column-types Y (alias: DV, CONC) , YTYPE, CENS, LIMIT are used to
define responses (respectively response value, response type, censored response flag and
response limit).
- covariate headers: column-types COV and CAT are used to define continuous and categorial covariates.
- regression headers: column-type X (alias: REG, XX) is used to define regression variables.
- control and event headers: column-types MDV and EVID can be used
- either to control data by tagging lines as dose-lines, response-lines or regression-lines
(i.e. line containing information to define regression variables)
- or to mark unusual events.
Note: for several column-types, alias have been defined because they have been used in the
present document as synonyms of the headers’ types. For instance DV or CONC are sometimes
used instead of Y.
After this introduction it is time for a more in-depth description of column-types.
148
Monolix 4.3.3
In-depth description of column-types
B.2
B.2.1
In-depth description of column-types
Description of column-types used to identify subject-occasions
ID: subject identifier
A data-set shall contain one column with the column-type ID (an exception is thrown if there
is no column with column-type ID or several columns with column-type ID).
The column is used to identify the different subjects.
The content of the column is totally free: numbers / strings . . .
Note: string ‘.’ will not be interpreted as a repetition of the previous line. As a consequence
the data-set B.1 generates two subject-occasions:
- first subject-occasions is ‘John’
- second subject-occasions is ‘.’
- Note: there is no occasion defined.
John
...
John
John
.
...
...
...
...
...
...
...
Table B.1: A data-set that defines two subject-occasions: subject ‘John’ and subject ‘.’
149
Monolix 4.3.3
In-depth description of column-types
OCC: occasion identifiers
It is possible to have in a data-set one or several columns with the column-type OCC.
The content of the column is totally free: numbers / strings . . .
Note: string ‘.’ will not be interpreted as a repetition of the previous line. As a consequence
the data-set B.2 generates three subject-occasions:
- subject-occasion #1: ‘John’ occasion ‘Occ1 ’
- subject-occasion #2: ‘John’ occasion ‘Occ2 ’
- subject-occasion #3: ‘John’ occasion ‘.’
ID
OCC
Occ1
Occ2
.
John
John
John
...
...
...
...
Table B.2: A data-set that defines three subject-occasions
IMPORTANT NOTE: Occasions are ordered lexicographically. For instance the data-set
B.3 defines subject ‘John’ with four occasions:
- first occasion is ‘1’
- second occasion is ‘10’
- third occasion is ‘11’
- fourth occasion is ‘2’
- fifth occasion is ‘3’
ID
OCC
John
John
John
John
John
1
2
3
10
11
...
...
...
...
...
...
Table B.3: Ordering of occasions within a subject
150
Monolix 4.3.3
In-depth description of column-types
B.2.2
Description of column-types used to time-stamp data
TIME: data time stamp
A data-set shall not contain more than one column with the column-type TIME (an exception
will be thrown otherwise).
Time can be defined as :
- a double: xx.yy
- using hours, minutes format with optional AM/PM tag: hh:mm [AM/PM]
- using hours, minutes seconds format with optional AM/PM tag: hh:mm:ss [AM/PM]
Note: String ‘.’ will not be interpreted as a repetition of the previous line. It will throw an
exception as any non-compliance with formats listed here-above.
Note: When there is no column-type TIME, the column-type DATE is used to time-stamp data
(see next section).
If there is neither TIME nor DATE column-type, first regression-column (i.e. first column with
column-type X) will be used to time-stamp data.
If there is neither TIME, nor DATE/REGRESSION column-type, an exception is thrown since it is
then impossible to time-stamp data.
151
Monolix 4.3.3
In-depth description of column-types
DATE/DAT1/DAT2/DAT3: date information
A data-set shall not contain more than one column-type DATE / DAT1-3 (an exception will be
thrown otherwise).
DATE can be defined as:
- any double value
- using month, day format: mm-dd
- using month, day, year format (two or four digits): mm-dd-yy / mm-dd-yyyy
DAT1 can be defined as:
- using day, month format: dd-mm
- using day, month, year format (two or four digits): dd-mm-yy / dd-mm-yyyy
DAT2 can be defined as:
- using month, day format: mm-dd
- using month, day, year format (two or four digits): mm-dd-yy / mm-dd-yyyy
DAT3 can be defined as:
- using day, month format: dd-mm
- using year, day, month format (two or four digits): yy-dd-mm / yyyy-dd-mm
Note: day month year separator shall be either string ‘/’ or string ‘-’. It is possible to mix
separators between lines but the use of another separator will raise an exception.
Note: year, day month shall be integers (an exception is thrown if it is impossible to convert to
int string between two separators).
Note: string ‘.’ will not be interpreted as a repetition of the previous line but will throw an
exception as any non-compliance with formats listed here-above.
Note: when year is coded with two digits then it is interpreted as 20xx. For instance, using
format DAT2, 12/07/41 is interpreted as december the 7th 2041.
Note: when there is no year information PC clock is used.
152
Monolix 4.3.3
In-depth description of column-types
Note: It is possible to mix dates with and without year information across subjects.
Within a subject if year information is present on one line it shall be present for all lines regarding the subject (otherwise an exception will be thrown).
ID
John
John
John
OCC
Occ1
Occ1
Occ2
DATE
7/6
1/12
1/1/1986
...
...
...
...
Mike
Mike
Melinda
Melinda
Occ1
Occ1
Occ1
Occ1
07/6
1/1
12/12/2004
1-12-2002
...
...
...
...
Melinda
Melinda
Occ2
Occ2
12/2/2003
12/12/2003
...
...
Comments
Exception thrown: year was not
specified in preceding lines
No year specification for Mike
Year information for Melinda
Delimiters can be mixed within a
subject
Table B.4: Using column-type DATE to define a date
153
Monolix 4.3.3
In-depth description of column-types
B.2.3
Description of column-types used to define the dose regimen
AMT:dose amount
A data-set shall not contain more than one column-type AMT (an exception will be thrown
otherwise). The content of colum AMT will be called the dose-column.
Column AMT shall either contain a double value or string ‘.’.
When a dose-column contains a double value dAmount with dAmount 6= 0 then it will be considered as a dose-line (i.e. a line containing dose information). If dAmount = 0 then it will be
interpreted as a dose-line if the response-column (i.e. the content of column with column-type
Y, see section B.2.6) contains either 0 or string ‘.’.
Note: when a line contains both dose and response information (see section B.2.6) dose information is not taken into acount. For instance if the line content is
TIME
12.1
ID
Tom
AMT
1.1
Y
12.6
then response Y is set to 12.6 at time 12.1 but no dose is added ! Of course it is possible to
specify a response and a dose at same time but lines shall be duplicated. With:
TIME
12.1
12.1
ID
Tom
Tom
AMT
.
1.1
Y
12.6
.
a response Y is set to 12.6 at time 12.1 and a dose amount 1.1 is also set at time 12.1.
154
Monolix 4.3.3
In-depth description of column-types
ADM_TYPE: dose administration type
A data-set shall not contain more than one column with column-type ADM_TYPE (an exception
will be thrown otherwise).
An exception will also be thrown if a data-set contains a column with column-type ADM_TYPE
and a column with column-type ADM_CMT or ADM_TARGET.
For dose-lines, this column shall contain only strings that can be converted to int (an exception
will be thrown otherwise).
They are used to associate a compartment to the dose.
ADM_CMT: dose compartment
A data-set shall not contain more than one column with column-type ADM_CMT (an exception
will be thrown otherwise). An exception will also be thrown if the data-set contains a column
with column-type ADM_CMT and a column with column-type ADM_TYPE or ADM_TARGET.
For dose-lines, this column behaves exactly like column ADM_TYPE. For reponse-lines, this
column behaves exactly as YTYPE.
ADM_TARGET: dose target
A data-set shall not contain more than one column with column-type ADM_TARGET (an exception will be thrown otherwise). An exception will also be thrown if the data-set contains a
column with column-type ADM_TARGET and a column with column-type ADM_TYPE or ADM_CMT.
This column can contain any string to specify the administration’s type.
Note: string ‘.’ will not be interpreted as repetition of previous column but as a type of administration.
RATE, TINF: rate and infusion time
A data-set shall not contain more than one column with column-type RATE or TINF (an exception will be thrown otherwise).
The column’s content is meaningful only for dose-lines and format shall be for such lines:
- ‘.’: standard dose, without any infusion rate or time.
- any double value. 0 is interpreted as ‘.’. A negative value denotes an oral administration.
155
Monolix 4.3.3
In-depth description of column-types
An exception is thrown in case of non-compliance.
156
Monolix 4.3.3
In-depth description of column-types
SS, II: steady-state and inter-dose interval
Steady-state is used to specify that any transitory effect is over and that the system reponse
is now a periodic function of doses.
To realize this, a fixed (5 actually) number of doses is added (the period between doses is set
to interdose-interval) before the dose entered with the SS flag set to true. Let’s take an
example:
ID
Tom
TIME
-25
AMT
5
SS
0
II
0
EVID
4
Y
.
Tom
Tom
Tom
Tom
Tom
-20
-15
-10
-5
0
5
5
5
5
5
0
0
0
0
1
0
0
0
0
2
1
1
1
1
1
.
.
.
.
.
COMMENT
This dose is automatically added.
Note that first dose has wash-out (EVID = 4)
This dose is automatically added.
This dose is automatically added.
This dose is automatically added.
This dose is automatically added.
This line implies that the system shall have
reached its steady-state at time 0.
This is why 5 doses are added (at times -25,
-20, ... , -5) before this dose
The first added dose will have wash-out, thus for clarity an EVID colum has been included in
the previous example. But of course it is possible to specify a steady-state even if there is no
EVID column in the data-set.
However an II column is mandatory to specify the period between the five added doses to reach
steady-state. The absence of this column will throw an exception (see hereunder for the complete list of exceptions).
It is possible to find in a data-set a mix of steady-state and non steady-state doses. To
prevent doses from colliding it has been decided not to add doses before a user defined dose.
Let’s take an example:
157
Monolix 4.3.3
In-depth description of column-types
ID
Tom
TIME
-10
AMT
4
SS
0
II
0
EVID
1
Y
.
Tom
-5
5
0
0
4
.
Tom
0
5
1
2
1
.
COMMENT
User entered a dose at time (-10).
This dose does not have steady-state and collides with dose at time (0) with steady-state
since it normally implies addition of doses at
times {-25, -20, ... , -5}
These conflicting declarations are solved by the
cancellation of doses at time {-25, -20, -15,
-10}
This dose is automatically added.
Note that the first dose has still wash-out (EVID
= 4)
This line implies that system shall have reached
its steady-state at time 0.
This is why 5 doses are added (at times -25,
-20, ... , -5) before this dose.
Format restrictions:
- a data-set shall not contain more than one column with column-type SS (an exception
will be thrown otherwise).
- a data-set shall not contain more than one column with column-type II (an exception
will be thrown otherwise).
- when a data-set contains a column with column-type SS and no column with column-type
II then an exception is thrown.
- when a data-set contains a column with column-type II and no column with column-type
SS or ADDL then a SS column is created with:
- SS = 1 when inter-dose interval is strictly positive
- SS = 0 otherwise
- when a data-set contains a column with column-type II and no column with column-type
SS but a column with column-type ADDL then a SS column is created with:
- SS = 1 when inter-dose interval is strictly positive and ADDL = 0
- SS = 0 otherwise
- the column is meaningful only for dose-lines. Its format shall be (for all lines including
reponse-lines for which SS information is not applicable) :
- SS shall be either 0 or 1 (‘.’ will be replaced by 0)
- II shall contain a double value and
158
Monolix 4.3.3
In-depth description of column-types
- iivalue shall be positive (or null).
- when SS = 0 then iivalue shall be null.
- when SS = 1, iivalue shall be strictly positive.
An exception is thrown in case of non-compliance.
159
Monolix 4.3.3
In-depth description of column-types
ADDL: Additional dose line
Additional dose lines is a useful shortcut to specify dose regimens with repetitive treatments.
For instance to specify a dose of 10 every 12 hours during 3 days it is possible to write:
ID
Tom
Tom
Tom
Tom
Tom
Tom
Tom
TIME
0
12
24
36
48
60
72
AMT
10
10
10
10
10
10
10
Comment
Dose of 10 during 3 days.
but ADDL and II (interdose-interval) can also be used to specify the same information in a
single line
ID
Tom
TIME
0
AMT
10
ADDL
6
II
12
Comment
Seven (6+1) doses of 10 evey 12 hours ⇔ dose
of 10 during 3 days.
More details on the ADDL column:
- ADDL shall only contain positive (or null) integers or ‘.’ (which will be replaced by 0).
Non-compliance will throw an exception
- when there is an ADDL column there shall exist an II (interdose interval) column. Noncompliance will throw an exception
- for dose-lines with ADDL strictly positive, the interdose-interval shall be striclty positive (non-compliance will throw an exception).
ADDL is the number of times the dose shall be repeated and column II contains the dose
repetition interval. With following notations:
ID
1
TIME
tDose
AMT
damount
ADDL
nADDL
II
iDose
there will be (nADDL +1) doses of damount at times tDose , tDose +iDose , tDose +2iDose , ... ,
tDose +nADDL iDose
Two important remarks concerning regression values:
160
Monolix 4.3.3
In-depth description of column-types
- if there is a regression-column (i.e. a colum with column-type X), its value will also be
repeated for added doses.
Even though this value has not been specified but obtained via interpolation (see
section B.2.5).
With following notations:
ID
TIME
AMT
tDose
1
ADDL
damount
nADDL
II
iDose
X(REG)
xReg
additional regressions (the regression is set to xReg ) are added at times tDose , tDose +iDose ,
tDose +2iDose , ... , tDose +nADDL iDose .
Reminder: xReg is either a numerical value or ‘.’ which means that its value will be set
by interpolation (see section B.2.5)
- when regression values are defined after the first added dose, warnings are generated.
Indeed these values will not be repeated and can possibly interfer with automatically added
regression values at dose time. So the warning is generated for the user to confirm that its
data make sense.
For instance the following data-set will generate a warning:
ID
1
TIME
0
AMT
10
ADDL
3
II
10
X
6
1
1
2
4
.
.
.
.
.
.
4
.
1
1
5
7
.
.
.
.
.
.
4.5
1.8
Y
.
COMMENT
This line specifies a regimen of 4 doses of 10
every 6 hours. Regression value is set to 6.
5
Response-line. Regression value set to 4
3
Response-line. No regression value defined (a
NaN will be generated for the regression at this
time stamp since there is no interpolation for
response-line - see section B.2.5)
1.5 Response-line. Regression value set to 4.5
0.12 A warning is generated for this line since it
defines regression value after an automatically
added dose. Indeed first line specified that doses
shall be created at times 6, 12, 18.
Note: concerning wash-outs for repeated dose: if a dose has wash-out (EVID=4) and a repetition
is required, duplicated doses will have wash-out set to false. Following table illustrates this point:
ID
1
TIME
0
AMT
10
ADDL
3
II
10
EVID
4
1
1
1
6
12
18
10
10
10
0
0
0
0
.
.
1
1
1
161
COMMENT
This line specifies a regimen of 4 doses of 10 every 6
hours. What’s more first dose has wash-out
Three additional doses are generated as required.
There is no wash-out for these doses. EVID is set to 1
since additional lines are dose lines.
Monolix 4.3.3
In-depth description of column-types
B.2.4
Description of column-types used to define covariates
COV: Continuous Covariate
It is possible to have in a data-set one or several columns with column-type COV.
Continuous covariate columns shall contain either strings that can be converted to double or ‘.’
(an exception will be thrown otherwise).
There shall be one covariate defined per subject-occasion and an exception will be thrown
- if there are several values defined for the same subject-occasion
- if there is no value defined for a subject-occasion.
Note: String ‘.’ can be used to prevent multiple definitions of a covariate for a subject-occasion
(it is interpreted as an absence of definition).
Several valid and problematic schemes are given in the following tables:
ID
Tom
Tom
Tom
Tom
ID
Tom
Tom
Tom
Tom
Tom
ID
Tom
Tom
Tom
ID
Tom
Tom
Tom
Tom
OCC
1
1
1
1
COV
13
13
13
13
OCC
1
1
1
1
1
.
.
12
.
.
1
1
1
Comment
Continuous covariate set to 12 for id Tom, first
occasion.
Note: covariate has not necessarily to be defined at
first occurrence of subject-occasion in the
data-set.
COV
.
.
.
OCC
1
1
1
1
Continuous covariate set to 13 for id Tom, first
occasion.
COV
OCC
Comment
Comment
Exception thrown: continuous covariate undefined
for subject Tim first occasion.
COV
.
.
12
14
Comment
Exception thrown: two different continuous
covariate values for subject Tom first occasion.
162
Monolix 4.3.3
In-depth description of column-types
CAT: categorical covariate.
It is possible to have in a data-set one or several columns with column-type CAT.
It is possible to enter in a CAT column any string and ‘.’ has no special meaning.
There shall be one categorical covariable defined per subject-occasion and an exception will
be thrown:
- if there are several values defined for the same subject-occasion
- if there is no value defined for a subject-occasion.
Note: as string ‘.’ has no peculiar interpretation, following scheme will throw an exception:
ID
Tom
Tom
Tom
Tom
OCC
1
1
1
1
CAT
.
.
F
.
Comment
Exception thrown: two different categorical
covariates (‘.’ and ‘F’) have been found for id Tom,
first occasion.
163
Monolix 4.3.3
In-depth description of column-types
B.2.5
Description of column-types used to define regressions
X: regression value
It is possible to have in a data-set one ot several columns with column-type X.
The regression-columns (i.e. columns with column-type X) shall contain either strings that
can be converted to double or ‘.’ (non-compliance will raise an exception).
Within a given subject-occasion, string ‘.’ will be interpolated (nearest neighbor interpolation is used) for dose-lines only (N.B.: if there is an EVID column dose-lines correspond to
EVID = 1 or EVID = 4)
If a subject-occasion contains only ‘.’ for a regression an exception is thrown (since it is
then impossible to interpolate values).
NOTE: An exception is raised when within a subject-occasion there are two different values
for a regression at the same time.
Let’s take an example:
ID
Tom
Tom
Tom
Tom
Tom
Tom
Tom
Tom
Tom
Tom
Tom
Tom
Tom
Tom
OCC
1
1
1
1
1
1
1
2
2
2
3
3
3
3
TIME
0
5
10
15
20
25
30
0
5
10
0
5
5
10
X
.
1
.
12
-6
.
.
.
1
.
0.1
1
1.1
10
AMT
1
.
.
1.5
.
0.2
.
1
.
.
1
.
2
.
Y
.
12
10
.
8
.
0.1
.
12
10
.
12
.
14
EVID
1
0
0
1
0
4
0
1
0
0
1
0
1
0
Comment
Regression X will be interpolated at
times 0 and 25 and will remain
undefined (i.e. set to NaN) at times
10, 20, 30.
Exception thrown: No regression
value defined for subject Tom
second occasion.
Exception thrown: Regression is
defined twice at time 5 with
different values (X=1 first time and
X=1.1 on following line).
NOTE: For first occasion X is set to:
- X(0) = 1 (it is a dose-line so an interpolation is realized. Note: nearest interpolation is
realized and here nearest sample corresponds to a response-line)
- X(5) = 1 (from direct reading of input file even if the line does not correspond to a dose)
164
Monolix 4.3.3
In-depth description of column-types
- X(10) = NaN (regression is undefined in the input file but since it is not a dose-line, no
interpolation is realized)
- X(15) = 12 (from direct reading of input file)
- X(20) = -6 (from direct reading of input file even though the line does not correspond to
a dose)
- X(25) = -6 (it is a dose-line so an interpolation is realized. Note: nearest interpolation
is realized and here nearest sample corresponds to a response-line)
- X(30) = NaN (regression is undefined in the input file but since it is not a dose-line, no
interpolation is realized)
165
Monolix 4.3.3
In-depth description of column-types
B.2.6
Description of column-types used to define responses
Y: Response
A data-set shall not contain more than one column with column-type Y (an exception will be
thrown otherwise).
Response-column (i.e. column with column-type Y) shall contain double value or string ‘.’.
Any other value will raise an exception.
When there is no EVID or MDV column (see hereunder), a line is considered as a response-line
if it contains:
- in response-column: a string which can be converted to a double value obsValue
- no dose-column (i.e. content of the column with dose-type AMT) or in dose-column:
either string ‘.’ or a 0
Note: When obsValue = 0, the line is considered as a response-line if there is no dose-column
or if string ‘.’ is in dose-column. As a consequence, when there are null values in both
dose-column and response-column, line is considered as a dose-line.
Note: when non null double value are both present in dose-column and response-column, an
exception is thrown (as already state a line can not be a dose-line and a response-line).
Following table sums up the different situations
...
...
...
...
DOSE
0
3.14
12
0
.
0
Y
...
...
.
0
0
1.1
...
14
8.8
Comment
Two null values ⇒ line is considered as a dose-line
String ‘.’ in response-column ⇒ dose-line
Null double in column observation and non null value
in column dose ⇒ dose-line
String ’.’ in dose column ⇒ response-line
Null value in dose-column and non null value in
response-column ⇒ response-line
Exception thrown: double non null values in both
columns
166
Monolix 4.3.3
In-depth description of column-types
YTYPE: reponse type
A data-set shall not contain more than one column with column-type YTYPE (an exception will
be thrown otherwise). An exception is also thrown if the data-set contains a column ADM_CMT
and a column YTYPE (see section B.2.3 for description of column CMT).
For response-lines, YTYPE identifies the response type or name with ‘.’ not interpreted as a
repetition or previous line but as the name of a reponse. For instance with:
TIME
0
5
10
15
20
25
DOSE
Y
.
.
.
.
.
.
12
6
4
3
2.1
2
Y_TYPE
Cc
Cc
.
.
Cc2
Cc2
three different types of responses are created:
- Response ‘Cc’: yCc (0) = 12, yCc (5) = 6
- Response ‘.’: y. (10) = 4, y. (15) = 3
- Response ‘Cc2’: yCc2 (20) = 2.1, yCc2 (25) = 2
CENS: censored response
A data-set shall not contain more than one column with column-type CENS (an exception will
be thrown otherwise).
Possible values are -1, 1, 0 (string ‘.’ will be interpreted as 0) and an exception will be
thrown if any other value is used.
- CENS = 1 means that the value in response-column (yobserved , the content of the column
with column-type Y) is an upper limit ⇔ true observation y verifies y < yobserved
- CENS = 0 means the the value in response-column corresponds to a valid observation (no
interval associated)
- CENS = -1 means that the value in response-column (yobserved ) is a lower bound ⇔ true
observation y verifies y > yobserved
167
Monolix 4.3.3
In-depth description of column-types
LIMIT: limit for censored values.
A data-set shall not contain more than one column with column-type LIMIT (an exception will
be thrown otherwise).
If a data-set contains a column with column-type LIMIT, it shall contain a column with
column-type CENS (an exception is thrown otherwise).
Column LIMIT shall contain either a string that can be converted to a double or ‘.’ (non
compliance will raise an exception).
- when column LIMIT contains a string that can be converted to a double and CENS = 1,
then value ylimit in column LIMIT is interpreted as the lower bound of the observation
interval ⇔ with yobserved the value in the response-column (the content of the column
with column-type Y), true observation y verifies ylimit < y < yobserved
- when column LIMIT contains a string that can be converted to a double and CENS = -1,
then value ylimit in column LIMIT is interpreted as the upper bound of the observation
interval ⇔ with yobserved the value in the response-column, true observation y verifies
ylimit > y > yobserved
168
Monolix 4.3.3
In-depth description of column-types
B.2.7
Description of column-types used to define controls and events
EVID: event identification data item.
A data-set shall not contain more than one column with column-type EVID (an exception will
be thrown otherwise).
- EVID shall contain an integer belonging to interval [0 ; 4]:
- EVID = 0 or ‘.’: observation event ⇔ the line is a response-line
- EVID = 1: dose event ⇔ the line is a dose-line
- EVID = 2: other event. UNUSED (exception thrown)
- EVID = 3: reset event. UNUSED (exception thrown)
- EVID = 4: reset dose event ⇔ indicates wash-out
Non-compliance with above format will raise exception.
Note: when a line is tagged (EVID = 0 or ‘.’) and the observation contained in column Y
cannot be converted to a double value, an exception is thrown. Indeed since EVID = 0 indicates
that the line is a response-line there is a contradiction if the content of Y cannot be converted
to a double.
Note: when a line is tagged (EVID = 1, EVID = 4) with a string in dose-column (i.e. content of
the colum with column-type AMT) which cannot be converted to a double an exception is thrown
(same rationale that in preceding note).
MDV: Missing dependent values.
It is possible to have in a data-set one or several columns with column-type MDV.
MDV shall contain only integers belonging to interval [0; 2]. Non-compliance will raise an exception.
When there are multiple MDV columns, a synthetic value MDVsynth is computed as:
- if MDV = 0 in all columns ⇒ MDVsynth = 0
- if MDV = 1 in at least one column ⇒ MDVsynth = 1
- if MDV = 2 in at least one column (and no column with MDV = 1) ⇒ MDVsynth = 2
When a line is tagged MDV = 1 then the value in column Y will not be taken into account (the
value in dose-column - if any valid value is present - will be taken into account).
169
Monolix 4.3.3
In-depth description of column-types
When a line is tagged MDV = 0 AND if it contains a string convertible to a double value in
response-column (the column with column-type Y) then the value is taken into acount. Otherwise an exception will be thrown. Values in dose-column (the column with column-type AMT)
will not be taken into account.
When a line is tagged MDV = 2 then the value in response-column is not taken into acvount (the
value in dose-column, if present, will be taken into account). The values in regressions-columns
are taken into account.
MDV and EVID cross checks.
An exception is thrown when MDV = 1 and EVID = 0 (it is considered as a conflicting instruction since EVID indicates that line shall be a response-line and the MDV that data in the
response-column shall be discarded).
An exception is also thrown when MDV = 0 and EVID = 1 (same reason as previously).
170
Monolix 4.3.3
Appendix C
Preferences
This appendix provides the details of Monolix preferences. The preferences are defined in the
preferences.xmlx file. The file is loaded when Monolix is started.
C.1
General
The user can modify the data to customize his own preferences.
1. Go to directory /Path/To/lixoft/monolix/config/ and open the preference.xmlx file.
2. Modify the chosen fields, then save and restart Monolix if the software is opened.
Note :To restore default settings, just delete the file and restart.
This chapter describes the correspondences between the file data and preferences in Monolix.
C.2
Graphic settings
Generally, data are visual settings of graphics.
There are 3 kinds of patterns:
1. matrix - value corresponds to the number of rows and vector contains all the elements of
the matrix.
2. list of chars - <charList> tag contains a set of tags <char> which have chars as value.
3. numeric value - can be a string, an integer or a real.
171
Graphic settings
C.2.1
Categorized Data
Data
fill_cat_color
fill_out_color
fill_CI
line_LineStyle
line_LineWidth
line_Color
bins_Color
figure_background
C.2.2
Description
Color of theoretical distribution line
Outliers color
Color of confidence intervals
Lines style
Lines width
Lines color
Color of bins limit lines
Color of figure background
Type
matrix
matrix
matrix
value
value
matrix
matrix
matrix
Covariates
Data
data_Color
data_Marker
data_MarkerSize
spline_LineStyle
spline_LineWidth
spline_Color
regression_LineStyle
regression_LineWidth
regression_Color
line_LineStyle
line_LineWidth
line_Color
figure_background
Description
Data colors
Data markers
Size of data markers
Line style of spline
Line width of spline
Line color of spline
Style of regression line
Width of regression line
Color of regression line
Lines style
Lines width
Lines color
Color of figure background
172
Type
matrix
List of characters
value
value
value
matrix
value
value
matrix
value
value
matrix
matrix
Monolix 4.3.3
Graphic settings
C.2.3
Parameters distribution
Data
histo_Color
paramEstimatedPDF_LineStyle
paramEstimatedPDF_LineWidth
paramEstimatedPDF_Color
predictedPdf_LineStyle
predictedPdf_LineWidth
predictedPdf_Color
predictedEstimatedPDF_LineStyle
predictedEstimatedPDF_LineWidth
predictedEstimatedPDF_Color
confidence_LineStyle
confidence_LineWidth
confidence_Color
figure_background
C.2.4
Description
Histogram color
Style of non parametric pdf line
Width of non parametric pdf line
Color of non parametric pdf line
Style of population distribution line
Width of population distribution line
Color of population distribution line
Style of theoretical median line
Width of theoretical median line
Color of theoretical median line
Style of confidence intervals line
Width of confidence intervals line
Color of confidence intervals line
Color of figure background
Type
matrix
value
value
matrix
value
value
matrix
value
value
matrix
value
value
matrix
matrix
Individual fits
Data
data_Color
data_Marker
data_MarkerSize
cens_Color
cens_Marker
cens_MarkerSize
populationFits_Color
populationFits_LineStyle
populationFits_LineWidth
IndividualFits_Color
IndividualFits_LineStyle
IndividualFits_LineWidth
percentile
confidence_pop_color
confidence_pop_linestyle
median_pop_linestyle
median_pop_color
figure_background
Description
Data colors
Data markers
Size of data markers
Censored data colors
Censored data markers
Size of censored data markers
Color of population fits line
Style of population fits line
Width of population fits line
Color of individual fits line
Style of individual fits line
Width of individual fits line
Percentile marker
Color of prediction interval line
Style of prediction interval line
Style of median line
Color of median line
Color of figure background
173
Type
matrix
List of characters
value
matrix
List of characters
value
matrix
value
value
matrix
value
value
value
matrix
value
value
matrix
matrix
Monolix 4.3.3
Graphic settings
C.2.5
Joint distribution
Data
data_Color
data_Marker
data_MarkerSize
spline_LineStyle
spline_LineWidth
spline_Color
regression_LineStyle
regression_LineWidth
regression_Color
figure_background
C.2.6
Description
Data colors
Data markers
Size of data markers
Line style of spline
Line width of spline
Line color of spline
Style of regression line
Width of regression line
Color of regression line
Color of figure background
Type
matrix
List of characters
value
value
value
matrix
value
value
matrix
matrix
Predictions vs observations
Data
data_Color
data_Marker
data_MarkerSize
cens_Color
cens_Marker
cens_MarkerSize
spline_LineStyle
spline_LineWidth
spline_Color
regression_LineStyle
regression_LineWidth
regression_Color
figure_background
segments_LineStyle
segments_LineWidth
segments_Color
Description
Data colors
Data markers
Size of data markers
Censored data colors
Censored data markers
Size of censored data markers
Line style of spline
Line width of spline
Line color of spline
Style of regression line
Width of regression line
Color of regression line
Color of figure background
Line style of segments
Line width of segments
Line color of segments
174
Type
matrix
List of characters
value
matrix
List of characters
value
value
value
matrix
value
value
matrix
matrix
value
value
matrix
Monolix 4.3.3
Graphic settings
C.2.7
Residuals
Data
data_Color
data_Marker
data_MarkerSize
cens_Color
cens_Marker
cens_MarkerSize
spline_LineStyle
spline_LineWidth
spline_Color
line_LineStyle
line_LineWidth
line_Color
bins_Color
plot_emp_color
plot_emp_linestyle
plot_emp_linewidth
plot_emp_marker
plot_emp_markersize
plot_out_color
plot_sim_color
plot_sim_linewidth
plot_sim_linestyle
fill_cat_color
fill_out_color
regression_LineStyle
regression_LineWidth
regression_Color
histo_Color
empdens_LineStyle
empdens_LineWidth
empdens_Color
thdens_LineStyle
thdens_LineWidth
thdens_Color
figure_background
Description
Data colors
Data markers
Size of data markers
Censored data colors
Censored data markers
Size of censored data markers
Line style of spline
Line width of spline
Line color of spline
Lines style
Lines width
Lines color
Color of bins limit lines
Color of empirical percentile line
Style of empirical percentile line
Width of empirical percentile line
Marker of outlier dots
Size of outlier dots marker
Color of outlier dots
Color of theoretical percentile line
Width of theoretical percentile lines
Style of theoretical percentile lines
Color of confidence interval
Color of outliers area
Style of regression line
Width of regression line
Color of regression line
Histogram color
Style of empirical pdf line
Width of empirical pdf line
Color of empirical pdf line
Style of theoretical empirical pdf line
Width of theoretical empirical pdf line
Color of theoretical empirical pdf line
Color of figure background
175
List
List
List
List
Type
matrix
of characters
value
matrix
of characters
value
value
value
matrix
value
value
matrix
matrix
matrix
of characters
value
value
value
matrix
matrix
value
of characters
matrix
matrix
value
value
matrix
matrix
value
value
matrix
value
value
matrix
matrix
Monolix 4.3.3
Graphic settings
C.2.8
Spaghetti
Data
data_Color
data_Marker
data_MarkerSize
cens_Color
cens_Marker
cens_MarkerSize
line_LineStyle
line_LineWidth
figure_background
C.2.9
Description
Data colors
Data markers
Size of data markers
Censored data colors
Censored data markers
Size of censored data markers
Lines style
Lines width
Color of figure background
Type
matrix
List of characters
value
matrix
List of characters
value
value
value
matrix
Prediction distribution
Data
data_Color
data_Marker
data_MarkerSize
fill_shading
fill_shading_discrete
line_LineStyle
line_LineWidth
bins_Color
plot_emp_color
plot_emp_linestyle
plot_emp_linewidth
median_color
figure_background
Description
Data colors
Data markers
Size of data markers
Prediction distribution area
Prediction distribution area in discrete case
Lines style
Lines width
Color of bins limit lines
Color of empirical percentile line
Style of empirical percentile line
Width of empirical percentile line
Color of median line
Color of figure background
Type
matrix
List of characters
value
matrix
matrix
value
value
matrix
matrix
List of characters
value
matrix
matrix
For fill_shading and fill_shading_discrete settings, a 2 × 3 matrix is necessary, that corresponds to the two limit colors used to fill the areas.
176
Monolix 4.3.3
Graphic settings
C.2.10
VPC
Data
data_Color
data_Marker
data_MarkerSize
cens_Color
cens_Marker
cens_MarkerSize
line_LineStyle
line_LineWidth
line_Color
plot_emp_color
plot_emp_linestyle
plot_emp_linewidth
plot_emp_marker
plot_emp_markersize
plot_out_color
plot_sim_color
plot_sim_marker
plot_sim_markersize
plot_sim_linewidth
plot_sim_linestyle
fill_cat_color
fill_out_color
figure_background
C.2.11
Description
Data colors
Data markers
Size of data markers
Censored data colors
Censored data markers
Size of censored data markers
Lines style
Lines width
Lines color
Color of empirical percentile line
Style of empirical percentile line
Width of empirical percentile line
Marker of outlier dots
Size of outlier dots marker
Color of outlier dots
Color of theoretical percentile line
Marker of theoretical percentile
Size of theoretical percentile marker
Width of theoretical percentile lines
Style of theoretical percentile lines
Color of confidence interval
Color of outliers area
Color of figure background
List
List
List
List
Type
matrix
of characters
value
matrix
of characters
value
value
value
matrix
matrix
of characters
value
value
value
matrix
matrix
matrix
matrix
value
of characters
matrix
matrix
matrix
NPC - BLQ
Data
fill_cat_color
fill_out_color
fill_CI
line_LineStyle
line_LineWidth
line_Color
figure_background
Description
Color of theoretical CDF
Color of median line
Color of confidence intervals
Lines style
Lines width
Lines color
Color of figure background
177
Type
matrix
matrix
matrix
value
value
matrix
matrix
Monolix 4.3.3
Graphic settings
C.2.12
Time to event (Kaplan-Meier)
Data
figure_background
fill_shading
fill_shading_average
median_color
median_lineStyle
median_lineWidth
median_average_color
median_average_lineStyle
median_average_lineWidth
cens_Color
cens_Marker
cens_MarkerSize
average_color
average_lineStyle
average_lineWidth
survival_color
survival_lineStyle
survival_lineWidth
Description
Color of figure background
Confidence interval area
Confidence interval area for average
Color of median line
Line style of median
Line width of median
Color of average median
Line style of average median
Line width of average median
Censored data colors
Censored data markers
Size of censored data markers
Average line color
Line style of average
Line width of average
Survival function line color
Survival function line style
Survival function line width
Type
matrix
matrix
matrix
matrix
value
value
matrix
value
value
matrix
List of characters
value
matrix
value
value
matrix
value
value
For fill_shading setting, a 2 × 3 matrix is necessary, that corresponds to the two limit colors
used to fill the areas.
C.2.13
Transition probabilities
Data
figure_background
line_LineStyle
line_LineWidth
bins_Color
line_LineStyle
line_LineWidth
line_Color
Description
Color of figure background
Lines style
Lines width
Color of bins limit lines
Lines style
Lines width
Lines color
178
Type
matrix
value
value
matrix
value
value
matrix
Monolix 4.3.3
Session related settings
C.2.14
Prior distribution
Data
figure_background
confidence_LineStyle
confidence_LineWidth
confidence_Color
histo_Color
nonParamPDF_LineStyle
nonParamPDF_LineWidth
nonParamPDF_Color
priorPDF_LineStyle
priorPDF_LineWidth
priorPDF_Color
medianPDF_LineStyle
medianPDF_LineWidth
medianPDF_Color
C.2.15
Description
Color of figure background
Style of confidence intervals line
Width of confidence intervals line
Color of confidence intervals line
Histogram color
Style of non parametric pdf line
Width of non parametric pdf line
Color of non parametric pdf line
Style of prior distribution line
Width of prior distribution line
Color of prior distribution line
Style of theoretical median line
Width of theoretical median line
Color of theoretical median line
Type
matrix
value
value
matrix
matrix
value
value
matrix
value
value
matrix
value
value
matrix
Individual contribution
Data
figure_background
bar_Color
Description
Color of figure background
Color of bars
Type
matrix
matrix
For bar_Color setting, a 2 × 3 matrix is necessary, that corresponds to the two likelihoods.
C.2.16
Convergence of SAEM
Data
figure_background
C.3
C.3.1
Description
Color of figure background
Type
matrix
Session related settings
session
Field
timestamp_value
historic_size
nbDatasetRows
save_graphics_format
lockModels
modelFilter
Description
Use timestamping
Size of historic file (projects, models)
(see nbShownColumns in dataSelection gui)
Printed graphics format
Lock possibility to modify models
Filter of structural model
useCurrentFolderByDefault
editor
Use current folder by default
Editor to use
179
Type
value
value
value
value
value
’none’, ’m’ or
’mlxtran’
value
editor path
Monolix 4.3.3
Session related settings
C.3.2
project
Field
dosesToAddForSteadyState
C.3.3
Description
number of doses to simulate Steady state
Type
value
gui
datasetSelection
Field
nbShownColumns
nbRows
Description
number of columns to show
number of rows to show (maximum 10)
180
Type
value
value
Monolix 4.3.3
Bibliography
[1] Allassonnière, S., Kuhn, E., and Trouvé, A. Construction of Bayesian deformable
models via stochastic approximation algorithm: A convergence study. Bernoulli (to appear)
(2010).
[2] Bertrand, J., Comets, E., and Mentré, F. Detecting a gene effect in pharmacokinetic
models: comparison of different methods (poster). PAGE, Brugge (2006).
[3] Chan, P.and Jacqmin, P., Lavielle, M., McFadyen, L., and Weatherley,
B. The use of the SAEM algorithm in MONOLIX software for estimation of population pharmacokinetic-pharmacodynamic-viral dynamics parameters of maraviroc in asymptomatic HIV subjects. Journal of Pharmacokinetics and Pharmacodynamics (to appear)
(2010).
[4] Comets, E., Verstuyft, C., Lavielle, M., Jaillon, P., Becquemont, L., and
Mentre, F. Modelling the influence of MDR1 polymorphism on digoxin pharmacokinetic
parameters. European Journal of Clinical Pharmacology 63 (2007), 437–449.
[5] Davidian, M., and Giltinan, D. Nonlinear Models for Repeated Measurement Data.
Chapman and Hall, 1995.
[6] Davidian, M., and Giltinan, D. Nonlinear models for repeated measurements: An
overview and update. JABES 8 (2003), 387–419.
[7] Delattre, M., Del Moral, P., and Lavielle, M. The SAEM algorithm in MONOLIX
for non-linear mixed effects models with stochastic differential equations (poster). PAGE,
Berlin (2010).
[8] Delattre, M., Savic, R., Miller, R., Karlsson, M., and Lavielle, M. Estimation of mixed hidden Markov models with SAEM. Application to daily seizures data. (oral
presentation). PAGE, Berlin (2010).
[9] Delyon, B., Lavielle, M., and Moulines, E. Convergence of a stochastic approximation version of the EM algorithm. Ann. Statist. 27, 1 (1999), 94–128.
[10] Donnet, S., and Samson, A. Estimation of parameters in incomplete data models defined
by dynamical systems. Journ. of Stat. and Plan. Infer. 50 (2007), 2381–2398.
181
BIBLIOGRAPHY
[11] Girard, P., and Mentré, F. A comparison of estimation methods in nonlinear mixed
effects models using a blind analysis (oral presentation). PAGE, Pamplona (2005).
[12] Jaffrézic, F., Meza, C., Foulley, J., and Lavielle, M. The SAEM algorithm for
the analysis of nonlinear traits in genetic studies. Genetics Selection Evolution 38 (2006),
583–600.
[13] Kuhn, E., and Lavielle, M. Coupling a stochastic approximation version of EM with a
MCMC procedure. ESAIM P&S 8 (2004), 115–131.
[14] Kuhn, E., and Lavielle, M. Maximum likelihood estimation in nonlinear mixed effects
models. Computational Statistics and Data Analysis 49, 4 (2005), 1020–1038.
[15] Lavielle, M., and Kuhn, E. Maximum likelihood estimation in nonlinear mixed effects
models (oral communication). PAGE, Verona (2003).
[16] Lavielle, M., and Mentré, F. Estimation of population pharmacokinetic parameters
of saquinavir in HIV patients and covariate analysis with MONOLIX (poster). PAGE,
Pamplona (2005).
[17] Lavielle, M., and Mentré, F. Estimation of population pharmacokinetic parameters of
saquinavir in HIV patients with the MONOLIX software. Journal of Pharmacokinetics and
Pharmacodynamics 34, 2 (2007), 229–249.
[18] Lavielle, M., Mesa, H., Chatel, K., and Vermeulen, A. Mixture models and model
mixtures with MONOLIX (oral presentation). PAGE, Berlin (2010).
[19] Makowski, D., and Lavielle, M. Using SAEM to estimate parameters of models of
response to applied fertilizer. Jour. of Agr., Bio, and Env. Stat. 11, 1 (2006), 45–60.
[20] Panhard, X., and Samson, A. Extension of the SAEM algorithm for the estimation of
inter-occasion variability: application to the population pharmacokinetics of nelfinavir and
its metabolite m8 (poster). PAGE, Brugge (2006).
[21] Pinheiro, J. C., and Bates, D. M. Mixed-Effects Models in S and S-PLUS. Springer,
New York, 2000.
[22] Samson, A., Lavielle, M., and Mentré, F. Approximation EM algorithm in nonlinear
mixed effects models: an evaluation by simulation (oral communication). PAGE, Uppsala
(2004).
[23] Samson, A., Lavielle, M., and Mentré, F. Extension of the SAEM algorithm to
left-censored data in nonlinear mixed-effects model: application to HIV dynamics model.
Computational Statistics and Data Analysis 51 (2006), 1562–1574.
[24] Samson, A., Lavielle, M., and Mentré, F. The SAEM algorithm for non-linear mixed
models with left-censored data and differential systems: application to the joint modeling
of hiv viral load and cd4 dynamics under treatment (oral presentation). PAGE, Brugge
(2006).
182
Monolix 4.3.3
BIBLIOGRAPHY
[25] Samson, A., Lavielle, M., and Mentré, F. The SAEM algorithm for group comparison
tests in longitudinal data analysis based on nonlinear mixed-effects model. Stat. in Med. 26
(2007), 4860–4875.
[26] Samson, A., Panhard, X., Lavielle, M., and Mentré, F. Generalisation of the SAEM
algorithm to nonlinear mixed effects model defined by differential equations: application to
HIV viral dynamic models (poster). PAGE, Pamplona (2005).
[27] Savic, R., and Lavielle, M. A new SAEM algorithm: Performance in population models
for count data. Journal of Pharmacokinetics and Pharmacodynamics 36 (2009), 367–379.
[28] Savic, R., Mentre, F., and Lavielle, M. Implementation and evaluation of an SAEM
algorithm for longitudinal ordered categorical data with an illustration in pharmacometrics.
The AAPS Journal (to appear) (2010).
[29] Snoeck, E., Chanu, P., Lavielle, M., Jacqmin, P., Jonsson, N., Jorga, K., Goggin, T., Jumbe, S., and Frey, N. Hepatitis C viral dynamics explaining breakthrough,
relapse or response after chronic treatment. Clinical Pharmacology and Therapeutics (AAPS
Outstanding Manuscript Award in Modeling and Simulation) 87 (2010), 706–713.
183
Monolix 4.3.3
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement