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:

• Importing a project from Monolix
• Writing a new project from scratch

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

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.

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.

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.

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.

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

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:

1. [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.
2. [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).

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.

• Continuous data
• Non-continuous data
• Outcomes and endpoints
• Plots features

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.