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

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

Download PDF

advertisement