Version 2024

This documentation specifies the format of datasets for the MonolixSuite starting in 2018. It details:

• General structure: structure of a dataset for population modeling
• Format rules: rules to format your experimental data, using the available column types
• Examples: examples of real datasets with typical features (continuous data, discrete data, time-to-event data, censored data, data with several types of measurements, …)
• Nonmem differences: key differences with the Nonmem format

©Lixoft

Dataset for population modeling

The considered datasets are dedicated to population modeling. The population approach describes phenomena observed in each of a set of individuals and the variability between individuals. The data is thus individual data, and is often longitudinal (over time).  For each subject, the dataset contains measurements, dose regimen, covariates etc … i.e. all collected information.

General format

The data must be in long format, i.e each row is one time point per subject. For each row, the individuals ID, observations, dose amount, covariates, etc are recorded in different columns. The column names in the dataset header can be  set to anything, but the columns must be tagged using the available column types when defining the data in the applications of the MonolixSuite, such that the application knows how to interpret the data. The column types are very similar and compatible with the structure used by the Nonmem software.

File types: The file should be in text format with a file of .txt or .csv or .tsv. and the data must be separated by tab “\t”, comma “,”,  semicolon “;” or a space ” “. A header line is required specifying the column names. Additionally, starting with version 2024, Excel files with extensions .xls or .xlsx and SAS files with extensions .sas2bdat, and .xpt are supported.

Data set structure

The data set structure contains for each subject measurements, dose regimen, covariates etc … i.e. all collected information. The data must be in the long format, i.e each line corresponds to one individual and one time point. Different type of information (dose, observation, covariate, etc) are recorded in different columns, which must be tagged with a column type (see below). The column types are very similar and compatible with the structure used by the Nonmem software (the differences are listed here).

Description of line-types

Depending on the information it contains, each line will be considered as (with exception of the header line):

• dose-line: line that contains information about the dose’s regimen (and possibly also about covariates and regression variables)
• response-line: line that contains an observation (and possibly also about covariates and regression variables)
• both dose and response-line: line that contains information about both the dose regimen and an observation (and possibly also about covariates and regression variables)

The EVENT ID column-type can be used to enforce each line to be a dose or response line. Without EVENT ID column, the content of the AMOUNT, OBSERVATION and IGNORED OBSERVATION columns are used to assign lines as dose lines, response lines or both. A table summarizing all cases can be found here.

Changes with respect to the MonolixSuite2016R1 version:

In the MonolixSuite2016R1, a line could not be both a dose-line and a response-line. Two lines were necessary to define a dose information and a measure occurring at the same time. In particular, in the MonolixSuite2018R1 version, if there is a non null dose and a value in the response-column, we consider it as both dose and response. It was formerly considered as a response.

Description of column-types

The first line of the data set must be a header line, defining the names of the columns. The columns names are completely free. In the MonolixSuite applications, when defining the data, the user will be asked to assign each column to a column-type (see here for an example of this step). The column type will indicate to the application how to interpret the information in that column. The available column types are given below:

Column-types used for all types of lines:

• ID (mandatory): identifier of the individual
• OCCASION (formerly OCC): identifier (index) of the occasion
• TIME: time of the dose or observation record
• DATE/DAT1/DAT2/DAT3: date of the dose or observation record, to be used in combination with the TIME column
• EVENT ID (formerly EVID): identifier to indicate if the line is a dose-line or a response-line
• IGNORED OBSERVATION (formerly MDV): identifier to ignore the OBSERVATION information of that line
• IGNORED LINE (from 2019 version): identifier to ignore all the informations of that line
• CONTINUOUS COVARIATE (formerly COV): continuous covariates (which can take values on a continuous scale)
• CATEGORICAL COVARIATE (formerly CAT): categorical covariate (which can only take a finite number of values)
• REGRESSOR (formerly X): defines a regression variable, i.e a variable that can be used in the structural model (used e.g for time-varying covariates)
• IGNORE: ignores the information of that column for all lines

Column-types used for response-lines:

• OBSERVATION (mandatory, formerly Y): records the measurement/observation for continuous, count, categorical or time-to-event data
• OBSERVATION ID (formerly YTYPE): identifier for the observation type (to distinguish different types of observations, e.g PK and PD)
• CENSORING (formerly CENS): marks censored data, below the lower limit or above the upper limit of quantification
• LIMIT: upper or lower boundary for the censoring interval in case of CENSORING column

Column-types used for dose-lines:

• AMOUNT (formerly AMT): dose amount
• ADMINISTRATION ID (formerly ADM): identifier for the type of dose (given via different routes for instance)
• INFUSION RATE (formerly RATE): rate of the dose administration (used in particular for infusions)
• INFUSION DURATION (formerly TINF): duration of the dose administration (used in particular for infusions)
• ADDITIONAL DOSES (formerly ADDL): number of doses to add in addition to the defined dose, at intervals INTERDOSE INTERVAL
• INTERDOSE INTERVAL (formerly II): interdose interval for doses added using ADDITIONAL DOSES or STEADY-STATE column types
• STEADY STATE (formerly SS): marks that steady-state has been achieved, and will add a predefined number of doses before the actual dose, at interval INTERDOSE INTERVAL, in order to achieve steady-state

CONTINUOUS COVARIATE (formerly COV): continuous covariate

The column-type CONTINUOUS COVARIATE is used to tag continuous covariates, i.e covariates which can take values on a continuous scale (such as weight or age). Covariates tagged in the data set can (but don’t have to) be used as covariates in the model. The covariate value must be constant within subjects (or within occasions if occasions are present). If the value is not constant, the first value of each subject in time ordering will be used for all times (and a warning is generated). To define time varying covariate, use REGRESSORS (example here).

The allowed values are doubles or dot ‘.’. There must be at least one non-dot value per subject (or per occasion if occasions are defined).

Examples:

• Basic example: in the following data set, individual 1 has weight WT = 78, individual 2 has WT = 80 for all times points (first value in time ordering) and individual 3 has WT = 90.

ID  TIME  Y    WT 
1    0   5.7   78   
1    1   5.6   78 
2    0   6.7   80 
2    1   6.5   82 
3    0   7.8    . 
3    1   8.9   90

Format restrictions:

• Continuous covariate columns shall contain either a double or “.”.
• The covariate must be defined at least once per subject-occasion.
• The covariate must remain the same for all the lines within the same subject-occasion.

CATEGORICAL COVARIATE (formerly CAT): categorical covariate

The column-type CATEGORICAL COVARIATE is used to tag categorical covariates, i.e covariates which can only take a finite number of values (such as sex or a genotype). Covariates tagged in the data set can (but don’t have to) be used as covariates in the model. The covariate value must be constant within subjects (or within occasions if occasions are present). If the value is not constant, the first value of each subject in time ordering will be used for all times (and a warning is generated). To define time varying covariate, use REGRESSORS (example here).

The allowed values are strings, doubles or dot ‘.’. There must be at least one non-dot value per subject (or per occasion if occasions are defined), otherwise the category is considered to be ‘NA’.

Examples:

• Basic example: in the following data set, the covariate SEX has two categories ‘F’ and ‘M’ and the individual 3 has value ‘F’. The covariate GENO has three categories ‘1’, ‘2’ and ‘NA’ (coming from the individual 3 which has no valid value). The covariate RACE has only one category ‘1’. Individual 1 has RACE = 1, as this is the value defined first in time. RACE will not appear in the graphical user interface because it is not possible to use a covariate with only one category in a model.

ID  TIME  Y  SEX GENO RACE
1    0   5.7  F   1     1
1    1   5.6  F   1     2
2    0   6.7  M   2     1
2    1   6.5  M   2     1
3    0   7.8  .   .     1
3    1   8.9  F   .     1

Format restrictions:

• The covariate must be defined at least once per subject-occasion.
• The categorical covariate must be the same for all the lines with the same subject-occasion.

Character definition

We recommend to use only alphanumeric characters and the underscore “_” character in the strings of your data set.

Unfortunately, in the Monolix2016R1 suite, special characters such as spaces ” “, stars “*”, parentheses “(“, brackets “[“, dashes “-“, dots “.” and slashes “/” are not supported in:

• The headers
• The strings in CAT column.

Please be careful that if your data set includes unsupported characters, the error will only de detected and displayed when loading a saved project (and not when creating and saving the project).

This feature is back in MonolixSuite2018R1.

On the use of “.”

The “.” can be used in almost all the lines of the data set but has several meaning depending on the context. The following table summarizes the use of it.

This section presents several data sets to show some concrete data set and see how to integrate censored data, covariates, …

Joint data sets

• Warfarin data set: Warfarin is an anticoagulant normally used in the prevention of thrombosis and thromboembolism.  Plasma warfarin concentrations and Prothrombin Complex Response in thirty normal subjects after a single loading dose are measured. Both measurements are continuous.
• Remifentanil data set: Remifentanil is an opoid analgesic drug with a rapid onset and rapid recovery time. Both remifentanil concentration and EEG measurement are proposed on 65 healthy adults. Both measurements are continuous.
• PSA and survival data set: PSA kinetics and survival data for 400 men with metastatic Castration-Resistant Prostate Cancer (mCRPC) treated with docetaxel and prednisone, the first-line reference chemotherapy, which constituted the control arm of a phase 3 clinical trial. In this context of advanced disease, the incidence of death is high and the PSA kinetics is closely monitored after treatment initiation to rapidly detect a breakthrough in PSA and propose rescue strategies.

Theophylline data set

The data considered here are courtesy of Dr. Robert A. Upton of the University of California, San Francisco. Theophylline is a methylxanthine drug used in therapy for respiratory diseases such as chronic obstructive pulmonary disease (COPD) and asthma under a variety of brand names. Theophylline was administered orally to 12 subjects whose serum concentrations were measured at 11 times over the next 25 hours. This is an example of a laboratory pharmacokinetic study characterized by many observations on a moderate number of individuals. A representation of the concentration over time for each subject is presented on the following figure (notice, that this figure was generated using Datxplore).

The purpose of this page is to see the construction, the definition and the use of such a data set in Datxplore and Monolix. For sake of simplicity, we look only on one subject (corresponding to ID 1).

Simplified data set

The data set for subject one writes as follows

ID AMT TIME    CONC    WEIGHT  SEX
1   4.02    0   .   79.6    M
1   .   0.25    2.84    79.6    M
1   .   0.57    6.57    79.6    M
1   .   1.12    10.5    79.6    M
1   .   2.02    9.66    79.6    M
1   .   3.82    8.58    79.6    M
1   .   5.1 8.36    79.6    M
1   .   7.03    7.47    79.6    M
1   .   9.05    6.89    79.6    M
1   .   12.12   5.94    79.6    M
1   .   24.37   3.28    79.6    M

Interpretation

One can see the following columns

• ID: the subject ID, column-type ID.
• AMT: the amount of drug provided to this subject, column-type AMOUNT.
• TIME: the time of the event, column-type TIME.
• CONC: the measured concentration, column-type OBSERVATION.
• WEIGHT: Weight of the subject, column-type CATEGORICAL COVARIATE.
• SEX: Sex of the subject, column-type CATEGORICAL COVARIATE.

Several points can be noticed.

1. The first line corresponds to a dose, while the other ones are measurements. This explains the dot in the CONC column for the first line and the dots in the AMT column for the other ones.
2. The covariates columns (the continuous WEIGHT and the categorical SEX) are constant over the individual. Even though it is not necessary, we encourage the user to fill the columns for readability and usage reasons.
3. Finally, notice that no initial washout is needed at the beginning as by default, the null initial condition is used for parameter estimation.

This data set has been originally published in:

Aarons, L., Vozeh, S., Wenk, M., Weiss, P. H., & Follath, F. (1989). Population pharmacokinetics of tobramycin. British journal of clinical pharmacology, 28(3), 305-314.

Tobramycin is an antimicrobial agent of the aminoglycosides family, which is among others used against severe gram-negative infections. Because tobramycin does not pass the gastro-intestinal tract, it is usually administrated intravenously as intermittent bolus doses or short infusions. Tobramycin is a drug with a narrow therapeutic index.
Tobramycin bolus doses ranging from 20 to 140mg were administrated every 8 hours in 97 patients (45 females, 52 male) during 1 to 21 days (for most patients, during ~6 days). Age, weight (kg), sex and creatinine clearance (mL/min) were available as covariates. The tobramycin concentration (mg/L) was measured 1 to 9 times per patients (322 measures in total), most of the time between 2 and 6h post-dose. This sparse data set is presented on the figure below

Below is an extract of the data set:

The columns have the following meaning:

• ID: the subject’s ID, column-type ID.
• TIME: the time of the record (administration or measurement) in hours, column-type TIME.
• CP: the measured drug’s concentration in mg/L, column-type OBSERVATION.
• EVID: event identifier, 1 for doses and 0 for response lines (measurements), column-type EVENT ID.
• DOSE: the amount of drug administrated to this subject in mg, column-type AMOUNT.
• WT: weight of the subject in kg, column-type CONTINUOUS COVARIATE.
• SEX: sex of the subject, column-type CATEGORICAL COVARIATE.
• CLCR: creatinine clearance of the subject in mL/min, column-type CONTINUOUS COVARIATE.

Several points can be noticed:

1. The four first lines correspond to doses, while the other ones are measurements, as indicated by the EVID column. The MDV column is not necessary. The zeros of the DOSE and CP columns could have been replaced by dots ‘.’ .
2. The covariates columns (WT, SEX and CLCR) are filled with the same value for each individual. Covariates must be constant within subjects (or subject-occasions when occasions are defined).

The data set and datxplore project file are in Datxplore demos.

HIV data set

In the COPHAR II-ANRS 134 trial, an open prospective non-randomized interventional study, 115 HIV-infected patients adults started an antiviral therapy. 48 patients were treated with indinavir (and ritonavir as a booster) (treatment A), 38 with lopinavir (and ritonavir as a booster) (treatment B), and 35 with nelfinavir (Treatment C). patients were followed one year after treatment initialization.

Viral load and CD4 cell count were measured at screenin, at inclusion and at weeks 2 (or 4), 8, 16, 24, 36, and 48. Plasma HIV-1-RNA were measured by Roche monitored with a limit of quantification of 50 copies/ml. The results of this trial are reported in Duval and al. (2009). The simulated data set is in Datxplore demos.

On the two following figures, one could see the two outputs with respect to time for all subjects split by treatments. The red circle corresponds to censored data.

Notice, that these figures were generated using Datxplore.

Simplified HIV data set

The data set for subject 2 can be defined as follows

ID TIME    Y_NCENS Y   CENS    YTYPE   TREATMENT
2   -2.43   4.9443  4.9443  0   1    A   
2   -2.43   249 249 0   2    A   
2   0   4.5245  4.5245  0   1    A   
2   2   2.3546  2.3546  0   1    A   
2   2   266 266 0   2    A   
2   4.29    268 268 0   2    A   
2   8   2.5585  2.5585  0   1    A   
2   8   34  34  0   2    A   
2   16  352 352 0   2    A   
2   24  1.7981  2   1   1    A   
2   24  385 385 0   2    A   
2   32  348 348 0   2    A   
2   43  415 415 0   2    A

Interpretation

One can see the following columns

• ID: the subject ID, column-type ID.
• TIME: the time of the measurement, column-type TIME.
• Y_NCENS: Non censored measurement. Ignored in the representation.
• Y: Considered measurement taking the censoring constraints into account, column-type OBSERVATION.
• CENS: Explicit if the data is censored or not, and the associated type of censoring, column-type CENSORING.
• YTYPE: the type of measurement. In this study, one has two measurements, column-type OBSERVATION ID.
• TREATMENT: Type of treatment, considered as a categorical covariate in our case, column-type CATEGORICAL COVARIATE.

Several points can be noticed.

1. There are no dose in the data set.
2. There is only a categorical covariate defining the treatment.
3. In the presented case, one does not necessary have both measurements at the same time. Indeed, this is not required for data export using Datxplore, nor parameter estimation using Monolix. Moreover, measurements for negative time is possible.

This data set has been originally published in:

Plusquellec, Y, Campistron, G, Staveris, S, Barre, J, Jung, L, Tillement, JP, Houin, G (1987). A double-peak phenomenon in the pharmacokinetics of veralipride after oral administration: a double-site model for drug absorption. J Pharmacokinet Biopharm, 15, 3:225-39.

Veralipride is a benzamide neuroleptic medicine indicated in the treatment of vasomotor symptoms associated with the menopause.
In this dataset, 100 mg doses of veralipride were given to 12 healthy volunteers by oral solution. Individual plasma concentrations of veralipride (ng/ml) were observed at 16 time points during 24h (time is measured in h) after the administration. Doses were given in the morning after an overnight fast, and subjects fasted up to 4 hr after drug administration in each case.

This data set is displayed on the figure below. For some individuals, as the one highlighted on the figure, a double peak in plasma concentrations was observed after oral administration of the solution.

This double peak phenomenon is not systematically noticeable, as can be seen on the next figure.

Below is an extract of the data set file:

The columns are:

• ID: the subject ID, column-type ID.
• TIME: the time of the measurement or of the dose, column-type TIME.
• AMT: the amount of drug provided to this subject, column-type AMOUNT
• Y: the measurement, column-type OBSERVATION.

The data set and datxplore project file can be in Datxplore demos.

This data set has been originally published in:

Influence of age and gender on the pharmacokinetics and pharmacodynamics of remifentanil. I. Model development. Anesthesiology, Minto, et al. (1997)

Remifentanil is an opioid analgesic drug with a rapid onset and rapid recovery time. It is used for sedation as well as combined with other medications for use in general anesthesia. It is given in adults via continuous IV infusion.

65 healthy adults have received remifentanil IV infusion at a constant diffusion rate between 1 and 8 µg.kg^-1.min^-1 for 4 to 20 minutes. The data set contains remifentanil admission characteristics (time and rate of infusion), dense measurements of remifentanil blood concentration during infusion and after (PK data), as well as dense electroencephalogram measurements (PD data) recording the depth of anesthesia. In addition, a list of covariates is available: age, gender, and lean body mass (LBM). Moreover, a variable TINFCAT classifies the patients in several categories with similar infusion time.

One can see on the following figure the remifentanil concentrations over time split in two groups (female and male). On each figure, the subjects with age lower than 50 are in blue while the ones with an age over 50 are in green.

On the following figure, one can see the electroencephalogram measurements with respect to time for all subjects.

Below is an extract of the data set file:

The columns have the following meaning:

• ID: the subject’s ID, column-type ID.
• TIME: the time of the record (administration or measurement) in minutes, column-type TIME.
• AMT: the amount of drug,column-type AMOUT.
• RATE: the rate of drug delivery, column-type INFUSTION RATE.
• DV: remifentanil concentration measurement or electroencephalogram measurement, column-type OBSERVATION.
• YTYPE: the type of measurement. There are two measurement types in this data set: the remifentanil concentration measurement (corresponding to the PK dynamics), and the electroencephalogram measurement (corresponding to the PD-part), column-type OBSERAVTION ID.
• MDV: Missing Data Variable, column-type MDV.
• AGE: Age of the subject in year, column-type CONTINUOUS COVARIATE.
• SEX: sex of the subject (F for female and M for male), column-type CATEGORICAL COVARIATE.
• LBM: lean body mass, column-type CONTINUOUS COVARIATE.
• TINFCAT: Categories of infusion time, column-type CATEGORICAL COVARIATE.

The data set and datxplore project file can be found in Datxplore demos.

This data set has been originally published in:

Leppik, IE. et al. (1985) A double-blind crossover evaluation of progabide in partial seizures. Neurology 35, 285.

The data arose from a clinical trial of 59 epileptics who were randomized to receive either the anti-epileptic drug progabide or a placebo, as an adjuvant to standard chemotherapy. The hope was that progabide would help to reduce the number of seizures experienced by patients. Patients attended four successive post-randomisation clinic visits, where the number of seizures that occurred over the previous 2 weeks was reported. At baseline, information on the age of the patient and the 8-week pre-randomisation seizure count was recorded.

Below is an extract of the data set:

The columns have the following meaning:

• treatment: factor with levels placebo progabide indicating whether the anti-epilepsy drug Progabide has been applied or not, column-type CATEGORICAL COVARIATE.
• base: number of epileptic attacks recorded during 8 week period prior to randomization, column-type CONTINUOUS COVARIATE.
• age: age of the patients, column-type CONTINUOUS COVARIATE.
• seizure_rate: number of epilepsy attacks patients have during the follow-up period, column-type OBSERVATION.
• period: measurement period, column-type TIME.
• subject: patient identification number, column-type ID.

Several points can be noticed:

1. There are several seizure counts for each individual, thus the time allows to define to which period it is related.
2. ID and TIME column are mandatory. Thus, if there is only one count measurement by individual, an additional column with TIME should be added (full of 0 for example).
3. The covariates columns (treatment, base and age) are filled with the same value for each individual. Covariates must be constant within subjects (or subject-occasions when occasions are defined).

Moreover, we can split by the covariate treatment and thus see the impact of the treatment

It seems the the subjects with the treatment have lower seizure rate. We can also display it grouped and not in a spaghetti display as in the following

Using that, we have a better understanding of the seizure_rate, and it seems that the treatment is effective.

Data set issued from a study of the adverse events of a drug on 117 patients affected by Crohn’s disease (a chronic inflammatory disease of the intestines). In addition to the response variable AE (number of adverse events), 7 explanatory variables were recorded for each patient: BMI (body mass index), HEIGHT, COUNTRY (one of the two countries where the patient lives), SEX, AGE, WEIGHT, and TREAT (the drug taken by the patient in factor form: placebo, d1, d2).

Below is an extract of the data set:

The definition of the columns is the following:

• ID: subject identifier, column-type ID
• TIME: constant to 0, column-type TIME. This column is mandatory. Thus all the values are fixed to 0 as there is only one evaluation.
• nrAdvE: the number of adverse events during the period, column-type OBSERVATION.
• BMI: body mass index, column-type CONTINUOUS COVARIATE
• height: height of the subject in cm, column-type CONTINUOUS COVARIATE
• country: country of the subject, column-type CATEGORICAL COVARIATE
• sex: sex of the subject (M or F), column-type CATEGORICAL COVARIATE
• age: age of the subject (in year), column-type CONTINUOUS COVARIATE
• weight: weight of the subject in kg, column-type CONTINUOUS COVARIATE
• treat: type of treatment, placebo, d1, or d2, column-type CATEGORICAL COVARIATE

We can see on the following figure the number of adverse events on that period providing a global evaluation of the number of adverse events over the population.

One can split by the categorical covariate treat and see if this covariate as an impact on the number of adverse events. As we can see on the following figure, the drugs seem efficient has we notice that the number of adverse event decrease when drug is used.

One can also stratify by the other covariate to have a first idea of the dependencies before the statistical population analysis using Monolix.

In this data set, 111 patients have been administrated a placebo or an active treatment. At randomization and at four visits during the treatment, their respiratory status was determined as being “poor” or “good”, which constitutes the categorical output. Covariates such as center, sex and age were also recorded. The goal was to evaluate the effect of the treatment on the respiratory status.
This data set has been originally published in:

Davis, C. S. (1991). Semi-parametric and non-parametric methods for the analysis of repeated measurements with applications to clinical trials. Statistics in Medicine, 10(12), 1959–80

Below we show a snapshot of the data set:

In MonolixSuite, the output categories must be coded as integers. Thus, we have created the column statusInteger where the respiratory status is coded as 0 for “poor” and 1 for “good”. For individual 1 on placebo, the respiratory status is poor at randomization and remains so during the 4 months. For individual 12 on treatment, the respiratory status is poor at randomization and improves to good during the first three months before deteriorating again to poor at month 4.

The definition of the columns is the following:

• subject: patient identifier, column-type ID.
• month: month after treatment start, column-type TIME
• statusInteger: respiratory status coded as integer, 0 for “poor” and 1 for “good”, column-type OBSERVATION.
• status: respiratory status coded as strings “poor” and “good”, column to be ignored
• treatment: type of treatment, active or placebo, column-type CATEGORICAL COVARIATE.
• sex: sex of the patient, female or name, column-type CATEGORICAL COVARIATE.
• age: age of the patient (in years), column-type CONTINUOUS COVARIATE.
• centre: index of the study center, 1 or 2, column-type CATEGORICAL COVARIATE.

The representation of statusInteger with respect to time is proposed on the following figure

Several points can be noticed:

1. The categories must be coded as integers.
2. There are respiratory status measures for each individual, the month column allows to define at which time the measures were done.
3. ID and TIME column are mandatory. Thus, even when there is only one measurement per individual, an additional column with TIME should be added (full of 0 for example).
4. Covariates must be constant within subjects (or subject-occasions when occasions are defined).
5. In this example, two categories are present (“good” and “poor”), but any number of categories is possible.

When loading this data set into Datxplore, one can easily visualize the number of individuals with “poor” (coded as 0, in dark blue) or “good” (coded as 1, in light blue) respiratory status over time in the case of placebo (left) or active treatment (right):

Based on this figure, it seems that the treatment is efficient a priori. We can additionally look at the other covariates and the impact on the output. One can split by sex as can be seen on the following figure.

In that case, the sex covariate seems not to influence a lot the output.

This data set has been originally published in:

Hedeker D. and Gibbons R.D. (1996) A computer program for mixed-effects ordinal regression analysis. Computer Methods and Programs in Biomedicine 49, 157-176.

These data are from the National Institute of Mental Health Schizophrenia Collaborative Study and are available here. Patients were randomized to receive one of four medications, either placebo or one of three different anti-psychotic drugs. The protocol indicated subjects were to then be evaluated at weeks 0, 1, 3, 6 to assess severity of illness; additionally some measurements were made at weeks 2, 4, and 5. The primary outcome is item 79 on the Inpatient Multidimensional Psychiatric.
Scale which indicates severity of illness. We will analyze imps79o which is an ordinally scaled version of the original variable imps79 which has the following interpretation

Predictor variables of interest are TxDrug a dummy coded variable indicating treatment with drug or placebo. Below is an extract of the data set:

The columns have the following meaning:

• ID: patient identification number, column-type ID
• IMPS: original variable imps79. This  column is ignored as we use an ordinally scaled version of this variable.
• IMPSo: ordinally version of imps79, column-type OBSERVATION.
• TxDrug indicates if there is a treatment or the placebo, column-type CATEGORICAL COVARIATE.
• Week: measurement period, column-type TIME.

One can see on the following figure the evolution of the IMPSo with respect to time on both treated patients and patients with placebo.

This data set has been originally published in:

C. Beata, J. Cordel, N. Marlois (2007). Effect of alpha-casozepine (Zylkene) on Anxiety in Cats, Journal of Veterinary Behavior: Clinical Applications in Research, Vol. 2., Issue 2, pp. 40-46.

The putative effects of a tryptic bovine αs1-casein hydrolysate on anxious disorders in cats was investigated. This product is known as alpha-casozepine and patented under the name of Zylkene (Ingredia, Arras, France). Within veterinary practices, 34 cats were recruited by certified behaviorist surgeons. This 56-day trial against placebo showed the statistically positive effect of this product in the management of anxious disorders such as social phobias in cats. Global score, as well as different items (fear of strangers, contact with familiars, general fears, fear-related aggressions, autonomic disorders), were all significantly improved by the use of this natural decapeptide.

Below we show a snapshot of the data set:

Note that in the MonolixSuite the output categories must be coded as integers. In that cases, observation is a score between 1 and 25. The definition of the columns is the following:

• ID: cat identifier, column-type ID.
• WT_KG: weight of the cat (in kg), column-type CONTINUOUS COVARIATE.
• AGE_M: age of the cat (in month), column-type CONTINUOUS COVARIATE.
• Gender: gender of the cat, Neutered F, Neutered M, or F, column-type CATEGORICAL COVARIATE.
• TRT: type of treatment, Zylkene or placebo, column-type CATEGORICAL COVARIATE.
• TIME: time of the score evaluation, column-type TIME.
• SCORE: global score of emotional state, column-type OBSERVATION.

We can see on the following figure the evolution of all SCORE with respect to time. We see that, when the time increases, the number of cats with a higher score increases too.

To see the impact of the treatment, we can split by the covariate TRT and see what is the difference between the two groups as on the following figure (placebo on the left and treatment on the right). We see that the treatment seems efficient as the SCORE is better with the treatment

We can do the same with the GENDER categorical covariate, we can create two groups the female (associating F and NeuteredF) and the male (NeutredM). On the contrary to the treatment, the GENDER does not seem to impact the SCORE.

Primary Biliary Cirrhosis is a rare but fatal chronic liver disease of unknown cause, with a prevalence of about 50-cases-per-million population. The primary pathologic event appears to be the destruction of interlobular bile ducts, which may be mediated by immunologic mechanisms.
Between January, 1974 and May, 1984, the Mayo Clinic conducted a double-blinded randomized trial in primary biliary cirrhosis of the liver (PBC), comparing the drug D-penicillamine (DPCA) with a placebo. There were 424 patients who met the eligibility criteria seen at the Clinic while the trial was open for patient registration. Both the treating physician and the patient agreed to participate in the randomized trial in 312 of the 424 cases. The date of randomization and a large number of clinical, biochemical, serologic, and histologic parameters were recorded for each of the 312 clinical trial patients. The data from the trial were analyzed in 1986 for presentation in the clinical literature. For that analysis, disease and survival status as of July, 1986, were recorded for as many patients as possible. By that date, 125 of the 312 patients had died, with only 11 not attributable to PBC. Eight patients had been lost to follow up, and 19 had undergone liver transplantation.

The considered data set comes from Counting Processes and Survival Analysis by T. Fleming & D. Harrington, (1991), published by John Wiley & Sons. On the following figure, one could see the survival curve and the mean number of events with respect to time. Notice, that this figure was generated using Datxplore.

In this data set, there are a lot of available covariates

id       = case number
futime   = number of days between registration and the earlier of death,
           transplantion, or study analysis time in July, 1986
status   = 0=alive, 1=liver transplant, 2=dead
drug     = 1= D-penicillamine, 2=placebo
age      = age in days
sex      = 0=male, 1=female
ascites  = presence of ascites: 0=no 1=yes
hepato   = presence of hepatomegaly 0=no 1=yes
spiders  = presence of spiders 0=no 1=yes
edema    = presence of edema 0=no edema and no diuretic therapy for edema;
          .5 = edema present without diuretics, or edema resolved by diuretics;
           1 = edema despite diuretic therapy
bili     = serum bilirubin in mg/dl
chol     = serum cholesterol in mg/dl
albumin  = albumin in gm/dl
copper   = urine copper in ug/day
alk_phos = alkaline phosphatase in U/liter
sgot     = SGOT in U/ml
trig     = triglicerides in mg/dl
platelet = platelets per cubic ml/1000
protime  = prothrombin time in seconds
stage    = histologic stage of disease

On the two following figure, one could see the survival curve with respect to the treatment. Notice, that this figure was generated using Datxplore.

Simplified data set

The data set for subjects 1 and 2 can be defined as follows

ID;TIME;Y;TRT;AGE;SEX;
1;0;0;1;58.7652;1;
1;400;1;1;58.7652;1;
2;0;0;1;56.4463;1;
2;4500;0;1;56.4463;1;

One must indicated the start time of the observation period with Y=0 (at line 1 and 3 for subject 1 and 2 respectively), and the time of event (Y=1) or the time of the end of the observation period if no event has occurred (Y=0). In this simplified data set, subject one had an event at time 400 leading to a line in the data set where Y=1. On the contrary, no event occurred for subject 2. Thus, at the end of the observation (TIME=4500), Y is set to 0.

Oropharynx data set

The following data set provides the data for a part of a large clinical trial carried out by the Radiation Therapy Oncology Group in the United States. The full study included patients with squamous carcinoma of 15 sites in the mouth and throat, with 16 participating institutions, though only data on three sites in the oropharynx reported by the six largest institutions are considered here. Patients entering the study were randomly assigned to one of two treatment groups, radiation therapy alone or radiation therapy together with a chemotherapeutic agent. One objective of the study was to  compare the two treatment policies with respect to patient survival. Approximately 30% of the survival times are censored owing primarily to patients surviving to the time of analysis. Some patients were lost to follow-up because the patient moved or transferred to an institution not participating in the study, though these cases were relatively rare.

The considered data set comes from The Statistical Analysis of Failure Time Data, by JD Kalbfleisch & RL Prentice, (1980), Published by John Wiley & Sons.The data set can be seen here, and the corresponding Datxplore project here (notice that both file should be in the same folder to be correctly linked).

On the following figure, one could see the survival curve and the mean number of events with respect to time. Notice, that this figure was generated using Datxplore.

This study included measurements of many covariates which would be expected to relate to survival experience. Six such variables are given in the data (sex, T staging, N staging, age, general condition, and grade). The site of the primary tumor and possible differences between participating institutions require consideration as well.

CASE          Case Number
INST          Participating Institution
SEX           1=male, 2=female
TX        Treatment: 1=standard, 2=test
GRADE         1=well differentiated, 2=moderately differentiated, 
              3=poorly differentiated,  9=missing
AGE           In years at time of diagnosis
COND          Condition: 1=no disability, 2=restricted work, 3=requires assistance
              with self care, 4=bed confined,  9=missing
SITE          1=faucial arch, 2=tonsillar fossa, 3=posterior pillar,
              4=pharyngeal tongue, 5=posterior wall
T_STAGE       1=primary tumor measuring 2 cm or less in largest diameter,
              2=primary tumor measuring 2 cm to 4 cm in largest diameter with
              minimal infiltration in depth, 3=primary tumor measuring more 
              than 4 cm, 4=massive invasive tumor
N_STAGE       0=no clinical evidence of node metastases, 1=single positive
              node 3 cm or less in diameter, not fixed, 2=single positive
              node more than 3 cm in diameter, not fixed, 3=multiple
              positive nodes or fixed positive nodes 
ENTRY_DT      Date of study entry: Day of year and year, dddyy
STATUS        0=censored,  1=dead
TIME          Survival time in days from day of diagnosis

On the two following figure, one could see the survival curve and the mean number of events with respect to time for two groups, the first groups concerns the subjects younger than 55 years and the other group concerns the other one. Notice, that this figure was generated using Datxplore.

Simplified Oropharynx data set

The data set for subjects 47 and 48 can be defined as follows

ID;INST;SEX;TRT;GRADE;AGE;COND;SITE;T_STAGE;N_STAGE;ENTRY_DT;Y;Time
47;4;1;2;2;49;3;1;4;3;5669;0;0
47;4;1;2;2;49;3;1;4;3;5669;1;74
48;3;1;1;1;44;1;1;3;1;2769;0;0
48;3;1;1;1;44;1;1;3;1;2769;0;1609

One must indicated the start time of the observation period with Y=0 (at line 1 and 3 for subject 47 and 48 respectively), and the time of event (Y=1) or the time of the end of the observation period if no event has occurred (Y=0). In this simplified data set, subject 47 had an event at time 74 leading to a line in the data set where Y=1. On the contrary, no event occurred for subject 48. Thus, at the end of the observation (TIME=1609), Y is set to 0.

In a study conducted by the US Veterans Administration, male patients with advanced inoperable lung cancer were given either a standard therapy or a test chemotherapy. Time to death was recorded for 137 patients, while 9 left the study before death. Various covariates were also documented for each patient.
The primary goal of the study was to assess if the test chemotherapy is beneficial. Secondary goals included the analysis of covariates as prognostic variables.
This data set has been published in D Kalbfleisch and RL Prentice (1980), The Statistical Analysis of Failure Time Data. Wiley, New York. The data set can be seen in Datxplore demos.

A snapshot of the data set in shown below:

The TIME and Y columns are interpreted in the following way: the observation period for individual 1 start at time 0 and the event occurs at time 72 (i.e 72 days after the enrollment). For individual 10, the start time is also 0 and by the end of the observation period for this individual at time 100, no event has yet occurred.

The structure of the data file is the following:

• ID: ID of the patient, column-type ID
• TIME: time of start of the observation period (if Y=0, first occurrence), death (if Y=1) or censoring (if Y=0, second occurrence), column-type TIME.
• Y: 0 to indicate the start of the observation period or censoring and 1 to indicate death, column-type OBSERVATION.
• trt: treatment type, column-type CATEGORICAL COVARIATE
• celltype: histological type of the tumor, categorical covariate, column-type CATEGORICAL COVARIATE
• karno: Karnofsky performance score that describes the overall patients status at the beginning of the study, column-type CONTINUOUS COVARIATE
• diagtime: Time between diagnosis and start of the study (in month), column-type CONTINUOUS COVARIATE
• age: age of the patient (in years), column-type CONTINUOUS COVARIATE
• priortherapy: indicates if the patient has received another therapy before the current one, column-type CATEGORICAL COVARIATE

Using Datxplore, one can visualize the Kaplan-Meier curve. The censored data are indicated by red points.

The North Central Cancer Treatment Group (NCCTG) data set records the survival of patients with advanced lung cancer, together with assessments of the patients performance status measured either by the physician and by the patients themselves. The goal of the study was to determine whether patients self-assessment could provide prognostic information complementary to the physician’s assessment. The data set contains 228 patients, including 63 patients that are right censored (patients that left the study before their death).

This data set has been originally presented and analyzed in Loprinzi et al. (1994). Prospective evaluation of prognostic variables from patient-completed questionnaires. North Central Cancer Treatment Group. Journal of Clinical Oncology : Official Journal of the American Society of Clinical Oncology, 12(3), 601–607. The data set can be downloaded in Datxplore demos.

A snapshot of the data set is displayed below:

The observation period for individual 1 start at 0 and the death event is observed at time 306. On the opposite, individual 3 left the study at time 1010, before his death.

The meaning of the columns is the following:

• ID: ID of the patient, column-type ID
• TIME: time of start of the observation period (if Y=0, first occurrence), death (if Y=1) or censoring (if Y=0, second occurrence), column-type TIME.
• Y: 0 to indicate the start of the observation period or censoring and 1 to indicate death, column-type OBSERVATION.
• age: age of the patient (years), column-type CONTINUOUS COVARIATE
• sex: sex of the patient (F for female, M for male), column-type CATEGORICAL COVARIATE
• ecogPH: ECOG (Eastern Cooperative Oncology Group) performance status assessed by the physician, on a scale from 0 (fully active) to 5 (dead). For information on the scale, click here, column-type CATEGORICAL COVARIATE
• karnoPH: Karnofsky performance status, assessed by the physician, on a scale from 0 (dead) to 100 (completely healthy). More details about the scale can be found here, column-type CONTINUOUS COVARIATE.
• karnoPAT: Karnofsky performance status, assessed by the patient, column-type CONTINUOUS COVARIATE

Using Datxplore, one can visualize the Kaplan-Meier kurve. The censored data are indicated by red points.

Data come from the 1991 Arizona cardiovascular patient files. A subset of the fields was selected to model the differential length of stay for patients entering the hospital to receive one of two standard cardiovascular procedures: CABG and PTCA. CABG is the standard acronym for Coronary Artery Bypass Graft, where the flow of blood in a diseased or blocked coronary artery or vein has been grafted to bypass the diseased sections. PTCA, or Percutaneous Transluminal Coronary Angioplasty, is a method of placing a balloon in a blocked coronary artery to open it to blood flow. It is a much less severe method of treatment for those having coronary blockage, with a corresponding reduction in risk.

Below we show a snapshot of the data set:

The definition of the columns is the following:

• ID: patient identifier, column-type ID
• los: time in days when the patient goes out of the hospital, column-type TIME
• procedure: procedure used, 1 or 0 (1 for CABG and 0 for PTCA), column-type CATEGORICAL COVARIATE
• sex: sex of the patient, 1 or 0 (1 for Male and 0 for female), column-type CATEGORICAL COVARIATE
• admit: type of admission, 1 or 0 (1 for Urgent/Emergency and  0 for elective), column-type CATEGORICAL COVARIATE
• age75: is the subject’s age over 75 years, column-type CATEGORICAL COVARIATE
• hospital: string describing the hospital, column-type CATEGORICAL COVARIATE
• Y: event type (0 to enter in the hospital, 1 when the event ‘The subject leaves the hospital’ happens), column-type OBSERVATION

The representation of the Keiplan-Meier curve with respect to time is presenter below.

Warfarin data set

This data set has been originally published in:

O’Reilly (1968). Studies on coumarin anticoagulant drugs. Initiation of warfarin therapy without a loading dose. Circulation 1968, 38:169-177.

Warfarin is an anticoagulant normally used in the prevention of thrombosis and thromboembolism, the formation of blood clots in the blood vessels and their migration elsewhere in the body, respectively. The data set provides set of plasma warfarin concentrations and Prothrombin Complex Response in thirty normal subjects after a single loading dose. A single large loading dose of warfarin sodium, 1.5 mg/kg of body weight, was administered orally to all subjects. Measurements were made each 12 or 24h.
On the two following figure, one could see the concentration and the effect with respect to time for all subjects.

The data set for subject one can be defined as follows

id time    amt dv  dvid    wt  age sex
1   0   100 .   1   66.7    50  1
1   0   .   100 2   66.7    50  1
1   24  .   9.2 1   66.7    50  1
1   24  .   49  2   66.7    50  1
1   36  .   8.5 1   66.7    50  1
1   36  .   32  2   66.7    50  1
1   48  .   6.4 1   66.7    50  1
1   48  .   26  2   66.7    50  1
1   72  .   4.8 1   66.7    50  1
1   72  .   22  2   66.7    50  1
1   96  .   3.1 1   66.7    50  1
1   96  .   28  2   66.7    50  1
1   120 .   2.5 1   66.7    50  1
1   120 .   33  2   66.7    50  1

Interpretation

One can see the following columns

• id: the subject ID, column-type ID
• time: the time of the measurement or of the dose, column-type TIME.
• amt: the amount of drug provided to this subject, column-type AMOUNT.
• dv: the measurement, column-type OBSERVATION.
• dvid: the type of measurement. In this study, one has two measurement, the concentration measurement (corresponding to the PK dynamics), and the Prothrombin Complex Response (corresponding to the PD-part), column-type OBSERVATION ID.
• wt: Weight of the subject, column-type CONTINUOUS COVARIATE.
• age: Age of the subject, column-type CONTINUOUS COVARIATE.
• sex: Sex of the subject, column-type CATEGORICAL COVARIATE.

Several points can be noticed.

1. The first line corresponds to a dose, while the other ones are measurements. This explains the dot in the CONC column for the first line and the dots in the AMT column for the other ones.
2. The covariates columns (the continuous wt and the categorical covariates age and sex) are filled with the same values. Even though it is not necessary, we encourage the user to fill the columns for readability and usage reasons.
3. In the presented case, both PK and PD measurements are at the same time, this is not required for data exploration using Datxplore, nor parameter estimation using Monolix.
4. Finally, notice that no initial washout is needed at the beginning as by default, the null initial condition is used for parameter estimation.

Interestingly, one can display the Effect with respect to the Concentration in order to have an idea on how to model the interaction between the PD and the PK part.

Then, the response does not seem to be direct. Notice that, as the observation times are no the same between the PK and the PD, interpolation is made to propose this kind of plot. One can also focus on one individual in particular as on the following figure

Notice that we also propose a red arrow to describe the evolution of time.

This data set has been originally published in:

Desmée, S, Mentré, F, Veyrat-Follet, C, Sébastien, B, Guedj, J (2017). Using the SAEM algorithm for mechanistic joint models characterizing the relationship between nonlinear PSA kinetics and survival in prostate cancer patients. Biometrics, 73, 1:305-312.

It contains PSA kinetics and survival data for 400 men with metastatic Castration-Resistant Prostate Cancer (mCRPC) treated with docetaxel and prednisone, the first-line reference chemotherapy, which constituted the control arm of a phase 3 clinical trial. In this context of advanced disease, the incidence of death is high and the PSA kinetics is closely monitored after treatment initiation to rapidly detect a breakthrough in PSA and propose rescue strategies. In more details:

• PSA kinetics: 6627 PSA measurements were collected, among which roughly 20% were pretreatment, 60% on treatment, and 20%posttreatment. 2.5% are below the limit of quantification (LoQ),set at 0.1 ng.ml⁻¹.
• survival: 286 patients deceased (71.5%), leading to a median survival of 656 days.

PSA measurements are displayed on the figure below. Since the data density is too high to see clearly, the next figure is a selection of six individuals, that allows to identify the shape of PSA measurements followed by most individuals: a decrease of PSA concentration after the treatment initiation at time zero, followed by an increase some time later due to resistance.

The following figure shows the Kaplan-Meier curves for the survival data split in two groups by the median time of end of treatment

Below is an extract of the data set file:

The columns are:

• TIME: the time of the measurement or of the dose, column-type TIME.
• ID: the subject ID, column-type ID.
• Y: measurements of PSA concentration in ng.ml⁻¹, or death events, column-type OBSERVATION.
• CENS: CENS=1 indicates values below the limit of quantification (LoQ), column-type CENSORING.
• YTYPE: the type of measurement. There are two measurement types in this data set: the PSA concentration measurement (corresponding to the PD), and death events, column-type OBSERVATION ID.
• TIME_ENDtr: day of end of treatment, column-type CONTINUOUS COVARIATE.

Evolution

• What are the evolution in this version compared to the previous version (2016R1)? All the evolution can be found here.
• Can I get the documentation for the data set associated with the 2016R1 version? Of course, you can download it here.

Questions about format

• Which file formats are supported? Text and comma-separated values file are allowed. The file extension should preferably be .txt or .csv.
• Should I have a header line? Yes, having a header line is mandatory.
• Are there restrictions on header names? No, there is no limitation in terms of names nor on character number. However, some characters are not allowed as in the rest of the data file (see here).
• Which column types are mandatory? The ID, and OBSERVATION column-types are mandatory. All others are optional.
• Which column-types are possible? The complete list of supported column-types can be found here.
• Which separators are allowed? The supported separators are comma (“,”), semicolon (“;”), space (” “), and tab (“\t”).
• Which characters are allowed in strings? The list of allowed characters can be found here.
• What does “.” mean? The “.” can be used in almost all the lines of the data set but has several meaning depending on the context. A summary can be found here.
• How can I ignore some response-lines of my data set? Use IGNORED OBSERVATION=1 for that.
• How can I ignore some dose-lines of my data set? Use EVENT ID=2
• Can I specify time in hour or in days? Yes, all the possible formats are defined here.
• Can the data be split into several files (for instance one file for dosing and one for observations)? No. All the data must be grouped into a single file.

Questions about units

• How are units handled? Units are free but must be consistent. For instance TIME, INFUSION RATE, INFUSION DURATION, INTERDOSE INTERVAL must have the same TIME units. With models from the libraries, no unit conversion is done. Thus, if in the data set TIME is in hours, rate constant parameters will be /hours. If in the data set the AMOUNT is in mmol and the concentration in mM, then the volume parameter will be in L.
• Is it possible to automatically convert units? No.
• Are the units visible in the graphical user interface of Monolix? No.

Questions about format difference with NONMEM

• What are the differences between Monolix and Nonmem in terms of data set? The few differences are listed here.
• What is the equivalent of the NONMEM CMT column? Depending on the usage of the CMT column, it can correspond to the OBSERVATION ID column-type, or the ADMINISTRATION ID column-type. All differences between NONMEM and the MonolixSuite are listed here.

Questions about subjects and occasions

• Must all lines corresponding to the same individual be grouped? No, this is not necessary. All lines with the same ID will be assigned to the same individual, whatever their order or grouping.
• How can I define occasions? For that, you can use the OCCASION column-type as explained here.

Questions about time

• Must the times be in ascending order? For a given individual, the times do not need to be in order. The sorting will be done automatically.
• Can I specify time in hour or in days? Yes, all the possible formats are defined here.
• Can time have negative values? Yes.
• For time-to-event data, do I have to indicate the start time? Yes, it must be explicitly stated, for instance with TIME=0 and OBSERVATION=0. Guidelines for data set formatting for time-to-event data are given here.

Questions about responses and observations

• Are non-continuous data types (such as count, time-to-event and categorical data) supported? Yes. Exemples of data set for non-continuous data types are presented here.
• Which value should I enter in the OBSERVATION column-type for BLQ values? In the OBSERVATION column-type, give the limit of quantification (LOQ). To mark the observations as being BLQ, use the CENSORED column-type. To indicate a censoring interval, use the LIMIT column-type in addition.
• Can my data set contain different types of observations? Yes, use the OBSERVATION ID column to define to which type of data the line corresponds. An example data set with different types of observations is presented here.
• What happen if I define both a dose and a response in the same line? Depending on the values, it can be a dose, a response. To see all the configurations, see here.

Questions about dose regimen

• How are steady-state doses handled? In case of a steady-state dose, 5 additional doses are added before the steady-state dose, in order to reach steady-state. More details can be found here.
• What happen if I define both a dose and a response in the same line? Depending on the values, it can be a dose, a response. To see all the configurations, see here.
• For dose-lines, should I specify the compartment into which the dose is introduced? No. In the MonolixSuite, the matching between the data (dose and observation lines) and the model (administrations and predictions) is done using identifiers, not based on compartment numbers. To assign a dose to a specific administration of the model (oral or iv macros for classical PK models, depot macro for more complex ODEs), the column ADMINISTRATION ID is used. The identifier in the ADMINISTRATION ID column should match the “adm=” field of the macro.
• If I have several outputs, should I duplicate the dosing information? No.
• If a dose is split in two absorption routes, should I duplicate the dosing information? No. The same dose line can be split in different fractions using the bioavaila

Questions about covariates

• Can I have time-varying covariates? Continuous (CONTINUOUS COVARIATE) and categorical (CATEGORICAL COVARIATE) covariates must be contant within a subject-occasion. If a continuous covariate varies with respect to time, the first value in time will be used for the entire subject-occasion. Time-varying continuous covariates can be tagged as regressors (column-type REGRESSOR) to be used as such. Examples are proposed here.

Questions about controls and events

• How can I ignore certain response-lines of my data set? Use IGNORED OBSERVATION=1 for that.
• Are the MDV and EVID columns necessary? These columns are not mandatory and most of the time not necessary.
• How can I define a time at which I which the output the predictions, even if I have no observation? No, use Simulx for simulations.

The required format for the data set in NONMEM and in the Monolix Suite is very similar. Usually only few changes (if any) are required to go from one format to the other one.

General formatting

• Column names: in the Monolix Suite column names are not restricted in length, and not restricted to uppercase format. Special characters such as spaces ” “, stars “*”, parentheses or brackets “(“, dashes “-“, slashes “/” are supported but are replaced by “_” in the interface and results.
• Header line: no need to start the header line with the “#” character in the Monolix Suite, the column headers line will be recognized automatically.
• Number of columns: there is no limitation of the number of columns in the Monolix Suite

Dose column-types

• STEADY STATE column: When a data set contains a column with column-type STEADY STATE (formerly SS), there must be a column with column-type INTERDOSE INTERVAL (formerly I)I. If STEADY STATE>0, then the value in the INTERDOSE INTERVAL column must be strictly positive. In case of steady-state, steady-state formulas are not used. Instead, additional doses (5 by default) are added before the STEADY STATE dose to reach steady-state.
• INFUSION RATE and INFUSION DURATION: in case of an infusion, in the Monolix Suite, it is possible to define either the rate (INFUSION RATE column-type, formerly RATE) or the duration (INFUSION DURATION column-type, formerly TINF). The rate and the duration are related to each other via the amount: TINF=RATE/AMT. Negative values in the RATE column-type result in a bolus, when used in combination with the iv macro (and models from the library with iv). When used in combination with the oral macro (and models from the library with oral0 or oral1), the RATE column is ignored if the value is negative and an error is triggered if the value is positive. If infusion duration is defined in the model (parameter or fixed value), the RATE column is not necessary (in opposition to NONMEM, where RATE=-1 and RATE=-2 are used).
• CMT column: in NONMEM, for observation-lines, CMT specifies the compartment from which the predicted value of the observation is obtained. For dose-lines, CMT specifies the compartment into which the dose is introduced. In the MonolixSuite, the matching between the data (dose and observation lines) and the model (administrations and predictions) is done using identifiers, not based on compartment numbers. To assign a dose to a specific administration of the model (oral or iv macros for classical PK models, depot macro for more complex ODEs), the column ADMINISTRATION ID (formerly ADM) is used. The identifier in the ADMINISTRATION ID column should match the “adm=” field of the macro. To assign an observation to a prediction, the column OBSERVATION ID (formerly YTYPE) is used. Observation lines with OBSERVATION ID=1 will be assigned to the first output (output = {…} statement in the model file), lines with OBSERVATION ID=2 to the second output, etc. Note that the default values for the administration id in administration macros or in the pkmodel macro is adm=1. Similarly, in case of a single output, OBSERVATION ID=1 by default (while in NONMEM, the central compartment may have number 1 or 2). In the ADMINISTRATION ID column-type, negative values are not allowed. Turning off compartments should instead be defined in the model file.

Control and event columns-types

• EVID column-type: in the Monolix Suite, the EVENT ID (formerly EVID) column is not mandatory, since dose-events (EVENT ID=1) and response-events (EVENT ID=0) are automatically recognized. The Monolix Suite also recognizes EVENT ID=2 (“Other event”), EVID=3 (“Reset event”), and EVID=4 (which corresponds to a reset to initial values immediately followed by a dose). EVID=4 creates a new occasion for the individual. In NONMEM, EVID=2 is sometimes used to define a time point at which one would like to predict a concentration, without having an observation. In the Monolix Suite, no prediction will be outputted for that time in the output files.
• MDV column-type: the IGNORED OBSERVATION (MDV) column is not mandatory in the Monolix Suite. Dose-lines and observation-lines will be recognized automatically based on their contents. Yet the IGNORED OBSERVATION column can be useful to force a response-line to be ignored (IGNORED OBSERVATION=1). Several IGNORED OBSERVATION columns are allowed, in this case a synthetic IGNORED OBSERVATION value is computed. In the Monolix Suite, IGNORED OBSERVATION can in addition take the value IGNORED OBSERVATION=2, which is identical to IGNORED OBSERVATION = 1. Note that no prediction will be made at that time point in the output files. Simulx can be used to obtain predictions from a model at different time points.

Response column-types

• Censored data: in the Monolix Suite, censored data should be tagged in the data set using additional columns with CENSORING (formerly CENS) to mark censored observation, and if necessary LIMIT (give other interval boundary) column-types. The LOQ value is indicated in the OBSERVATION column. Censored data are then automatically taken into account in the likelihood in a rigorous statistical way. If only the CENSORING column is used, the method in the MonolisSuite is equivalent to the so-called M3 method. When both CENSORING and LIMIT are used, the method in equivalent to M4.

Subject identification columns-types

• ID column-type: in NONMEM all lines related to a single individual must be in one block, which is not the case in the Monolix Suite. If the ID column contains the following IDs: [1,1,1,2,2,1,1], NONMEM will consider that the dataset comprise three individuals with IDs 1 (with 3 observations), 2 (with 2 observations) and 1_1 (with 2 observations). In the Monolix Suite, two individuals are considered, with IDs 1 (with 5 observations) and 2 (with 2 observations).

Time column-types

• TIME column-type: values in the time column can be negative in the Monolix Suite.

Covariates and regression column-types

• Covariates: in the Monolix Suite, columns corresponding to continuous covariates must be set to the CONTINUOUS COVARIATE (formerly COV) column-type, and categorical covariates to the CATEGORICAL COVARIATE (formerly CAT) column-type.
• Regression variables: in the Monolix Suite, regression variables must be set to the REGRESSOR (formerly X) column-type. If several regression variables are used, their order must be the same in the dataset and in the “input” field of the model file. Interpolation between two regressor values is done using “last observation carried forward” in Monolix, while it is “next observation carried backward” in Nonmem. When converting a Nonmem dataset to Monolix format, the time-varying regressor columns must be shifted one cell up for each individual.
  

Unsupported column-types

• The PCMT, CONT, CALL, MRG_, RAW_, RPT_, L1, and L2 column-types are not supported in the MonolixSuite.