1.Overview
Version 2023
This documentation is for Simulx.
©Lixoft
Simulx GUI – easy, efficient and flexible application for clinical trial simulations
Now, more than ever, to increase drug success rate and accelerate clinical development it is important to incorporate new technology – like clinical trials simulators. They improve the quality and efficiency of decision making process. Modeling&simulation approach models molecules and mechanisms from the available data and then uses these models to generate new information that can optimize your strategies in terms of time, money and commercial success.
What if it were possible to:
- Use your estimated model and, investigating new dosing regimens and populations, gain unique insights that improve your chances of success?
- Avoid costly surprises by simulating easily different scenarios with a flexible and user-friendly interface?
- Utilize the outputs from simulations to optimize your clinical trial strategies that reduces drug development cycle?
It is possible to do this, and more, with Simulx GUI!
Simulx is an advanced simulation software interconnected with Monolix and flexible in building user-designed scenarios. This application combines a user-friendly interface with the highest computational capabilities to help you make faster and more informed decisions.
Simulx has three sections that create an optimal environment to build and analyse simulations:
-
- Definition – create easily new exploration and simulation elements of different types.
- Exploration – explore different treatments and effects of model parameters on a typical individual.
- Simulation – simulate a clinical trial using a population of individuals in one or several groups with specific treatment or features and use flexible post-processing tools, clear results and interactive plots for analysis.
How does it work?
Start with:
play:
- add new dosing regimens, parameters, covariates, outputs, etc.
- explore effects of model parameters and treatments
- combine defined elements into a desired simulation with one or several groups for comparison
- create outcomes&endpoints to quantify the simulations outputs
- start immediately the analysis and decision process using automatically generated results and plots
and customize:
- plots: add analysis features, stratify data and modify plotting area look
- interface: use dark theme and increase font size and numbers precision
- data: save user files in the result folder
- export: data, plots and settings
1.1.Import a project from Monolix
There are three methods to start a project in Simulx: create a new project, open an existing project and import a project from Monolix or PKanalix. To import a project from Monolix is as simple as clicking on the button “Import from Monolix” in the Simulx home tab. It is the easiest way to build a simulation scenario, because everything to run a simulation is prepared automatically. As a result, it saves a lot of time.You can always modify current simulation elements, define new ones and change the scenario, so the flexibility of Simulx is not compromised.
1. Simulx project structure with “Import from Monolix”
2. A typical simulation workflow with a project imported from Monolix
Simulx project structure
Importing a project from Monolix creates a Simulx project with pre-defined elements. You can use them to re-simulate the dataset from the Monolix project or as a base for a new simulation scenario. These elements appear in the Definition tab:
- Model, population parameters and individual parameters estimates and output variables are imported from Monolix.
- Occasions, covariates, treatments and regressors are imported from the dataset (used in the imported Monolix project).
Simulx sets default exploration and simulation scenarios – they are ready to run. They contain one exploration group to simulate a typical individual (in the exploration tab) and one simulation group to re-simulate the Monolix project (in the simulation tab).
Default simulation elements
- model: mlxtran model with blocks [INDIVIDUAL], [COVARIATE] and [LONGITUDINAL].
- pop.params.:
- mlx_PopInit [no POP.PARAM task results]: (vector) initial values of the population parameters from Monolix.
- mlx_Pop: (vector) population parameters estimated by Monolix.
- mlx_PopUncertainSA (resp. mlx_PopUncertainLin): (matrix) an element which enables to sample population parameters using the covariance matrix of the estimates computed by Monolix if the Standard Error task (Estimation of the Fisher Information matrix) was performed by stochastic approximation (resp. by linearization). To sample several population parameter sets, this element needs to be used with replicates.
- indiv.params.:
- mlx_IndivInit [no POP.PARAM task results]: (vector) initial values of the population parameters from Monolix.
- mlx_PopIndiv: (vector) population parameters estimated by Monolix.
- mlx_PopIndivCov: (table) population parameters with the impact of the covariates used in the model (but no random effects).
- mlx_EBEs: (table) EBEs (conditional mode) estimated by Monolix.
- mlx_CondMean: (table) conditional mean estimated by Monolix.
- mlx_CondDistSample: (table) one sample of the conditional distribution (first replicate in Monolix).
- covariates [if used in the model]:
- mlx_Cov: (table) ids and covariates read from the dataset.
- mlx_CovDist: (distribution) distribution of covariates from the dataset with empirical mean and variance for continuous covariates, set as lognormal for positive continuous covariates, normal for continuous covariate with some negative values, and multinomial low based on frequencies of modalities for categorical covariates.
- treatment:
- mlx_AdmID: (table) ids, amounts and dosing times (+ tinf/rate or washouts) read from the dataset for each administration type.
- outputs:
- mlx_observationName: (table) ids and measurement times read from the dataset for each output of the observation model
- mlx_predictionName: (vector) uniform time grid with 250 points on the same time interval as the observations for each continuous output of the structural model.
- mlx_TableName: (vector) uniform time grid with 250 points on the same time interval as the observations for each variable of the structural model defined as table in the OUTPUT block.
- occasions:
- mlx_Occ [if used in the model]: (table) ids, times and occ(s) read from the dataset.
- regressors:
- mlx_Reg [if used in the model]: (table) ids, times and regressor values and names read from the dataset.
Default exploration and simulation scenarios
Exploration:
- Indiv.params: mlx_IndivInit or mlx_PopIndiv.
- Treatment: one exploration group with mlx_AdmId for all administration IDs.
- Output: mlx_predictionName for all predictions defined in the model.
Simulation:
- Size: number of individuals read from the dataset.
- Parameters: mlx_PopInit or mlx_Pop.
- Treatment: mlx_AdmId for all administration IDs.
- Output: mlx_observationName for all observations.
- Covariates: mlx_cov if used in the model.
- Regressor: mlx_reg if used in the model.
Interface allows to have an overview on all defined elements, modify them and create new ones as well as build simulation scenarios. But, if you modify the imported model, then Simulx will remove all simulation elements. In addition, if you remove occasions, then all occasion-dependent simulation elements will be removed as well.
A typical simulation workflow with a project imported from Monolix
The projects shown here are available as demo projects in the interface “1.overview – importFromMonolix_xxx.smlx”:
This example is based on a PK-PD model for Warfarin developed and estimated in Monolix. The Warfarin dataset contains concentration and PCA(%) measurements for 32 individuals, who received different oral doses of the drug. Firstly, the goal of the Simulx project is to use the information from the Monolix project to test the efficacy and safety conditions for different treatments. Secondly, to simulate clinical trials and compare various dosing regimens strategies. Simulations should answer the following questions:
- Which “loading dose” strategy assures a rapid steady state without a concentration peak?
- Do multi-dose treatments meet the efficacy and safety criteria?
- What is the uncertainty of the percentage of individuals in a target due to the variability between individuals and due to the size of a trial group?
Model:
The PK model includes an administration with a first order absorption and a lag time. It has one compartment and a linear elimination. The PD model is an indirect turnover model with inhibition of the production. All individual parameters have log-normal distribution besides the Imax parameter, which is logitNormally distributed. In addition, the log-transformed scaled weight covariate explains intra-individual variability of the volume, age covariate has an effect on the clearance and sex covariate on the baseline response. Finally, the combined-1 error model is used in the observation model of the concentration, and the constant model of the response.
0. Re-simulation of the Monolix project
[Demo project “1.overview – importFromMonolix_resimulateProject.smlx”]
You can download the Monolix project for this example, here. To import it in SImulx, first unzip the folder, then start a Simulx session, click on “Import from: Monolix” and browse the .mlxtran file. After importing a project from Monolix, the task buttons “simulation” and “run” in the Simulation tab re-simulate the project. Plots and results are generated automatically. Results are tables for outputs and individual parameters and plots display model observations as individual outputs and distributions.
1. Exploration of the loading dose strategies
[Demo project “1.overview – importFromMonolix_compareTreatments.smlx”]
Exploration tab simulates a typical individual. After importing a project from Monolix (the same as in the previous example), you can choose different types of individual parameters elements, eg. equal to population parameters estimated by Monolix or EBEs. Using several exploration groups allows to compare different treatments in one chart. The goal of this example is to test how many days of a “loading dose” are necessary to reach a steady state without a peak of the concentration. Starting dosing regimens are:
- 1 day with a load dose 12mg OD followed by 13 days with a 6mg single dose OD
- 1 day with a load dose 12mg OD followed by 13 days with a 4mg single dose OD
- 1 day with load doses 4mg twice a day (BID) followed by 26 doses of 2mg every 12 hours.
“Loading dose” treatments elements are of manual type (with time of a dose and amount), while multi-dose elements are of regular type. Regular type includes a specification of a treatment period, inter-dose interval and number of doses. You combine treatments elements directly in the exploration tab (in the left panel).
Output is the concentration prediction Cc and the response prediction R on a regular time grid over the whole treatment period (t = 0:1:336) . The plot displays one subplot per output, and all exploration groups (=dosing regimen) together on each subplot. In the right panel, you can edit treatment elements and parameters interactively – predictions are updated on-the-fly for all groups to help you find which exact regimen is the most promising.
2. Treatment comparison: percentage of individuals in the target
[Demo project “1.overview – importFromMonolix_compareTreatments.smlx”]
Simulation scenario
Exploration tab performed simulation on one individual. In the simulation tab, Simulx simulates a population of individuals. SImulation outputs can be further post-processed to calculate, for example, the percentage of individuals in the target for different treatment arms. This simulation scenario uses the following treatment and output elements.
- BID treatment: One day of a “loading dose” with 4mg or 6mg dose twice a day (BID), followed by 26 doses of 2mg or 3 mg respectively each 12 hours.
- OD treatment: One day of a “loading dose” with 8mg or 12mg dose once a day (OD), followed by 13 doses of 4mg or 6 mg respectively each 24 hours.
- Outputs: manual type using model predictions (Cc and R) at time equal 336h.
In the simulation tab, the button “plus” adds a new group and “arrows” (green frames below) move elements from the shared section to the group specific section. For treatment, each group has a specific combination of treatments (blue frame). In addition, the option “same individuals among groups” removes the effect of intra-individual variability between individuals (red frame). As a consequence, the observed differences between groups are only due to the treatment and simulation can use a smaller number of individuals.
The comparison between groups is in terms of the percentage of individuals in the efficacy and safety target:
- Efficacy: PCA at the end of the treatment should be less than 60%.
- Safety: Ctrough on the last treatment day should be less than 2ug/mL.
You can calculate it in the outcomes&endpoints section of the simulation tab. Definition of new outcomes includes selecting an output computed in the simulation scenario and post-processing methods. When you apply threshold condition, then outcome is of a binary (true/false) type.
In addition, outcomes can be combined together (blue frame below), and an endpoint summarizes “true” outcomes over all individuals in groups.
Analysis
Similarly to the task button “Simulation”, which runs the simulation, the “Outcomes & endpoint” button performs post-processing, which in this example means calculating the efficacy and safety criteria and the number of individuals in the target. When you run this task, SImulx generates automatically the results in the “endpoint” section and plots for outcomes distributions.
In this example, the outcome distribution compares the number of individuals in the target between groups. The highest number of “true” outcomes is in the group with the low level dose twice a day (gr_BID_lowDose). Failure to satisfy the safety criteria by the two groups with the high dose level causes large numbers of “false” outcomes. In fact, the endpoint results show that for these two groups less than half of the individuals have Ctrough below the safety threshold (blue frame below).
3. Clinical trial simulation and uncertainty of the results
[Demo project “1.overview – importFromMonolix_clinicalTrial.smlx”]
The previous step shows that the high dose level violates the safety criteria in more than 50% of individuals. Therefore, the simulation of a clinical trial uses only one dose level with the BID and OD administration.
The goal is to analyse the effect of the uncertainty due to the variability between individuals, measurement errors and number of individuals in a trial.
New simulation scenario has four groups which combine different dosing regimens (BID or OD) with different group sizes (30 or 100). Outputs are model observations at the end of the treatment. To simulates the scenario several times (green frames), use the option “replicates”. As a result, the endpoints summarize the outcomes not only over the groups but also over the replicates.
[Starting from the demo project “1.overview – compareTreatments.smlx”, change number of replicates to 100, and add two groups: one with treatment as for GR_BID, other as GR_OD. Move “number of ids” as group specific, and set N=30 for one BID-OD pair and N=100 for the other. Change names to indicate group sizes.]
After running both tasks, plots display the endpoint distribution as a box plot with the mean value (dashed line) and standard deviations for each group. As expected, the uncertainty is lower for trial with more individuals. However, the mean values remain at similar levels.
“Group comparison” option in the Outcomes&endpoints section compares the endpoints values across groups (blue frame). Selecting different reference groups and hypothesis (through the odds ratio) allows to change the objectives. Moreover, calculation of new outcomes or endpoints do not require re-running a simulation because the post-processing is a separate task.
The statistical test checks if any of the dosing regimens, BID or OD, is better than the other. Firstly, in the smaller trial so the gr_BID_N30 group is the reference and the hypothesis states that the odds ratio is different from one. For each replicate, if the p-value is lower than selected 0.05, then a test group (GR_OD_N30) is a “success”. Results summary in the “group comparison” section shows that only 5% of the test group replicates are successful (upper image below), which suggests that OD dosing regimen is not significantly better than BID. Larger trial size might give different results. Change reference group to gr_BID_N100 and re-run the outcomes & endpoints task. Percentage of successful replicates for gr_OD_N100 is higher, 8%, (lower image below), but it is comparable to the previous result.
4. Propagation of parameter uncertainty to the predictions
[Demo project in 2021 version only “1.overview – importFromMonolix_clinicalTrial_uncertainty.smlx”]
In the previous step, we replicated the study 100 times to check the impact of sampling different individuals on the endpoint, and on the power of the study. For all these replicates, we sampled individuals using the same population parameters (so same typical values and deviations of random effects).
The goal of this final step is to check the impact of the uncertainty of population parameter estimates on the final endpoint and study power. For this, starting from the 2021 version, it is possible to use the population parameter element mlx_PopUncertainSA (resp. mlx_PopUncertainLin) if standard errors have been computed by stochastic approximation in the original Monolix project (resp. by linearization). Now the 100 replicates will be samples using each time different population parameter values, which are sampled from the variance-covariance matrix of the estimates imported from Monolix.
When running again simulation and outcomes with this population parameter element, we obtain a higher uncertainty on the endpoint than in step 3, since now we observe in addition the uncertainty related to the estimation of parameters in Monolix.
1.2.New project from scratch
New possibilities, as well as unexpected and unwanted effects, arise during different phases of drugs development. Simulx allows to create a new project from scratch, which gives freedom in simulating new scenarios. Moreover, it creates easily a space for testing new hypothesis. This helps to explore the full potential of drugs, and better prepare for their possible failures.
To create a new project from scratch:
- Select “New project” after opening the Simulx.
- Browse, or write new, mlxtran model (see here for details about the model structure).
- Use Definition tab to specify simulation elements required by the model. Explore in the Exploration tab the effects of treatments and parameters. Build a simulation scenario in the Simulation tab and run the simulation.
Demo project: 1.overview/newProject_TMDDmodel
The following example shows how to build “from scratch” a simulation that aims at comparing different treatments among two populations: healthy volunteers and patients with rheumatoid arthritis. It uses a TMDD model for a ligand and receptor concentrations. In addition, the synthesis of the receptor depends on the population type – lower for healthy subjects. All simulation elements are user-defined. The basic assumption is that a treatment is effective if the free receptor stays below 10% of the baseline. The goal is to test if the dose levels effective on healthy volunteers allow rheumatoid arthritis patients to reach the efficiency target.
Model
When building a project from scratch, loading a model is mandatory and has to be done in the first place. It sets automatically the structure of a simulation based on the model type and its elements.
- Structural model is a TMDD model with the QE approximation, two compartments and oral administration.
- Statistical model defines an effect of the patient state (healthy or with RA) on the synthesis rate of the receptor. It also includes the power law relationship between the weight covariate and the volume of the central compartment.
Covariates and their transformations are described in the [COVARIATE] block, the statistical model of the individual parameters is in the [INDIVIDUAL] block, while the [LONGITUDINAL] block contains the structural model with output definitions.
Definition of the scenario elements:
To guide building a project from scratch, Simulx defines default simulation elements automatically using information from the loaded model. These elements can be removed or modified, as well as new elements can be created. In this example, the definition includes the following new elements used in the exploration and simulation.
- Pop.Param.: Values come from an external table with at least two mandatory rows. The first row contains names of all population parameters as used in the model, while the second has the parameter values.
- Indiv.Params.: Individual parameters appear in the exploration tab. In this example, they are equal to population parameters in order to explore the effect of parameters on the model predictions for a typical individual.
- Covariates: The aim of this simulation is to compare two populations (healthy and with rheumatoid arthritis). There are two covariate elements with different values of the “patient” covariate, but the same “weight” covariate.
- Treatment has two cycles (green frame). In each cycle patients receive an oral dose scaled by their weight (blue frame) once per day for 7 days (red frame) followed by 7 days without a treatment. Three different dose levels: 3mg/kg, 6mg/kg and 12mg/kg require three separate treatment elements . An option “duplicate” allows to clone a treatment, and then change only the name and the amount. Note that the “View” option has the scaling formula.
- Outputs elements include the ratio between the free receptor and the baseline. This output on the regular grid is useful in the exploration. Simulation uses only the value at the end of the treatment. The latter choice speeds up the computations in case of many individuals and/or replicates.
Exploration
The model assumes that rheumatoid arthritis disease affects the synthesis of the free receptor (ksyn parameter). It means that for a certain dose level the efficacy target can be reached by healthy individuals (ksyn_pop = 0.789, dashed reference curve in the figure below), but not by patients with rheumatoid arthritis (ksyn_pop = 2.8, solid curve). In this exploration, the scaling of the amount 3mg/kg corresponds to typical individual with a weight 70kg (blue frame).
Simulation
The scenario consists of 6 groups for three dose levels and two populations, see here to learn about creating a simulation scenario.
- Treatment is group specific. Each group uses one of the three covariate dependent doses: 3mg/kg, 6mg/kg or 12mg/kg (green frame).
- Type of a population – healthy or with the rheumatoid arthritis – is in the group specific covariate (blue frame).
- Group size, population parameters and the output are the same for all groups.
The outcomes&endpoints section defines post-processing of the simulation outputs for post-processing, which helps to compare the groups. The main endpoint is the percentage of individuals reaching the efficacy target in each group. It summarizes the “true” outcomes, which correspond to the situation when the ratio between the free receptor and the baseline at the end of the treatment is less then 10% (green frame). In addition, the “group comparison” (blue frame) compares the endpoints of all groups with respect to the reference group (healthy population with 3mg/kg dose level).
Results
To run the simulation and the calculation of the endpoints it is enough to select both tasks and click the button “Run”. Generation of the results and plots is automatic in two dedicated tabs. The outcome distribution shows that the efficacy of the treatment in healthy individuals stays above 90% (red line) for all dose levels. On the contrary, a group with rheumatoid arthritis achieves this level only at the highest tested dose.
The response at the lowest dose level by healthy individuals is the reference. Group comparison considers a test group a “success” if the odds ratio of “percentage true” is larger then 0.6. Only the highest dose level satisfies this criterion for unhealthy patients.
2.Definition
Exploration or simulation scenarios are build from elements, such as model, parameters, treatments etc. Definition tab, as the name suggests, allows to create these simulation elements through user-friendly and flexible methods. Moreover, it displays them is dedicated sections, which gives a clear overview of the project status. Definition of the following simulation elements is available (click on any of them to see the full description):
- Model
- Occasions
- Population parameters
- Individual parameters
- Covariates
- Treatments
- Outputs
- Regressors
Each element, imported from Monolix or used-defined, is a table , vector
or a distribution
. These icons next to the element name inform about the type when you hover on it with a cursor (green frame). Elements can be displayed, edited, duplicated (besides tables) or deleted (red frame). To create a new element, go to a dedicated section and click the “plus” button (blue frame).
Model is a mandatory element. It has to be loaded as first, because only elements present in the model can be defined. Otherwise, the section is greyed out and unavailable, for instance “regressors” (blue arrow at the bottom). Of course, more then one element of each category is possible.
After importing a project from Monolix, all elements are automatically created using Monolix model, results and dataset, see the list of elements here. In a new project written from scratch, Simulx generates default elements based on the loaded model to guide building new ones.
2.1.Model
A single model must be defined in each Simulx project. This model is used both in Exploration and Simulation. Loading or reloading a model deletes all definition elements to avoid incompatibilities between previously defined elements and the new model.
- Model sections:
- [LONGITUDINAL]
- [INDIVIDUAL]
- [COVARIATE]
- Loading or modifying a model
- Model imported from Monolix
- Additional lines
Model sections
The model includes different sections:
- [LONGITUDINAL] (mandatory)
This section contains the structural model. All variables of the model can be defined as outputs of the simulation.
Details on the syntax to define the structural model is here.
This section can include the definition of random variables in a block DEFINITION:, such as a random event or a variable with residual error.
- [INDIVIDUAL] (optional)
If the model considers the inter-individual variability, then definitions of models for individual parameters are in [LONGITUDINAL]. The inputs of [INDIVIDUAL] are population parameters and covariates involved in covariate effects.
Example: Parameters Tlag, ka, V and Cl are described with lognormal distributions, effects of covariates SEX and logtAGE are included on Tlag and Cl, respectively, and there is a correlation between eta_V and eta_Cl:
[INDIVIDUAL] input = {Tlag_pop, ka_pop, omega_ka, V_pop, omega_V, Cl_pop, omega_Cl, F_pop, omega_F, corr_V_Cl, logtAGE, beta_Cl_logtAGE, SEX, beta_Tlag_SEX_M} SEX = {type=categorical, categories={F, M}} DEFINITION: Tlag = {distribution=logNormal, typical=Tlag_pop, covariate=SEX, coefficient={0, beta_Tlag_SEX_M}, no-variability} ka = {distribution=logNormal, typical=ka_pop, sd=omega_ka} V = {distribution=logNormal, typical=V_pop, sd=omega_V} Cl = {distribution=logNormal, typical=Cl_pop, covariate=logtAGE, coefficient=beta_Cl_logtAGE, sd=omega_Cl} F = {distribution=logitNormal, typical=F_pop, sd=omega_F} correlation = {level=id, r(V, Cl)=corr_V_Cl}
More details on the syntax in this section is here.
- [COVARIATE] (optional)
If covariates are used in the model of individual parameters, then they should be defined in a block [COVARIATE]. This block contains the list of inputs (covariates used in the model) and the definition of categories for categorical covariates. It can also include transformations of the covariates, in a section EQUATION: for continuous covariates and in a section DEFINITION: for categorical covariates. All the covariates defined in this block (transformed or not) can be then used in the block [INDIVIDUAL].
Example: There are 3 covariates AGE, RACE and SEX. The covariate AGE is transformed into logtAGE, RACE is transformed into tRACE.
[COVARIATE] input = {AGE, RACE, SEX} RACE = {type=categorical, categories={Asian, Black, White}} SEX = {type=categorical, categories={F, M}} EQUATION: logtAGE = log(AGE/35) DEFINITION: tRACE = { transform = RACE, categories = { G_Asian = Asian, G_Black_White = {Black, White} }, reference = G_Black_White }
More details on the syntax in this section is here.
Note that in Simulx it is not possible to define covariates as distributions within the block [COVARIATE] with a section DEFINITION:. However, the covariate distributions can be defined in the tab Definition in the interface of Simulx.
Loading or modifying a model
Several buttons are available on the top of the page to load or modify a model:
- Browse: to load a new model file by browsing if from the computer.
- Load from library: to load a model from the built-in libraries. Note that all models from the libraries contain only structural models ([LONGITUDINAL] block) with no individual models for the parameters or covariates.
- Reload: to reload the same model after modifying it using the built-in editor or with any text editor.
- Open in editor: to opens the current model in the built-in editor.
Loading or updating a model with the buttons “Browse”, “Load from library” or “Reload” deletes all definition elements to avoid incompatibilities with previously defined elements and the new model.
Model imported from Monolix
When importing a model from Monolix, the model that appears in the interface of Monolix comes from two sources:
- The structural model ([LONGITUDINAL] block) used in the Monolix project, copied in a new file stored in the result folder of the Simulx project, in a subfolder names ModelFile/.
- The [INDIVIDUAL] and (if there are covariates in the model) [COVARIATE] blocks, derived from the statistical model set up in Monolix, saved directly in the .smlx file.
Warning: When opening a model in the editor with “Open in editor”, only the new structural model file is opened for modifications. If this model is changed and reloaded, it will replace the two model sources mentioned above. It means that the [INDIVIDUAL] and [COVARIATE] blocks are removed. To keep these blocks in the modified model, they have to be pasted in the file together with the [LONGITUDINAL] block.
Additional lines
Below a model definition, there is a field to write additional lines, which are included “on the fly” in the model. This is convenient for example to use variables for simulations that are not defined in the Mlxtran model code, such as the AUC, a change from baseline, or the survival function (see example below). The model file itself is not modified, the additional lines are saved in the .smlx file.
By default, the additional lines are added in a new section EQUATION: below the structural model. In order to add additional lines in the PK block, it is necessary to add “PK:” at the beginning of the additional lines. This is convenient to add a new route of administration, using the iv(), oral() or depot() macro for instance. If this new administration depends on a parameter (e.g the absorption rate ka), the parameter needs to be fixed in the additional lines. It cannot be added to the input parameter list. It is not possible to add additional lines in the [INDIVIDUAL] or [COVARIATE] blocks.
This function is available also with lixoftConnectors functions: setAddLines() and getAddLines(), see here for more details.
Warning: When using “import from Monolix”, “additional lines” fields can (sometimes) be unavailable. In this case, open the Monolix project in Monolix and use “Export to Simulx”. This problem has been fixed in the 2021R1 version.
In the example below, a oral absortion route in added to the demo TMDD_exploration.smlx, which originally had only iv:
2.2.Occasions
Occasions definition. When the model to simulate contains inter-occasion variability (ie variability between different periods of measurements within the same individual), you should define a single element Occasions. Like for the model, and contrary to the other simulation elements, it is not possible to define several occasion elements to choose from for the simulation.
Demo projects: 3.7. occasions
All other defined elements must be compatible with the structure of occasions.
Common occasions for all subjects
In the interface, it is possible to define a common structure of occasions applied to all simulated subjects. This structure can contain one or several levels of occasions, and one or several occasions per subject.
After defining such common occasion structure, other common elements (parameters, covariates, treatments, outputs and regressors of type “manual” or “regular”) can be defined occasion-wise thanks to a dedicated toggle “occasion-wise values”, as on this example screenshot for covariates:
Moreover, elements defined as external tables may contain one or several columns to assign different values to different subject-occasions.
Subject-specific occasions
To define subject-specific occasions use an external file containing a table with columns ID, time and one or several columns for the occasions. The header names for these columns are free and are used by Simulx. The external file separator can be tab, comma or semicolon. The possible file extensions are .csv or .txt.
Below is an example of the occasions element defined after loading the external table (on the left).
After defining such subject-specific occasion structure, other elements (parameters, covariates, treatments, outputs and regressors) must be common over subjects (type “manual”, “regular” or “distribution”), or can be defined with occasion-wise values as external tables only, with the same occasion structure.
Occasions imported from Monolix
Upon import of a Monolix run, Simulx creates an occasion element with the individual structure of occasions from the Monolix data set.
- mlx_subjects: a table containing the occasions and their starting times for each individual. The table has at least 3 columns: id, time, occ. Additional columns may be present in case of several levels of occasions.
Rules for simulating occasions
- Occasions are not simulated in Exploration: only the first occasion from the selected subject is simulated.
- If occasions are not defined, inter-occasion variability is not taken into account for the simulation of individual parameters.
- From the 2023 version on, the sampling of individual parameters takes into account the inter-occasion variability if one or several occasions are defined. In previous versions (2020 and 2021), if the structure of occasions contains a single occasion for some subject, then the simulation of individual parameters for this subject does not take into account inter-occasion variability.
- When an occasion element has been defined, in case of several replicates, the sampling method has to be ‘Keep Order’.
Occasions in outcomes, results and plots
Occasions are indicated as additional columns in the table of individual parameters. In the plots of individual outputs, occasions are highlighted as dashed yellow lines on hover of one the occasions from the same subject. Furthermore, all plots of results can be stratified by occasions.
When occasions are defined, the definition of outcomes can be made by post-processing the simulation outputs by subject (one outcome value per individual) or by subject-occasion (one outcome value for each occasion of each individual). When the post-processing by subject-occasion is selected, the occasion column(s) appear(s) also in the corresponding outcome table.
2.3.Population parameters
Definition of population parameters as simulation elements allows to simulate individual parameters from probability distributions. In the mlxtran model they are:
- [INDIVIDUAL] block input parameters that are neither inputs nor outputs of the block [COVARIATE].
- [LONGITUDINAL] block input parameters that are neither individual parameters nor regressors.
POP.PARAM section in the “Definition” tab is available only if the list of population parameters from the model is not empty.
Demo projects: 3.3. population parameters
Overview
In the “Population parameters” tab, elements created automatically after a “new project” or an “import from Monolix/PKanalix” and elements created by the user are shown.
The buttons on the right allow to do the following actions:
- VIEW: display the content of the element (the value of the population parameters)
- EDIT: modify the content of the element. Note: the elements “mlx_PopUncertainSA”, “mlx_PopUncertainLin”, “mlx_TypicalUncertainSA”, and “mlx_TypicalUncertainLin” represent multidimentional distributions and cannot be edited.
- DUPLICATE: open a pop-up window for a new element with the same content as the previous element. Note: the elements “mlx_PopUncertainSA”, “mlx_PopUncertainLin”, “mlx_TypicalUncertainSA”, and “mlx_TypicalUncertainLin” cannot be duplicated. Elements based on external files can also not be duplicated.
- DELETE: delete the element. When the deleted element is based on an external file located in <result folder>/ExternalFiles, the file itself is also deleted upon save.
- CREATE NEW INDIV: creates a new element “individual parameters” from the population parameters fixed effects (e.g V = V_pop). This option is available for population elements of type “manual” only.
New population parameters element
After loading a model, Simulx generates automatically a default population parameter element. It is a table with parameters names from the model and all entries equal to one. It helps to create a new element by just modifying the values. Clicking the button “plus” adds a new population parameter, which may be one of the three types.
- Manual: It is a vector and has one value for each parameter.
- Distribution: Parameters are a distribution law – normal, lognormal (default), logitnormal, uniform – with a typical value and a standard deviation. If the distribution is lognormal or logitnormal, sd is the standard deviation of the distribution in the Gaussian space. The typical value is the median of the population parameter distribution. In the case of a lognormal distribution, in order to get the sd \(s_G\) of the distribution in the Gaussian space given a typical value of the lognormally distributed covariate \(\mu\), or given its mean \(m\), and given its sd \(s\), you can use the following formulae:\[s_G = \sqrt{\ln\Big(1+\Big(\frac{s}{m}\Big)^2\Big)} = \sqrt{\ln\Bigg(1+\sqrt{1+4\Big(\frac{s}{\mu}\Big)^2}\Bigg) – \ln(2)}\]Both formulae are equivalent if \(\frac{s}{\mu}<<1\) (in that case \(\mu \approx m\)).
- External: It is a file with a table that has each population parameter in a separate column.
The external file can have only one column header different from the population parameters names. It indicates replicates (eg. from bootstrap or simpopmlx). All individual parameters of the same replicate come from the same population distribution.
Population parameters imported from Monolix
Demo projects: 1.overview/importFromMonolix … .smlx
Importing a Monolix project generates automatically a population parameter element with values from the Monolix result folder.
- mlx_Pop contains population parameters estimated by Monolix if the POP.PARAM task results are available.
- mlx_PopInit contains initial estimates of the population parameters if the mlx_pop does not exist.
- mlx_Typical (NEW since 2023 version) is the same as mlx_Pop but with all standard deviations of random effects (omega parameters) set to 0. It enables to simulate a typical individual in terms of parameters (no unexplained variability), and still include non-typical covariates in the simulation. The variability in the sampled individual parameters will come only from sampling different covariate values. To see how this element can be used in practice, check the demo project 1.overview/importFromMonolix_CovEffectOnTypical.smlx.
mlx_Pop, mlx_PopInit and mlx_Typical are vectors (single set of population parameters). If replicates are used in the Simulation tab, with these elements, the same set of poplation parameters will be used for all replicates.
- mlx_PopUncertainSA (resp. mlx_PopUncertainLin) enables to sample population parameters using the variance-covariance matrix of the estimates computed by Monolix if the Standard Error task (Estimation of the Fisher Information matrix) was performed by stochastic approximation (resp. by linearization). To sample several population parameter sets, this element needs to be used with replicates. In the interface, the element is displayed with a reminder of the estimated values and RSEs next to the variance-covariance matrix which is used to generate new samples.
The displayed variance-covariance matrix and the sampling is done in the gaussian space (i.e we sample {log(V_pop), log(Cl_pop), omega_V, omega_Cl, b} from a multivariate normal distribution, if V and Cl have a lognormal distribution). The sampled values are then converted to the non-gaussian space.
This element cannot be modified nor duplicated.
- mlx_TypicalUncertainSA (resp. mlx_PopUncertainLin, NEW since 2023 version) is another population parameter element with the variance-covariance matrix of population parameter values estimated in Monolix. The only difference to the previous mlx_PopUncertainSA/Lin is that it has standard deviations of random effects (omega parameters) set to 0. It enables to simulate a typical individual with different typical parameter values for each replicate, such that the uncertainty of parameters is propagated to the predictions. To sample several parameter sets, this element needs to be used with replicates. To see how this element can be used in practice, check the demo project 1.overview/importFromMonolix_UncertaintyOnTypical.smlx.
In the following video we apply uncertainty on fixed effects only (with version 2021). With the 2023 version, the steps performed outside of the interface in this video can all be replaced by simply selecting the new element mlx_TypicalUncertain.
2.4.Individual parameters
In the mlxtran model, the following parameters are recognized as individual parameters:
- Only the [LONGITUDINAL] block is present: all parameters of the input list, except those defined as regressors.
- Both the [LONGITUDINAL] and [INDIVIDUAL] blocks are present: parameters defined in the DEFINITION section of the [INDIVIDUAL] block.
Individual parameters can be used in the tab “Exploration” and “Simulation”. An individual parameter definition is either a vector, which has one value per parameter, or a table, where each line correspond to a value of a different individual.
Demo projects: 3.4. individual parameters
Overview
In the “Invidual parameters” tab, elements created automatically after a “new project” or an “import from Monolix/PKanalix” and elements created by the user are shown.
The buttons on the right allow to do the following actions:
- VIEW: display the content of the element (the value of the individual parameters)
- EDIT: modify the content of the element.
- DUPLICATE: open a pop-up window for a new element with the same content as the previous element. Note: elements based on external files cannot be duplicated.
- DELETE: delete the element. When the deleted element is based on an external file located in <result folder>/ExternalFiles, the file itself is also deleted upon save.
- CREATE NEW POP: creates a new element “population parameters” from the individual parameters (e.g V_pop = V). The betas (covariate effects), omegas (standard deviation of the random effects), correlation and error parameters are set to zero. This option is available for individual elements of type “manual” only, which contain a single set of individual parameters.
New individual parameters elements
After loading a model, Simulx generates automatically a default individual parameter element called “IndivParameters” with all values set to 1. This element can be modified (button EDIT). New elements can be created with the button “+”. Two different types of individual parameter elements are available:
- Manual: One value per parameter to type in. The required parameters are automatically listed.
- External: An external text file with either:
- A single row and one column per parameter. The headers must correspond to the parameter names.
- Several rows, a first column with header “id”, occasion columns (optional) and one column per parameter. The headers must correspond to the parameter names, and to the occasion names if applicable.
- A single row and one column per parameter. The headers must correspond to the parameter names.
The external file can be tab, comma or semicolon separated. Available file extension are: .csv or .txt.
Individual parameters elements imported from Monolix
Upon import of a Monolix run, several individual parameters elements are created automatically:
- mlx_IndivInit: [when POP.PARAM task has not run]a vector of individual parameters corresponding to the initial values of the population parameters in Monolix, i.e with covariate betas and random effects set to zero. For instance, \( V=V_{pop,ini} \)
- mlx_PopIndiv: [when POP.PARAM task has run]a vector of individual parameters corresponding to the population parameters estimated by Monolix, i.e with covariate betas and random effects set to zero. For instance, \( V=V_{pop,est} \)
- mlx_PopIndivCov: [when POP.PARAM task has run and covariates are defined in the Monolix data set]a table of individual parameters corresponding to the population parameters and the impact of the covariates, but random effects set to zero. For instance, \( V=V_{pop} \times \left( \frac{WT}{70} \right) ^{\beta_{V,WT}} \)
- mlx_EBEs: [when EBEs task has run] a table of individual parameters corresponding to the EBEs (conditional mode) estimated by Monolix (as displayed in Monolix Results > Indiv. param > Cond. mode.)
- mlx_CondMean: [when COND. DISTRIB. task has run] a table of individual parameters corresponding to the conditional mean estimated by Monolix (as displayed in in Monolix Results > Indiv. param > Cond. mean.)
- mlx_CondDistSample: [when COND. DISTRIB. task has run] a table of individual parameters corresponding to one sample of the conditional distribution (first replicate of the Monolix result file IndividualParameters/simulatedIndividualParameters.txt).
2.5.Covariates
Values to use for simulation should be defined for covariates used in the statistical model, if the simulation is based on population parameters. In this case, new individual parameters are simulated from the population distributions and the covariate values. Several covariate elements can be defined in Definition, but only one covariate element should be used per simulation group in Simulation. No covariate element can be used in Exploration, since only individual parameters are used in Exploration.
Demo projects: 3.2. covariates
New covariate element
Several types of covariate elements can be defined:
- Manual: It is a vector that has one or several dosing times with identical or different amounts. The + and – buttons allow to add and remove doses.
- Distribution: The covariates are described with distribution laws. When this type of element is used for simulation, new covariate values are simuated from the distributions. For continuous covariates, the distribution can be normal, lognormal or logitnormal with a mean and sd, or uniform with two interval limits. If the distribution is lognormal or logitnormal, sd is the standard deviation of the distribution in the Gaussian space. The typical value is the median of the covariate distribution..
In the case of a lognormal distribution, in order to get the sd \(s_G\) of the distribution in the Gaussian space given a typical value of the lognormally distributed covariate \(\mu\), or given its mean \(m\), and given its sd \(s\), you can use the following formulas:
\[s_G = \sqrt{\ln\Big(1+\Big(\frac{s}{m}\Big)^2\Big)} = \sqrt{\ln\Bigg(1+\sqrt{1+4\Big(\frac{s}{\mu}\Big)^2}\Bigg) – \ln(2)}\]
Both formulas are equivalent if \(\frac{s}{\mu}<<1\) (in that case \(\mu \approx m\)).
For categorical covariates, the probability for each category can be defined in [0,1]. The sum of probabilities over all categories must be 1, and an “auto fill” option allows to automatically fill one or several of the categories to satisfy this rule.
- External: An external text file with columns id (optional), occasions (optional), and one column per covariate (mandatory). The occasions headers must correspond to the occasion names defined in the occasion element. When id and occasion columns are present, then they must be the first columns. When the id column is not present, the covariate is considered ‘common’, i.e the same for all individuals. Categorical covariate values must correspond to the categories defined in the model (block [COVARIATE]).The external file can be tab, comma or semicolon separated. The possible file extensions are .csv or .txt.
Covariate elements imported from Monolix
Importing a Monolix project generates automatically a covariate element based on the Monolix data set.
- mlx_Cov: contains covariate information for each individual. The table is saved as external table in the result folder of the project. This table contains a column id, and one column per covariate. If there are occasions in the Monolix project, it also contains one or several columns for the occasion levels.
- mlx_CovDist: element of type “distribution” with typical values, standard deviations and probabilities calculated on the individuals of the Monolix project. No correlation between the covariates is assumed. In the 2020 version, all continuous covariates are assumed to follow a normal distribution. In the 2021 version, continuous covariates having only strictly positive values in the Monolix data set are assumed to follow a log-normal distribution, and the others are set with a normal distribution.
2.6.Treatments
Treatments definition includes times and amounts of the doses applied to the model. Treatments are applied to the model via the macros depot(), iv() or oral() used in the model. Moreover, treatments definition has an administration id, which allows to choose to which macros used in the model the doses are applied.
When used in “Exploration” or “Simulation“, several treatment elements can be combined together. For instance, a loading dose of type manual followed by maintenance doses of type regular, or a oral dose with adm=2 and an iv dose with adm=1.
The units of time and amounts must be consistent with the units of the Monolix data set or with the model definition when starting from scratch.
Demo projects: 3.1. treatments
New treatments element
Several types of elements can be defined:
- Regular: It is used for regularly spaced dosing times with a unique amount and a unique infusion duration or rate (optional). It requires the start time, inter-dose internal, number of doses, and amount.
- Manual: It is a vector that has one or several dosing times with identical or different amounts. The + and – buttons allow to add and remove doses.
- External: An external text file with columns id (optional), occasions (optional), time (mandatory), amount (mandatory), tinf or rate (optional), washout (optional). The occasions headers must correspond to the occasion names defined in the occasion element. When id and occasion columns are present, then they must be the first columns. When the id column is not present, the treatment is considered ‘common’, i.e the same for all individuals. The washout column can contain zeros (no washout) or ones (washout).
The external file can be tab, comma or semicolon separated. The possible file extensions are .csv or .txt.
Additional treatments definition specifications:
- adm: [all] the administration id of the treatment element (integer). The doses of a treatment element with adm=2 apply to all model macros defined with adm=2, for instance
oral(adm=2, ka)
. Macros used in the model without adm are implicitly defined with adm=1.
- infusion duration or rate: [regular/manual] the list button on the right allows to display the infusion column. The value is understood as either a duration or a rate, depending on the chosen option.
- washout: [manual] the list button on the right allows to display the washout column. When the washout tick-box is selected, a washout is applied just before the dose. A washout means that all model variables are reset to their initial values.
- repeat: [regular/manual] This option allows to repeat a base pattern of doses several times (number of repetitions), with a given periodicity (cycle duration). In the example below, the dose is given on the three first days of the week, for 4 weeks. The doses on the first week are defined using the type ‘regular’ with three doses and an inter-dose interval of 1 day. This base pattern is then repeated every 7 days (cycle duration), 3 times (number of repetitions) in addition to the first week.
- scale amount by a covariate: [regular/manual] This option allows to personalize the dose given to different individuals by scaling the dose amount with the selected covariate and with a specific intercept for the linear relationship: \(\text{Scaled amount} = \text{Amount} \times \text{Selected covariate} + \text{Intercept}\).
- non-compliance probability: [all] The doses defined are applied to the model with a given probability (1-p) , where p is the probability to miss a dose. This allows to simulate non-adherence to a treatment. Which doses are applied and which are not rely on the random number seed defined in the project settings to ensure reproducibility.
Treatment elements imported from Monolix
Importing a Monolix project generates automatically a treatment element for each administration id defined in the Monolix data set.
- mlx_AdmX: contains treatment information for admID=X for each individual including: dosing times, amount, infusion duration or rates (optional) and washouts (optional, from EVID=3 or EVID=4 in Monolix). The Monolix data set column SS is replaced by additional dose lines as defined by the Monolix setting “number of steady-state doses”. The ADDL column is also replaced by additional dose lines.
2.7.Outputs
Outputs of simulations are variables from the longitudinal model of continuous, discrete or event type. There are two outputs groups:
- Main outputs
- Model predictions defined in the structural model as the “output” (eg. Cc).
- Observations (model predictions with an error model) defined in the observation model (eg. y1).
- All variables defined in the structural model as “tables” (eg. AUC).
- Intermediate outputs
- Variables computed in the structural model and not listed as an “output” or “table” in the OUTPUT block (eg. amount in the peripheral compartment, time varying clearance).
- Regressors.
- Variables defined with the “additional lines” in the model definition.
Loading a model automatically generates the “main outputs”. Model predictions and tables are on a default time grid. If a project is built from scratch, then model observations use also the default time grid. Otherwise, in case of project imported from Monolix, they are on a grid given by the measurement times from the Monolix dataset.
Projects: 3.5.outputs, 7.noncontinuous_outputs
New output element
Outputs correspond to output variables, which can be written or selected from the list (green frame).
It is possible to have different outputs of the same variable. For example, one output shows the time evolution over a treatment period and another gives a value at the end of treatment to define an endpoint. However, charts display these outputs on one plot with merged time grids.
There are three output types.
- Regular: It is a vector on a regular time grid (start time, step, final time, (occ)) common for all subjects.
- Manual: It is a vector with manually defined list of time points (use “space” to separate them) common for all subjects.
- External: It is a file with a table that has: a mandatory column “time” for time points, an optional column “id” (in the absence of the “id” column the time grid is equal for all subjects), and an optional column “occ” for occasions.
Occasions
By default, the regular and manual output types apply to all subject-occasions. If occasions are common among all individuals, then an option “occasion-wise values” is available. In this case each occasion has a separate time grid.
Time-to-event outputs
Time limits (start time and final time) define the observation period during which the survival curve is computed. The final time thus defines the censoring time. Intermediate times are ignored. The time grid must be the same for all individuals. If an external file is provided with different start and end values for each individual, the events will be simulated on the same observation period for all individuals, using the min(start time) and max(end time) over all individuals.
Outputs imported from Monolix
Importing a Monolix project generates automatically output elements for the “main output” variables.
- mlx_observationName (eg. mlx_y1, mlx_y2): For each output of the observation model it is a table with ids and observation times corresponding to the measurements read from the dataset.
- mlx_predictionName (eg. mlx_Cc, mlx_R): For each continuous output of the structural model it is a vector with a uniform time grid with 250 points on the same time interval as the observations.
- mlx_TableName: For each variable of the structural model defined as table in the OUTPUT section it is a vector with a uniform time grid with 250 points on the same time interval as the observations.
2.8.Regressors
Definition of regressors elements is available only if the mlxtran model used in a Simulx project uses it. In this case, specification of regressors is mandatory. All regressors used in a model are displayed in one element as separate columns.
Regressors names
- If a Monolix project was imported, then regressors names come from a dataset – headers of columns tagged as regressor.
- When building a project from scratch, regressor names are equal to names used in a model.
Demo projects: 3.6.regressors
Create new regressors element
There are two types of regressor elements:
- Manual: It is a vector with manually defined time points and values, which are common for all individuals.
Example: parameter – covariate relationship with the covariate as a regressor
- External: Regressors definition is a table with the following mandatory columns: “time” for time points and “regressor_name” for regressor values. Optionally, it can have a column “id”. In the absence of the “id” column, the time grid is equal for all individuals and occasions (if defined in the model).
Example: PK-PD model with PK measurements as a regressor
Regressors imported from Monolix
Importing a Monolix project generates automatically regressors element with regressors names from the dataset:
- mlx_Reg: contains Ids, times and regressors values read from the dataset. Occasions are included if any.
3.Exploration
The Exploration tab is the second tab in the interface of Simulx. It simulates a typical individual to explore a model by interactively changing treatments and model parameters.
- Simulate a single individual
- Compare treatments using exploration groups
- Display any non-random model variable as prediction output
- Interactivity: impact of parameters and dosing regimen on the model dynamics
- Define new parameter or treatment elements
- Add observed data in the plot
- Select elements for Simulation of clinical trials
- Plots settings
- Export the plots as images
Predicted individual
In Exploration, the predictions are based on only:
- one set of individual parameters (mandatory),
- one or several treatments (optional) for one individual,
- one or several outputs (mandatory) with a single vector of measurement times per output,
- one set of regressor values, only if regressors are present in the model (mandatory).
These elements are selected in the left panel.
Thus an element of type “Individual parameters” must be selected, and it is not possible to select an element of type “Population parameters“.
If a selected element is a table containing several sets of individual values, then the first row in the table is selected by default, and the “ID” field on top of the plot in the middle allows to select the row in the table corresponding to a particular ID.
[Demo: 1.overview/importFromMonolix_resimulateProject.smlx]
This field is highlighted on the figure below, corresponding to a project that comes from a Monolix project imported into Simulx:
-
- the individual parameters come from the table mlx_EBEs contains the EBEs estimates,
- the treatment mlx_Adm1 contains the individual doses imported from the dataset used in Monolix,
- the output mlx_Cc contains a single vector of regular measurement times for Cc, the structural model output.
Thus changing the “ID” value will change the row read from the two tables mlx_EBEs and mlx_Adm1.
Exploration groups
- 3.exploration/PK_exploration.smlx
Treatment can contain several elements in different exploration groups (explorationGroup1 and explorationGroup2 below), or combined within an exploration group (as in the explorationGroup2 below). Each exploration group produces a separate prediction. If an exploration group contains several treatments, then the prediction corresponds to the treatments given together to the same individual.
In the demo shown below, there are two exploration groups: the first corresponds to the treatment element singleDose_150, while the second corresponds to the combination of loadingDose_100 and multipleDoses_50. Two prediction curves in different colors represent these two exploration groups in the plot.
Exploration outputs
- 3.exploration/TMDD_exploration.smlx
Only non-random element of type “Output” can be selected in Exploration, thus they should:
-
- correspond to continuous variables (consequently excluding time-to-event, categorical or count variables)
- not include a residual error model in their definition.
By default, there is a separate plot for each selected output, as shown below. This can be changed in the exploration settings, where it is possible to select variables to display at each chart. If the scenario contains several output elements based on the same variable (but on a different grid), then they are plotted on the same plot with merged grids.
Interactive modification of parameter values or dosing regimen
- 3.exploration/PK_exploration.smlx
The right panel of the Exploration tab has three sub-tabs: PARAMETERS, SETTINGS and DATA OVERLAY. The parameter values and dosing regimens can be modified there to explore in real-time their impact on the model dynamics.
The figure below shows the PARAMETERS sub-tab with the model parameters (Parameters) and treatment parameters (Treatment) sections (highlighted in blue). The parameter values can be changed via the small arrows, sliders or by entering new values with the keyboard. The “reset” button resets parameters to their initial values, while the “new” button
generates a new element (individual parameters element or treatment element) using the current values. On the plot, the solid curves correspond to the current predictions, while reference curves, added with the button
, are shown as dashed lines.
Reference curves. In the figure below, the section “Treatment” – highlighted in green – shows the elements from the treatment element: multipleDoses_50. All its parameters, such as start time, inter-dose interval, number of doses and dose amount can be modified. Current values can be set as a reference by clicking on the button – highlighted in purple. The reference curves are listed on the right panel – highlighter in blue – and are represented by dashed lines in the plot.
Several reference curves can be created and each successive one is displayed with a corresponding number. The icon restores the reference parameters values, and
removes the reference curve from the list and from the plot. Hovering on a reference line (#1 in the figure below) highlights in yellow the corresponding reference curve, as seen in the figure below. Stroke dash-array defines the pattern of dashes and gaps of a curve.
Defining new parameter or treatment elements
- 3.exploration/PK_exploration.smlx
Exploration allows to create new elements from the current values by clicking on the icon . In the parameter section it creates the Individual parameters element, while in the treatment section it creates the Treatment element.
A window to define a new element opens automatically. For the parameters, the individual parameter element is of type “manual” and by default replaces the previously selected element in the Exploration scenario. Untick the corresponding checkbox (blue mark in the figure below) to only define a new element – without the replacement.
A new treatment element can be set as a regular or manual type – depending on the definition in the exploration. By default it replaces the treatment element used in the exploration, but it can be also added as the new treatment to a new exploration group.
Overlay of the observed data
Continuous data can be overlaid on the prediction plots.
Load
Data overlay sub-tab in the Exploration tab allows to load a data file. Click on the BROWSE button and select a file. It has to be a Monolix compatible dataset and has to contain columns that correspond to: subject identifier (tag: ID), time of observations (tag: TIME) and observation values (tag: OBSERVATION). It is possible to have multiple observations to be displayed in different charts. In this case, the loaded datafile need to contain the column with observation id to distinguish different observations.
![]() |
![]() |
After tagging columns, click on the ACCEPT button to load the data file. Displayed observations can be filtered (green frame) using categorical covariates present and correctly tagged in the loaded file. In the figure below, ticked box next to a value “0” means that in the plot there are only observations for individuals with SEX = 0. To change the tagging, click on the VIEW/EDIT button (blue frame).
When a Simulx project is build by importing a Monolix project, then the dataset – used in the Monolix project – is set automatically in the DATA OVERLAY sub-tab.
Display
Observed data are displayed automatically as “dots” if there is only one output in the Exploration scenario and the data file contains only one observation type. Otherwise – in case of several different outputs or multiple observations types – data display has to be selected in the SETTINGS sub-tab.
In the data – charts grid, see the figure below, observation data are listed in rows. Numerical order is applied if the observation identifiers in the data file are integers, eg. data_1, data_2, …; or alphabetical order if the observation identifiers are strings, eg. data_PD, data_PD, as in the figure below. Charts are in columns. To display data on a chart, click on the drop-down menu of in the appropriate grid cell and select “dots” or “lines”.
Link to individual selection
If any of the exploration scenario elements contains a table with several individuals, then the simulated individual can be selected in the PARAMETERS sub-tab, see individual prediction description section for details. To link the observed data to the selected individual, enable the toggle “Link to individual selection”. Only data corresponding to the selected individual will be displayed on charts. The option “Link to individual selection” only appears if the list of ids found in the data set and in the elements selected for the simulation are the same.
It is also possible to display one or several individuals selected from the dataset, which may or may not be linked to the simulated individual. This option is available in the DATA OVERLAY sub-tab, in the “Selection” section. In the example below, selection contains a range of IDs between 15 and 42 and only observed data corresponding to these individuals are overlaid on the chart.
Sending elements to simulation
The button “Send elements to simulation” sends all elements selected in the Exploration to the scenario definition in the tab Simulation. Exploration groups are turned into simulation groups with a default size of 1 individual per group.
Plots settings
The panel “Settings” can be used to control plots features, such as the scale of the curves displayed on each plot and axis limits. The x-axis is common for all charts, while the y-axis can be specified independently for each chart.
In the following figure, two variables Cc and E are displayed on separate charts. They have the same x-axis limits – blue frame. The y-axis is specified for each chart: user limits 0-60 on the chart – 1, and automatic limits on the chart – 2 – green frame.
Exporting plots
The “export” button on top of the plots can be used to save the plots as an image in the result folder. Two image formats are available: PNG and SVG (Scalable Vector Graphics).
4.Simulation
The main goal of Simulx is to perform simulations of clinical trials. In other words, it simulates a population of individuals, in one or several groups, using different scenarios. It gives the last step of the modeling&simulation workflow, after model building in Monolix for instance.
There are two tasks in the simulation tab: SIMULATION that generates outputs, and OUTCOMES & ENDPOINTS – a post-processing task – that uses the simulation outputs to calculate outcomes (one per individual) and endpoints (summary over all individuals of a group). In addition, running the tasks produces and immediate feedback thanks to the automatically generated RESULTS and PLOTS.
Simulations of clinical trials include:
- Simulation scenario – Building a simulation scenario takes place in the dedicated section “Simulation” and includes selecting simulation elements, creating groups for comparison and choosing sampling options.
- Outcomes and endpoints – Outcomes & Endpoints are below the “Simulations” section. Outcomes represent a post-processing of the simulation outputs for each individual. Endpoints summarize the outcome values over all individuals, for each simulation group and for each replicate. It is a separate task, so it does not require re-running the entire simulation after a modification.
- Results – Results are in a dedicated tab as copyable tables. They include individual and output values, outcome&endpoint analysis and statistical group comparison.
- Plots – All simulation outputs, defined outcomes and endpoints are displayed on separate plots as individual outputs and distributions. In addition, plot settings, stratification options and charts preferences are available at hand in the right panel of the interface.
4.1.Building a simulation scenario
Simulx allows to interactively build a simulation scenario using simulation elements defined in the “Definition” tab and additional options available in the interface. It is done in the Simulations tab – Simulation section – which contains:
- List of simulation elements, which can be shared between groups or set as group specific.
- Flexible group definition with drop-down menus for selecting group specific elements and with editable group names.
- Option to run a single simulation or replicates.
- Different sampling options such as using subjects with the same individual parameters or drawing individuals from table type elements with different methods.
To run a scenario, just click on the button SIMULATION in the tasks section. When importing a Monolix project, Simulx automatically sets the scenario re-simulating the Monolix project.
- Simulation elements
- Groups
- Replicates
- Sampling options and use of ids
- Sampling options
- Shared ids
- Same individuals among groups
Simulation scenario elements
List of simulation elements contains: group size, parameters, treatments, outputs and, if used in a model, covariates and regressors. To select an element from already defined elements, use a drop-down menu available after clicking on the currently selected element. To edit a selected element, click on the icon . To create a new element, click on the “plus” icon
to open a “New element” pop-up window in the Definition tab.
Mandatory elements
- Group size corresponds to the number of individuals in a group.
- Parameters can be chosen from POP. PARAM. or INDIV. PARAM. elements in the Definition. When Individual parameters are selected, then the covariate element disappears and new section to set the error model parameters becomes available.
Note: Remaining parameters are all parameters that appear in the structural model (in the input line of [LONGITUDINAL]) and are neither individual parameters not regressors. They are typically error model parameters. These error model parameters will impact the simulation only if a noisy observation (from the DEFINITION section of the [LONGITUDINAL] block) is set as output element (instead of a smooth prediction in OUTPUT or variable in EQUATION).
- Outputs correspond to one or more variables to be computed and displayed in plots and results. When importing a project from Monolix, by default all observation outputs (if defined in a model) are automatically selected, otherwise only the last defined model output.
- Covariates are available in two situations: selected treatments use a covariate scaling or individual parameters model uses covariates and population parameters are selected as an element in the Parameters.
- Regressor is available only if it is used is a model.
Optional elements
- Treatment can be one element or a combination of several treatment elements.
- Occasions are optional even if defined in a model, but are mandatory if any occasion-dependent element is selected in a scenario.
Simulx automatically assigns default elements: the last one from the definition list of each category or specific default “mlx_” types after importing a Monolix, see here for details. It is not possible to remove in the Definition tab an element currently used in a simulation. However, it might not be possible to run a simulation if any of the mandatory elements was removes. For instance, deleting occasions element removes automatically all occasion-dependent elements even if used in a simulation.
Simulation scenario with groups
Groups allows to build a scenario with population having different characteristics, such as parameters, regressors, covariates, different treatments and/or different simulation outputs. Moreover, groups can have different number of individuals to compare clinical trial of different sizes.
To create a new group click on the “plus” button, use the arrows to move elements from “shared” part to group section (or vice versa) and select specific element for each group. Each simulation element can be shared between groups or can be a group specific.
To edit a group name click next to it. In the Plots tab, figures for different groups appear in the same order as they are defined in the Simulation tab, not in the alphabetical order. To remove a group click “x” under the group name.
- Each new group is by default a copy of the previous one (eg. group 3 is a copy of group 2).
- Population and individual parameters can not be used in different groups simultaneously.
Examples:
- [Demo 5.simulation: simulationGroups_treatment]: Simulation of three groups with three different oral dose levels: low (trt_1), medium (trt_5) and high dose (trt_10). Groups sizes, parameters, covariates and outputs are shared (the same) between the groups, while treatment is group specific.
- [Demo 5.simulation: simulationGroups_ethnicGroups]: Simulation of two groups with different ethnicity, which affects the bioavailability. In this case, “covariates” simulation element is group specific with: “caucasian” modality for the first group and “asian” for the second group.
Simulation scenario with replicates
By default, Simulx simulates one clinical trial. When the option “replicates” is selected, then Simulx simulate the scenario several times.
- If population parameters are vectors (user-defined or imported from a Monolix project), then all replicates have the same population parameters.
- If population parameters are of a distribution type, then Simulx samples one set of population parameters for each replicate.
- If population parameters are given as an external table with several population parameters sets, for instance from the simpopmlx function, then each replicate uses one set of population parameters with the order of the appearance in the table.
Tables in the results tab display information for all replicates.
In “summaries” the values are summarized over all individuals and all replicates. For instance, endpoints result summarize outcomes over all replicates with the uncertainty of the result.
Similarly, plots contain information of all replicates. By default, individual outputs display only one replicate, however, stratification panel allows to select one or more replicate to plot (green frame).
Endpoint distribution in case of replicates is summarized in a box plot.
Sampling options
Individual sampling
Simulation elements of different types are subject to different individual sampling in a simulation. Elements defined as vectors provide common values for all individuals, so there is no sampling. When an element is a distribution, then sampling is done for each individual separately. Tables, from external files or from Monolix after importing a project from Monolix, can contain data for more then one individual distinguished with the column called “id”. In this case, there are three sampling methods available in the Simulation tab.
- Keep order (default) – individual values are taken in the same order as they appear in a table.
- With replacement – individual values are samples from a table with replacement.
- Without replacement – individual values are samples from a table without replacement. This option is available only if tables contain at least the same number of individual values as a group size.
All of the above sampling methods are general and apply to all tables in a simulation scenario.
Shared ids
If there is a group of tables with individual values, an option “shared ids” allows to create an intersections of ids present in the considered tables. After that, ids from these intersection are sampled to create the data for simulation.
Example: Simulation uses a treatment with a dose amount depending on the patients weights. Treatment element and weights are external tables with columns (id, time, amount) for the treatment, and (id, weight) for the covariate. Moreover, an effect of the weight is added on the definition of the individual parameter (volume of the central compartment) in the model. It this case, it is important to match a sample from the treatment element with a sample from the covariate element. It is done by ticking two boxes in the “shared ids” column for both elements (blue frame).
Same individuals among groups
“Same individuals among groups” option allows to have the same individual parameters in all groups and is available if the following elements (required for the sampling) are the same for all groups: size of groups, parameters (population or individual) and covariates. The main aim is to make the comparison between groups easier. In particular, it is used to compare different treatments on the same individuals – subjects with the same individual parameters. Selecting same individuals among groups assures that the differences between groups are only due to the treatment itself. To obtain the same conclusion without this option enabled, simulation should be performed on a very large number of individuals to averaged out the individual differences.
Example: a simulation of two treatment groups with shared parameters, covariates and outputs. When the option “same individuals among groups” is enabled, then subjects in each group have the same individual parameters because the same Parameters (manual_popParam) and Covariates (race) are used in all groups (Demo 5.simulation: simulationGroups_sameIdsInGroups).
4.2.Outcomes and endpoints
Outcomes, endpoints group comparison are in a dedicated section “Outcomes&endpoints” of the Simulation tab.
To calculate outcomes and endpoints click on the “Outcomes&Endpoints” button in the Tasks section (on top). The outcomes are a post-processing of the simulation outputs, so remember that you have to first run the “Simulation” task. You can also selected the task “Outcomes&Endpoints” in a scenario (circle radio button on the right hand side of the task button) and click the button RUN – Simulx will run both tasks automatically one by one.
The calculated values are displayed in the Results tab and Plots tab.
Outcomes
Outcomes represent a post-processing of the simulation outputs done for each individual. They correspond to the measure of interest per individual. Outcomes have different types: values (e.g Cmax), binary true/false (e.g true if Cmax < threshold), or time-to-event (e.g time to NADIR).
To create a new outcome, click on the “plus” button next to Outcomes header or on the “+ New outcome element” within the list of outcomes for an endpoint:
Each outcome has a name (default or user defined), which allows to select it in an endpoint definition. To define an outcome you have to select an output element for post – processing. You can only use output elements selected in the Simulation scenario. The specification of the outcome includes the following options to post-process the selected output.
For continuous, count and categorical outputs:
Relative to: none/ baseline/ maximal or minimal value/ maximal or minimal value up to current time/ custom value: it divides (“ratio”) or subtracts (“difference”) the output values by the specific value (i.e baseline – the first value of the output). For baseline option, because the first value of the transformed output is non-informative (ratio=1 or difference=0), it is removed.
Output processing:
- average value – takes the average over all output values for each individual
- first or last value – takes a value at the first or last time point for each individual
- min or max value – takes the minimum or maximum over all output values for each individual. You can choose “value of min/max” to take the value of the min or max, or choose “time of min/max” to take the time of the min or max – as continues time or time-to-event.
- at custom point – takes a value of an output at a specified time point. Only grid time points are allowed.
- duration below or above a value or between values – calculates time when the output values are below, above or between a given values. Strict inequalities (< or >) apply. You input threshold values manually below the output processing menu. As duration you can choose:
- “cumulative time” – sum of time intervals between consecutive time points where output values satisfy the condition
- “% of total time” – cumulative time divided by the final time (in percentage)
- “number of observations” – number of time points where output values satisfy the condition
- “time of the first occurrence” – a time point where the condition is satisfied for the first time (can be event or continuous)
Apply threshold: applies a logical test (usually comparing the outcome value to a threshold) to get a binary true/false outcome. You must set a threshold value and a comparison sign (=, !=, >=, <=, >, <).
For single time-to-event outputs:
- Has event / has no event / time of event: “has event” and “has no event” calculates if the individual had or didn’t have an event during the observation period. This is a binary true/false outcome. “time of event” uses the TTE output as outcome directly. The outcome is then of type ‘time-to-event’.
For repeated time-to-event outputs:
- Has at least one event / number of events per id / time of event #: “has at least one event” leads to a binary true/false outcome depending if the individual has at least one event during the observation period or not. “number of events per id” count the total number of events for each individual. This is an outcome of type ‘value’. “Time of event # “ generates a time-to-event outcome with a single event per individual. The index of the event to be considered can be typed-in by the user.
Occasions
In case occasions, you can choose to compute the outcome for each individual, or for each occasion of each individual. Select a corresponding radio button in the outcome definition window
Outcomes organization
Outcomes are building blocks for endpoints. When you create a new outcome, you can add the outcome to a new or to an existing endpoint via the option “Add to endpoint” at the bottom of the outcome definition window. The Outcomes & endpoints section displays only the outcomes used in endpoints. All defined outcomes, whether used or not in an endpoint, appear in the list of outcomes:
Outcomes of the same type can be combined together using AND/OR for binary true/false outcomes (e.g Cmax < threshold1 and Ctrough > threshold2), or MIN/MAX for double values and time-to-event (e.g max(CmaxParent, CmaxMetabolite) ).
Endpoints
Endpoints summarize the outcome values over all individuals, for each simulation group and each replicate. To create a new endpoint, you can select one or several outcomes of the same type from the drop-down menu (highlighted below in blue) or click on the “+” icon next to the Endpoint header. Endpoints are also created automatically, when at the bottom of an outcome definition you select the option “Add to endpoint: New endpoint”. Once you create an endpoint, you can change its name highlighted below in green).
There are several options to summarize the individual outcomes into an endpoint. It depends on the type of outcomes:
- value outcomes: the endpoint can be
- geometric mean. Includes calculation of the coefficient of variation.
- arithmetic mean. Includes calculation of the standard deviation.
- median. Includes calculation of the 5th and 95th percentiles.
- binary true/false outcomes: the endpoint will be the percentage of true. Includes calculation of the “total number true”.
- time-to-event outcomes: the endpoint will be the median survival (time at which the Kaplan Meier curve is equal to 0.5). Includes calculation of the lower bound (5th) and and upper bound (95th) of the confidence interval of the median survival.
Group comparison
You can compare endpoints across simulation groups by activating the toggle “Group comparison” (green highlight). One of the simulation groups must be defined as the reference group (blue highlight) and all other groups will be compared to this reference group. For each endpoint, the group comparison can rely on a direct comparison of the endpoint values, or on a statistical test (purple highlight). The exact comparison or test applied depends on the type of the endpoint.
Statistical tests
This table gives an overview of the statistical tests performed in Group comparison depending on the type of outcome and endpoint. Next sections contain detailed information of each option.
Outcome | Endpoint | Metric | Statistical test | |
Same indiv = True | Same indiv = False | |||
Continuous | Geometric mean | Ratio of means | Paired t-test on log-transformed |
Unpaired t-test on log-transformed |
Arithmetic mean | Difference of means | Paired t-test | Unpaired t-test | |
Median | Difference of medians | Wilcoxon signed rank test | Wilcoxon rank sum test | |
Binary true/false | Percent true | Odds ratio | McNemar’s exact test | Fisher’s exact test |
Time-to-event | Median survival | Difference in median survival | Logrank test with variance correction | Logrank test |
Endpoint “median” for value outcome
This test calculates the difference between the median of the test group and of the reference group: \( \textrm{median}_{test} – \textrm{median}_{ref} \) with \(\textrm{median}_{test}\) and \(\textrm{median}_{ref}\) the median in the test and reference group respectively.
In case of a direct comparison, this difference is compared using operators =, !=, >, >=, <, <= to a user-defined value (default: 0). When this logical comparison is true, the trial simulation is considered as ‘success’.
Example: When the direct comparison “difference > 25” is true, it means that the median in the test group is larger than in the reference group by at least 25 units (e.g ng/mL if the outcome is a peak concentration).
In case of a statistical test, a Wilcoxon rank sum test (equivalent to the Mann-Whitney test) (“Same individuals among groups” not selected) or a Wilcoxon signed rank test (“Same individuals among groups” selected) is done to compare the median of the test and reference group. “difference \(\neq\) 0” represents the alternative hypothesis H1. By default, it performs a two-sided test (sign \(\neq\)) and checks if the medians significantly differ from each other. You can define single-sided tests by choosing “>” or “<“. The minimal or maximal (depending of the direction of the test) difference can also be specified (default: 0). The statistical test results into a p-value, which is compared to a user-defined threshold (default: 0.05). If the p-value is below the threshold, the trial simulation is considered as ‘success’.
Example: When the statistical test testing the alternative H1 hypothesis “difference > 25” results into a small p-value, it means that the medians of the test and reference groups differ by more than 25 units significantly (e.g ng/mL if the outcome is a peak concentration) with a larger value for test.
Endpoint “arithmetic mean” for value outcome
This test calculates the difference between the mean of the test group and of the reference group: \( \textrm{mean}_{test} – \textrm{mean}_{ref} \) with \(\textrm{mean}_{test}\) and \(\textrm{mean}_{ref}\) the mean in the test and reference group respectively.
In case of a direct comparison, this difference is compared using operators =, !=, >, >=, <, <= to a user-defined value (default: 0). When this logical comparison is true, the trial simulation is considered as ‘success’.
Example: When the direct comparison “difference > 14 ” is true, it means that the mean in the test group is larger than in the reference group by at least 14 units (e.g ng/mL if the outcome is a peak concentration).
In case of a statistical test, it performs an unpaired t-test (“Same individuals among groups” not selected) or a paired t-test (“Same individuals among groups” selected) to compare the test and reference group. “difference \(\neq\) 0” represents the alternative hypothesis H1. By default, it performs a two-sided test (sign \(\neq\)) and checks if the two means significantly differ from each other. You can define single-sided tests by choosing “>” or “<“. The minimal or maximal (depending of the direction of the test) difference can also be specified (default: 0). The statistical test results into a p-value, and compares it to a user-defined threshold (default: 0.05). If the p-value is below the threshold, the trial simulation is considered as ‘success’.
Example: When the statistical test testing the alternative H1 hypothesis “difference > 14” results into a small p-value, it means that the means of the test and reference groups differ significantly by more than 14 units (e.g ng/mL if the outcome is a peak concentration) with a larger value for test.
Endpoint “geometric mean” for value outcome
This test calculates the ratio of the test geometric mean divided by the reference geometric mean: \( \textrm{geoMean}_{test} / \textrm{geoMean}_{ref} \) with \(\textrm{geoMean}_{test}\) and \(\textrm{geoMean}_{ref}\) the geometric mean in the test and reference group respectively.
In case of a direct comparison, this ratio is compared using operators =, !=, >, >=, <, <= to a user-defined value (default: 1). When this logical comparison is true, the trial simulation is considered as ‘success’.
Example: When the direct comparison “ratio > 2” is true, it means that the geometric mean in the test group is at least twice larger than in the reference group.
In case of a statistical test, it performs an unpaired t-test (“Same individuals among groups” not selected) or a paired t-test (“Same individuals among groups” selected) on the log-transformed values (which are assumed to follow a normal distribution) to compare the means of the test and reference group. “ratio \(\neq\) 1” represents the alternative hypothesis H1. By default, it performs a two-sided test (sign \(\neq\)) and checks if the geometric means significantly differ from each other. You can define single-sided tests by choosing “>” or “<“. The minimal or maximal (depending of the direction of the test) ratio can also be specified (default: 1). The statistical test results into a p-value, which is compared to a user-defined threshold (default: 0.05). If the p-value is below the threshold, the trial simulation is considered as ‘success’.
Example: When the statistical test testing the alternative H1 hypothesis “ratio > 2” results into a small p-value, it means that the geometric mean of the test group is significantly larger than twice the geometric mean of the reference group.
Endpoint “percent true” for binary true/false outcome
This test calculates the odds ratio between the test group and the reference group. The odds ratio definition is different depending if you use paired samples case or not.
“Same individuals among groups” not selected (unpaired samples)
The odd ratio is \( \frac{pTest}{1-pTest} / \frac{pRef}{1-pRef} \) with \(pTest\) and \(pRef\) the fraction of true outcomes in the test and reference group respectively. \(1-pTest\) represents the fraction of false outcomes.
Equivalently, you can use the following contingency table to define the odd ratio.
“Same individuals among groups” selected (paired samples)
In case of identical individuals among groups, the individuals which have the same outcome value in both groups (so Ref=True and Test=True, or Ref=False and Test=False) are not counted. The odd ratio is defined as\( \frac{nTest_TRef_F}{nTest_FRef_T}\), with \(nTest_TRef_F\) the number of individuals with true in the test group and and false in the reference group. It corresponds to the contingency table below. The odds ratio can frequently be zero or infinity – in particular in the absence of measurement noise – an individual true in the reference group is also necessarily true in the test group (corresponding for instance to a higher dose).
In case of a direct comparison, this odds ratio is compared using operators =, !=, >, >=, <, <= to a user-defined value (default: 1). When this logical comparison is true, the trial simulation is considered as ‘success’.
Example: When the direct comparison “odds ratio > 2” is true, it means that the odds in the test group are at least twice larger than in the reference group.
In case of a statistical test, it preforms a Fisher’s exact test (“Same individuals among groups” not selected) or a McNemar’s exact test (“Same individuals among groups” selected) to compare the results of the test and reference group via the construction of a 2×2 contingency table (which contain more information than the endpoinds \(pTest\) and \(pRef\)). “odds ratio \(\neq\) 1” represents the alternative hypothesis H1. By default, it performs a two-sided test (sign \(\neq\)) and checks if the odds ratio significantly differs from 1. You can define a single-sided tests by choosing “>” or “<“. The minimal or maximal (depending of the direction of the test) odds ratio can also be specified (default: 1). The statistical test results into a p-value, and compare it to a user-defined threshold (default: 0.05). If the p-value is below the threshold, the trial simulation is considered as ‘success’.
Example: When the statistical test testing the alternative H1 hypothesis “odds ratio > 2” results into a small p-value, it means that the odds of the test group are significantly larger than twice the odds of the reference group.
Endpoint “median survival” for time-to-event outcome
This test calculates the difference between the median survival of the test group and of the reference group: \( \textrm{medSurv}_{test} – \textrm{medSurv}_{ref} \) with \(\textrm{medSurv}_{test}\) and \(\textrm{medSurv}_{ref}\) the median survival (time at which the Kaplan-Meier estimates equals 0.5) in the test and reference group respectively.
In case of a direct comparison, this difference is compared using operators =, !=, >, >=, <, <= to a user-defined value (default: 1). When this logical comparison is true, the trial simulation is considered as ‘success’.
Example: Direct comparison “difference > 60” corresponds to median survival in the test group larger than in the reference group by 60 time units (e.g days).
In case of a statistical test, it performs a logrank test to compare the survival Kaplan-Meier curves. Selecting “Same individuals among groups”, applies a variance correction (see Jung 1999). “difference \(\neq\) 0” represents the alternative hypothesis H1. By default, it performs a two-sided test (sign \(\neq\)) and checks if the survival curves significantly differ. You can define single-sided tests by choosing “>” or “<“. For the log rank test, it is not possible to define a “minimal difference”. The statistical test gives a p-value, and compare it to a user-defined threshold (default: 0.05). If the p-value is below the threshold, the trial simulation is considered as ‘success’.
Example: When the statistical test testing the alternative H1 hypothesis “difference \(\neq\) 0” results into a small p-value, it means that the survival curves from the two groups differ significantly.
4.3.Plots
Running the tasks in Simulx automatically generates interactive plots for simulation outputs, outcomes and endpoints. Interface provides many plots features such as:
- Different chart types depending on simulation outputs and post-processing methods: individual outputs or distributions.
- Plots settings: display, binning criteria, axes, visual cues.
- Stratification and customization options.
- Export:plots as images, charts data and charts settings.
To learn more about plots in the exploration tab, click here – it is a special documentation page for the model Exploration feature.
Plots tab structure and settings in Simulx is the same as in Monolix and Pkanalix. The left panel (green frame) contains the list of available plots grouped by outcome type or by chart type. Central region displays one selected plot, for instance output distribution of Cc. Each simulation group has its own subplot. On top of the plotting area, there are layout options and a button to export current plot as an image (blue frame). The right panel is for plots settings, such as display or axis options, definition of bins or visual cues. In addition, separate sub-tabs at the bottom of this panel (red frame) allow to stratify plots data and change preferences of the plotting area.
- Simulation outputs. Only output elements used in a simulation scenario generate plots. If more then one simulation output element uses the same model output, then all these simulation outputs are merged on one same plot. For instance, concentration during the whole treatment period on a fine grid and Ctrough on the last treatment day – both using model prediction Cc. Title name of the plot corresponds to the model output name.
- Outcomes. Outcomes of different endpoints have separate plots, for instance “Cmax” and “CmaxBelow800”. If there is more then one outcome in an endpoint, then a plot displays the combination of them. Moreover, it appears in the plots list as “<endpointName>_outcome”, for instance “SafetyAndEfficacy_outome”.
- Endpoints distribution is generated only for simulations with replicates.
Plots for continuous data
There are two types of plots for continuous outputs. Firstly, the individual output subplot, which contains individual curves. Secondly, the output distribution with the percentiles. Title of each outcome section in the plot list corresponds to the name of a model variable, for instance Cc for model predictions or y1 for model observations. It is not the name of the output element selected in the simulation tab.
Individual output
Individual output plots represent individual curves computed for each id and each occasion (if present in the model). It is possible to DISPLAY lines, dots and median with standard deviations (green frame), or a combination of them. The statistics (median and standard deviations) use the binning options available in the BINS section of the settings (blue frame). If simulation uses replicates, then by default a plot shows only one replicate. However, you can select other replicates – one or several – in the DISPLAY sub-tab.
The ID used in plots stratification is the simulated ID, which is the id column in the result tables. ID i is the i-st parameter set sampled for simulation.
Since the version 2023R1, if a simulation uses elements with custom id lists, for example a table of individual treatments, or a table of individual parameters, the original ids in these tables are available to stratify the plots. For example in the demo project “importFromMonolix_useEBEs_originalID.smlx”, we use the element mlx_EBEs which is a table of individual parameters. The original IDs used in this table can be used to color or split the individual output trajectories.
Output distribution
Output distribution plots show percentiles of the simulated data for all ids and all replicates computed. The BINS section of the settings contains the binning options. DISPLAY settings allow to change plot features, such as median, number of percentiles bands and levels.
When the “Output distribution” plot is split (by simulation group or by a covariate), it is possible to overlay the prediction intervals on a single plot with different colors using the “merged splits” toggle. You can choose the colors in the “stratification groups”. This feature is available starting from the Simulx 2023 version.
Plots for non-continuous data
Time-to-event
Individual output of time-to-event data is a single Kaplan-Meier curve – estimator of the survival function. In addition, for simulations with replicates, the Kaplan-Meier curves for each replicate are interpolated on one grid and displayed as a prediction interval at a specific level (blue frame). Mean number of subjects plot is available in the SUBPLOTS section (green frame). Click here for more information about time-to-event data plots.
Discrete data (categorical and count)
Individual outputs are functions of time for each individual and occasion.
- Count data: plots show the number of observed events in a specific period, for instance “number of good answers” (on the left).
- Categorical data: plots show nominal categories, for instance “respiratory status level” (on the right).
Output distribution shows the time evolution of probabilities of different categories. In case of count data, each number of “counts” constitutes a separate category.
Plots for outcomes and endpoints
- Outcomes represent a post-processing of the simulation outputs done for each individual, so plots display their distribution within a population. Simulx displays only outcomes used in endpoints (Outcome&endpoint section in the simulation tab). If there are several outcomes in one endpoint, then the outcome distribution corresponds to of a combination of these outcomes, and not to separate outcomes.
- Depending on a type of an outcome, plots are histograms or box plots for numeric outcomes, and stacked histograms for binary outcomes.
- Endpoints summarize the outcome values over all individuals. In simulation with replicates, Simulx displays them as box plots.
- In all boxplots, the dashed line represents the median, the blue box represents the 25th and 75th percentiles (Q1 and Q3), and
the whiskers extend to the most extreme data points, outliers excluded. Outliers are the points larger than Q1 + w*(Q3 – Q1) or smaller than Q1 – w*(Q3 – Q1) with w=1.5. Outliers are shown with red crosses.
[Demo: 6.1.outcome_endpoint/OutcomeEndpoint_PKPD_Cmax_targetinhibition]
Numeric outcome distribution:
“Cmax” outcome gives for each individual the maximum of the output element “Plasma concentration”. In this case, the outcome distribution can be a box-plot or as a histogram (selection in the DISPLAY settings). Each group is on a separate subplot. This outcome is the only outcome in the endpoint, so the title name of the plot in the list coincides with the outcome name.
Binary outcome distribution
“CmaxBelow800” outcome is a of boolean type (true/false) and compares the maximal value of the “Plasma concentration” with a threshold of 800. If Cmax is below this value, then the outcome is true, otherwise it is false. Similarly, “inhibitionAtTroughAbove80Percent” outcome compares the average of the values in the output element “TargetInhibition_at168h” with a threshold of 0.8 (i.e 80%). These two outcomes belong to one endpoint “SafetyAndEfficacy”, so the plot shows the distribution of true/false values corresponding to the combination of the two conditions. In this case, the title name of the outcome plot is the name of the endpoint “_outcome” (red frame). Binary outcomes use stacked or grouped histograms (green frame). Hovering on a any part of the histogram highlights it, shows the outcome value and the corresponding number of individuals.
Endpoint distribution
If this simulation scenario is run several times – option “replicates” available in the Simulation section – then the endpoint distribution plots are added to the plots list. Endpoint median_Cmax is a a box-plot with median value and standard errors for groups listed on the x-axis. For endpoints using numerical outcomes, uncertainty of the 5th and 95th percentiles can be added from the settings – SUBPLOTS section (green frame).
Endpoints using binary outcomes, in this example the SafetyAndEfficacy endpoint, calculate the percentage of individuals with “true” outcomes values. As previously, the endpoint distribution is a box-plots with different groups on the x-axis. A subplot with the number of individuals is available from the settings.
Plots features
The right panel of the Plots tab has several sub-tabs – at the bottom of the interface window – to interact and customize the charts:
- “Settings” modify plots elements, such as: hide or display additional data, adjust binning criteria, change axis or add visual cues
- “Stratify” splits, filters or colors data points using covariates.
- “Preferences” customize graphical aspects of plots such as colors, font sizes, line width or margins.
Icons at the left-top angle of the plotting area – – allow to select sub-plots for visualization, change the sub-plots layout and export the plots as a png or svg file (saved in the Chart folder in the Results). In addition, using the “Export” in the top menu saves all generated plots (Export plots), saves all data used to generate plots as txt files to re-plot them outside Simulx ( Export charts data, see here for more information) and save charts settings so that the selected customization is applied to all Simulx projects (Export charts settings as default).
Simulx has the same architecture of plots features, preferences and export options as Monolix. Here is an extensive documentation about it, with links to Features of the week videos that explain how to use customization in MonolixSuite applications.
Settings
Settings sub tab has several sections, which may differ between plot.
- General settings include toggle buttons add legend, data information, dosing etc. Zoom is interactive by selecting with a cursor a region directly on a plot.
- Display section for “individual output” plots has toggle buttons to add lines, data dots and Mean and SD (at least one option needs to be selected). For “output distribution” it customizes the level of percentiles and the number of bands shown.
- Bins serve to specify the criteria for computing the mean&SD for the “individual outputs” and percentiles for the “output distribution”. There are several strategies to segment the data: equal width, equal size and the least squares criterion. In addition, number of bins, range and number of data per bin are changeable.
- Axes is for general X and Y axis settings, such as log scale, same limits across plots and main axis titles.
- Visual cues freehand guides option allow to place additional lines or points on plots directly with a cursor. Definition of a specific location is via (X,Y) coordinates – one entry filled gives a line, two filled entries specify a point.
Stratify
Stratification panel contains a list of covariates that can split, color or filter the data. Simulx automatically allocates covariates in groups – according to modalities for categorical covariates and in two “equal count” groups for continuos covariates. As a result stratification is immediately applied after ticking appropriate boxes.
Example:
- Color data according to two weight groups (blue frame)
- Split data between HV (healthy volunteers) and RA (rheumatoid arthritis) patients (green frame)
When the “Output distribution” plot is split (by simulation group or by a covariate), it is possible to overlay the prediction intervals on a single plot with different colors using the “merged splits” toggle. The colors can be chosen in the “stratification groups”. This feature is available starting from the 2023 version.
4.4.Results
The results tab displays the simulated values and the outcomes and endpoints as tables.
Result tables are organized into three sections:
Simulation
The simulation tab displays the simulated output values and the sampled individual parameters.
Outputs
Because the simulated output values are usually a very large table, the results are presented as percentiles for continuous simulations (minimum, 5th percentile, median, 95th percentile and maximum) and as percentage of survival and average number of events for time-to-event simulations. These statistics are calculated over time bins calculated automatically. When replicates are used, the statistics are calculated over all replicates merged together. Each simulation group is displayed as a separate table.
Individual parameters [Summary]
This tab displays the percentiles summarizing the distribution of individual parameters used for simulation for each of the groups. These parameters have been either directly defined by the user or sampled from the population parameters defined by the user. As for the simulated outputs, the statistics are calculated over all replicates merged together.

Individual parameters [Table]
This tab displays the full tables of individual parameters for all replicates and for all groups. The content of these tables can also be found in a table gathering all groups in the result folder>Simulation>individualParameters.txt .
The id column in these tables is the simulated id, meaning that id i is the i-st parameter set sampled for simulation.
Since the version 2023R1, if elements using original id lists have been used for simulation, for example a table of individual treatments, or a table of individual parameters, the original ids in these tables is reported in the individual parameter tables in the “original_id” column. For example in the demo project “importFromMonolix_useEBEs_originalID.smlx”, we use the element mlx_EBEs which is a table of individual parameters. The original IDs used in this table are reported in the sampled individual parameters table, together with the simulated id. The original id is also reported in the output files.
If a simulated id uses information coming from several original ids (e.g when a table a individual parameters and a table of treatment is used by the “shared ids” option is not selected), then the original id is not displayed in the GUI but it can be found in the result folder in the file ID_mapping.txt.
Endpoints
The endpoints section appears if an outcome has been defined in the simulation tab, to post-process the simulation results.
Outcomes [Summary]
The summary shows one table per outcome, displaying the percentiles over individuals and replicates for each group if the outcome is continuous, and the number of true and false individuals if the outcome is a boolean.
Outcomes [Table]
The outcomes table shows the outcome values for all individuals. A table of all values for each outcome also appears the result folder/Endpoints.
Endpoints [Summary]
Endpoints summarize the outcome values over all individuals for a specific group and replicate. The endpoints summary shows percentiles for the calculated endpoint over replicates. These percentiles give the uncertainty of the endpoint value over several clinical trial simulations.
Endpoints [Table]
The endpoints table shows the value of the endpoint defined in the simulation tab for each group and each replicate. A table for each endpoint is also saved in the result folder/Endpoints.
Group Comparison
If several simulation groups are used, and if group comparison is checked in the simulation tab, the group comparison section appears in the results.
Group comparison Table
For each replicate study, a test comparing the groups is performed as defined in the group comparison section of the simulation tab. The statistics of the test, p-value and the resulting decision (success or failure) according to the defined criteria are reported for each group (compared to the reference group) and for each replicate. A table is also saved for each statistical test and for each decision criterion in the result folder/Endpoints.
Group comparison Summary
The summary of group comparison shows for each group the percentage of replicates that led to a successful test.
Export Simulations
Export simulations as output files at each run
The full table of simulated values can be generated at each run if the preference setting “Export simulation files” is true. It will then appear in the result folder > Simulation > simulation_xxx.txt with xxx the output variable name.

Export simulations as a Monolix or PKanalix project
Note that this option not available in Simulx versions prior to 2023.
After running simulations, it is possible to generate a new Monolix or PKanalix project using the simulated values as dataset. This can be done from the menu Export > Export project to:

In the pop-up window, you can choose:
- to which application you want to export the simulated dataset: PKanalix or Monolix.
- names to the generated dataset (based on simulations) and generated model file (if the model is not part of the library).

Click the “EXPORT” button at the bottom to confirm. The target application (Monolix or PKanalix) will open automatically with a predefined project called “untitled”. The simulated dataset and model files (if not from the library) will be copied next to the new new project – first in the temporary folder, when the project is “untitled”, then to the final destination, where you save the project.
The dataset in the new project will be set in the following way:
- A column ID contains the identifiers for the individuals simulated in the Simulx project. It is tagged as ID if no replicates have been used in Simulx.
- If replicates have been simulated, a UID column containing a unique identifier combining replicate and ids (eg 1_rep1) is tagged as ID, and a rep column indicates the replicate (it is possible to use filters to select a single replicate if necessary).
- If external elements have been used in Simulx, original IDs coming from these elements are indicated in a column original_id which is ignored by default, but can be tagged by the user as categorical covariate or ID, depending on the situation.
- Simulation groups are given in a column group tagged as stratification categorical covariate.
- If several model outputs are simulated, the output names are indicated in an obsid column tagged as observation ID.
- Pre-defined tagging is used for time, observation, amount, and simulated covariates.

For an export to PKanalix, the new project will be set in the following way:
- the data is set as described above.
- NCA settings: default PKanalix settings for administration type, integral method, treatment of BLQ values, parameters
- NCA settings: “observation ID to use” set to the first one alphabetically (if obsid are strings) or numerically (if obsid are integers).
- Acceptance criteria: not selected.
- Bioequivalence: default PKanalix settings
- the structural model is set to the generated model file attached to the new project, or a model from the library if the Simulx project used a library model.
- The generated structural model only includes the [LONGITUDINAL] block of the Simulx model, without the error model.
- If a statistical model was used in simulx (observation or individual model), it is not included in the generated model file for PKanalix.
- The mapping automatically links the simulated observations to the model outputs.
- If additional lines were used in the Simulx project, they are added at the end of the generated structural model file.
- If output elements are defined based on intermediate variables of the model in the Simulx project, they are added to the output section of the model.
- The mapping automatically links the simulated observations to the model outputs. If a statistical model was used in simulx (observation or individual model), it is not included in the generated model file for PKanalix. The generated model only includes the [LONGITUDINAL] block without DEFINITION section.
- CA initial parameter values: set to default
- CA parameters constraints: none for normally distributed parameters, positive for log-normally distributed parameters; bounded with limits imported from the Monolix project for logit-normally and probit-normally distributed parameters.
- CA calculations settings: default PKanalix settings
For an export to Monolix, the project will be set in the following way:
- the data is set as described above.
- the structural model is set to the generated model file attached to the new project, or a model from the library if the Simulx project used a library model.
- The generated structural model only includes the [LONGITUDINAL] block of the Simulx model, without the error model.
- The mapping automatically links the simulated observations to the model outputs.
- If additional lines were used in the Simulx project, they are added at the end of the generated structural model file.
- If output elements are defined based on intermediate variables of the model in the Simulx project, they are added to the output section of the model.
- Initial values are set to default.
- the observation model and individual model in Monolix statistical model tab is set based on the Simulx project, if a statistical model was defined in the model of the Simulx project (INDIVIDUAL, COVARIATE blocks or error model in the LONGITUDINAL block). Note that the statistical model is not included in the generated model file for Monolix, but it is taken into account in the statistical model tab. Only the Monolix style syntax for the INDIVIDUAL block can be imported to the Monolix project, not the flexible style. When modifications are done to the model for compatibility reasons, Simulx warns you at export to double check the model interpretation in the Monolix project.
- if some part of the statistical model is not defined in the Simulx project, it is set to default in the statistical model tab.
Export simulations as a formatted dataset
Note that this option not available in Simulx versions prior to 2021.
To export simulations as a formatted dataset for further investigations outside the Monolixsuite, it is possible to use the menu Export > Export simulated data. This data set contains the dose, occasions, covariate, simulation groups, observation id informations in addition to the id, time and simulated values. The exported simulated data file is located in the result folder > Simulation > simulatedData.txt.

General display options
The tables generally contain many rows and are by default paginated. The page displayed and the number of records per page can be changed at the bottom (green highlight). The panel on the right (blue highlight) allows to switch the pagination off in order to show the entire table. The tables can also be all expanded and collapsed. When several groups and several output variables/outcomes/endpoints have been defined, the tables can be grouped by either simulation group or output/outcome/endpoint to easily compare the tables of interest. Finally it is possible to hide some of the simulation groups using the drop-down selection menu. The display panel can be hidden with the button
at the top right. The button
on the bottom left opens the result folder which contains the simulated values and their post-processing as text files. All tables can be copied to the clipboard using the button
at the top left . Only the displayed page is copied. To copy the entire table, expand it first.
