Select Page

Version 2021

This documentation is for Simulx.

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?

play:

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. 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 automatically ready. As a result, it saves a lot of time. It is always possible to 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 all elements that could be useful for simulating the model automatically generated 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.

Moreover, exploration and simulation scenarios are set and 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.
• 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.
• 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, modifying the model removes all simulation elements. In addition, removing occasions removes all occasion-dependent simulation elements.

A typical simulation workflow with a project imported from Monolix

The projects shown here are all 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 strategies. Simulations should answer the following questions:

• 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”]

The Monolix project imported in Simulx for this example can be downloaded here. To import the Monolix project, unzip the folder and import the .mlxtran file. After importing a project from Monolix, the task buttons “simulation” and “run” in the Simulation tab re-simulate the project. After that, plots and results are generated automatically. Results are tables for outputs and individual parameters and plots display model observations as individual outputs and distributions.

[Demo project “1.overview – importFromMonolix_compareTreatments.smlx”]

Exploration tab simulates a typical individual. After importing a project from Monolix, individual parameters equal population parameters estimated by Monolix or their initial estimates. Using several exploration groups allows to compare different treatments. The goal of this example is to test how many days of a “loading dose” are neccesary to reach a steady state without a peak of the concentration. 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 are of manual types (with time of a dose and amount), but multi-dose elements are of regular types. The latter is an easy way to specify a treatment period, inter-dose interval and number of doses. Treatments combination takes place directly in the exploration tab.

As outputs we selected 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. Dosing regimen (and parameters) can be interactively explored and predictions are updated on-the-fly for all groups to help you find which exact regimen should be compared in the next step (simulation of a whole population).

2. Treatment comparison: percentage of individuals in the target

[Demo project “1.overview – importFromMonolix_compareTreatments.smlx”]

Simulation scenario

Simulation of a population of individuals allows to compare the percentage of individuals in the target for different treatment arms. As before, simulation scenario uses specific 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” move the treatment element from the shared section to the group specific section (green frames). 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 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.

Simulx treats these types of criteria as binary (true/false) outcomes. It is a post-processing of simulation outputs, which takes place in the  outcome&endpoint section of the Simulation tab. Definition of new outcomes includes selecting an output computed in the simulation scenario and post-processing methods.

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 calculates the efficacy and safety criteria and the number of individuals in the target in this example. Moreover, running the task 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 focuses only on one dose level with the BID and OD administration.

The goal is to analyse the effect of uncertainties due to variability between individuals, measurement errors and number of individuals in a trial.

Simulation scenario has four groups with different dosing regimens (BID or OD) and different group sizes (30 or 100). Outputs are model observations at the end of the treatment. Most importantly, the option “replicates” simulates the scenario several times (green frames). 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 (left 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%, (right 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):

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

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.

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.

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 additional lines are added in a new section EQUATION: below the structural model. The model file itself is not modified, it affects only the model used for the simulation. You cannot add new lines in the PK block, so if you need oral macro in a model with IV, you have to change the model file, save it and then reload it. 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”.

2.2.Occasions#

When the model to simulate contains inter-occasion variability (ie variability between different periods of measurements within the same individual), a single element Occasions should be defined. 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 toggle, 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

Subject-specific occasions can be defined as 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 used by Simulx. The external file can be tab, comma or semicolon separated. The possible file extensions are .csv or .txt.

Below is for example 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, an occasion element is created 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.
• 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.
• If all elements used for simulation are occasion-independent, then only the first occasion is simulated for all individuals, and inter-occasion variability is not taken into account.
• The following configuration is forbidden: several replicates, an occasion structure and sampling method different from ‘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 occassions.

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

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

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_Pop and mlx_PopInit are vectors and are common 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.

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

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.

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:

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

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.

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

• 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

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.

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.

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

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

Definition of outcomes, endpoints and group comparisons

Outcomes and endpoints are defined in the Simulation tab, in the dedicated section.

Outcomes

Outcomes represent a post-processing of the simulation outputs done for each individual. They correspond to the measure of interest per individual. Outcomes can be of 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, the user can click on the “plus” button next to Outcomes or on the “+ New outcome element” within the menu of an endpoint:

First, each outcome is given an element name, which allows to select the outcome for endpoint definition. Then, the first step is to select an output element to work on. Only the output elements selected in the Simulation section are available. The definition of the outcome includes the following options to post-process the selected output.

For continuous, count and categorical outputs:

•  Relative to baseline: divides (“ratio”) or subtracts (“difference”) the output values by the baseline (i.e the first value of the output). Because the first value of the transformed output is non-informative (ratio=1 or difference=0), it is removed.
•  Output processing average per id / max per id / min per id / first per id / last per id: takes the average, minimum, maximum, first or last over all output values (possibly divided or subtracted by the first value) for each individual. In case of minimum or maximum, the user 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. When “time of min/max” is selected, the outcome is of type ‘time-to-event’. In case occasions are used, the user can choose to compute the outcome for each individual, or for each occasion of each individual.
• Apply threshold: applies a logical test (usually comparing the outcome value to a threshold) to get a binary true/false outcome. A threshold value and a comparison sign (=, !=, >=, <=, >, <) must be set.

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 results in 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.

When creating a new outcome, the outcome can be added to a new or an existing endpoint via the option “Add to endpoint” at the bottom. Only the endpoints containing outcomes of the same type are shown.

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, one or several outcomes of the same type can be selected from the drop-down menu (green highlight below). Endpoints are also created when at the bottom of an outcome definition the option “Add to endpoint: New endpoint” is selected. Once an endpoint is created, its name can be edited (blue highlight below).

The options to summarize the individual outcomes into an endpoint depend on the type of outcomes:

• value outcomes: the endpoint can be
• geometric mean. The coefficient of variation is also calculated.
• arithmetic mean. The standard deviation is also calculated.
• median. The 5th and 95th percentiles are also calculated.
• binary true/false outcomes: the endpoint will be the percentage of true. The total number of true is also calculated.
• time-to-event outcomes: the endpoint will be the median survival (time at which the Kaplan Meier curve is equal to 0.5). The lower bound (5th) and and upper bound (95th) of the confidence interval of the median survival are also calculated.

Group comparison

The endpoints can be compared 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 perfomed in Group comparison depending on the type of outome and endpoint. Each possibility is also detailed in the next sections.

 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

One 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, a two-sided test is done (sign $$\neq$$) and one checks if the medians significantly differ from each other. Single-sided tests can be defined 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

One 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, an unpaired t-test (“Same individuals among groups” not selected) or a paired t-test (“Same individuals among groups” selected) is done to compare the test and reference group. “difference $$\neq$$ 0” represents the alternative hypothesis H1. By default, a two-sided test is done (sign $$\neq$$) and one checks if the two means significantly differ from each other. Single-sided tests can be defined 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 > 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

One 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, an unpaired t-test (“Same individuals among groups” not selected) or a paired t-test (“Same individuals among groups” selected) is done 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, a two-sided test is done (sign $$\neq$$) and one checks if the geometric means significantly differ from each other. Single-sided tests can be defined 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

One calculates the odds ratio between the test group and the reference group. The odds ratio definition is different depending if we are in a 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.

The odd ratio can be defined equivalently using the following contingency table.

“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, when 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, a Fisher’s exact test (“Same individuals among groups” not selected) or a McNemar’s exact test (“Same individuals among groups” selected) is done 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, a two-sided test is done (sign $$\neq$$) and one checks if the odds ratio significantly differs from 1. Single-sided tests can be defined 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, 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 “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

One 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, a logrank test is done to compare the survival Kaplan-Meier curves. When “Same individuals among groups” is selected, a variance correction is applied (see Jung 1999). “difference $$\neq$$ 0” represents the alternative hypothesis H1. By default, a two-sided test is done (sign $$\neq$$) and one checks if the survival curves significantly differ. Single-sided tests can be defined by choosing “>” or “<“. For the log rank test, it is not possible to define a “minimal difference”. 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 $$\neq$$ 0” results into a small p-value, it means that the survival curves from the two groups differ significantly.

Calculating the outcomes and endpoints

The outcomes, endpoints and group comparisons are calculated when clicking on the task “Outcomes&Endpoints” or when running the scenario with the task “Outcomes&Endpoints” selected. As the outcomes are a post-processing of the simulation outputs, the “Simulation” task must run first.

The calculated values are displayed in the Results tab and Plots tab.

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.

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, other replicates – one or several – can be selected in the STRATIFY sub-tab.

Output distribution

Output distribution plots show percentiles of the simulated data for all ids and all replicates computed. The binning options are available in the BINS section of the settings. DISPLAY settings allow to change plot features, such as median, number of percentiles bands and levels.

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)

4.4.Results#

The results tab displays the simulated value and their post-processing as tables.

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.

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.

• Export simulation files: The full table of simulated values can be generated 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 formatted dataset: Since the 2021 version, it is also possible to export the simulated values for all outputs as a formatted dataset in 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. It can be directly loaded in Monolix or PKanalix, for further investigations, such as non-compartmental analysis of the simulated data. The exported simulated data file is located in the result folder > Simulation > simulatedData.txt

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 .

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.

On the use of the R-functions

We now propose to use Simulx via R-functions. The package lixoftConnectors provides access to the project exactly in the same way as you would do with the interface. All the installation guidelines and initialization procedure can be found here. All the functions are described below.

Description of the functions concerning the project management

• getStructuralModel: Get the model file for the structural model used in the current project.
.
• loadProject: Load a project by parsing the Mlxtran-formated file whose path has been given as an input.
• newProject: Create a new empty project providing model and data specification.
• saveProject: Save the current project as an Mlxtran-formated file.

Examples

Handling of warning/error/info messages

Error, warning and info messages from Monolix are displayed in the R console when performing actions on a monolix project. They can be hidden via the R options. Set lixoft_notificationOptions$errors, lixoft_notificationOptions$warnings and lixoft_notificationOptions$info to 1 or 0 to respectively hide or show the messages. Example op = options() op$lixoft_notificationOptions$warnings = 1 #hide the warning messages options(op) 5.1.R-package installation and initialization# In this page, we present the installation procedure of the R-package that allow to run Simulx from R. Installation The R package lixoftConnectors is located in the installation directory as tar.gz ball. It can be installed directly using Rstudio (Tools > Install packages > from package archive file) or with the following R command: install.packages(packagePath, repos = NULL, type="source", INSTALL_opts ="--no-multiarch") with the packagePath = ‘<installDirectory>/connectors/lixoftConnectors.tar.gz’ where <installDirectory> is the MonolixSuite installation directory. With the default installation directory, the command is: # for Windows OS install.packages("C:/ProgramData/Lixoft/MonolixSuite2020R1/connectors/lixoftConnectors.tar.gz", repos = NULL, type="source", INSTALL_opts ="--no-multiarch") # for Mac OS install.packages("/Applications/MonolixSuite2020R1.app/Contents/Resources/\ monolixSuite/connectors/lixoftConnectors.tar.gz", repos = NULL, type="source", INSTALL_opts ="--no-multiarch") The lixoftConnectors package depends on the RJSONIO package that may need to be installed from CRAN first using: install.packages('RJSONIO')  Initializing When starting a new R session, you need to load the library and initialize the connectors with the following commands library(lixoftConnectors) initializeLixoftConnectors(software = "simulx")  In some cases, it may be necessary to specify the path to the installation directory of the Lixoft suite. If no path is given, the one written in the <user home>/lixoft/lixoft.ini file is used (usually “C:/ProgramData/Lixoft/MonolixSuite2020R1” for Windows). where XXXX corresponds to the version of MonolixSuite library(lixoftConnectors) initializeLixoftConnectors(software = "simulx", path = "/path/to/MonolixSuite/") Making sure the installation is ok To test if the installation is ok, you can load and run a project from the demos as on the following: # load and initialize the API library(lixoftConnectors) initializeLixoftConnectors(software=”simulx”) # Get the project demoPath = ‘<UserName>/lixoft/simulx/simulx2020R1/demos/’ project <- paste0(demoPath, “2.models/longitudinal.smlx”) loadProject(projectFile = project) # Run the simulation runSimulation() # The results are accessible through the function getSimulationResults() # The results for the output is the list res and TS is one of the outputs head(getSimulationResults()$res$TS) id time TS 1 1 0 10.00000 2 1 1 11.04939 3 1 2 12.20862 4 1 3 13.48915 5 1 4 14.90359 6 1 5 16.46585 where <UserName> is the user’s home folder (on windows C:/Users/toto if toto is your username). 5.2.Description of the functions concerning the element definition# Description of the functions of the API  defineCovariateElement Define a new covariate element. defineIndividualElement Define a new individual element. defineOccasionElement Define a new occasion element. defineOutputElement Define a new output element. definePopulationElement Define a new population element. defineRegressorElement Define a new regression element. defineTreatmentElement Define a new treatment element. deleteElement Delete an element of any type. deleteOccasionElement Delete the occasion element. getCovariateElements Get the list of all available covariate elements for the exploration and simulation. getIndividualElements Get the list of all available individual elements for the exploration and simulation. getOccasionElements Get the list of the occasion element for the simulation. getOutputElements Get the list of all available output elements for the exploration and simulation. getPopulationElements Get the list of all available population elements for the simulation. getRegressorElements Get the list of all available regressor elements for the exploration and simulation. getTreatmentElements Get the list of all available treatments elements for the exploration and simulation. [Simulx] Define covariate element Description Define a new covariate element. If can be defined as an external file or as a data.frame. If defined by a data.frame, it can contain only one row. Usage defineCovariateElement(name, element)  Arguments name (string) Element name. element (string or dataFrame) Element definition from external file path or data frame with covariates as columns. See Also  getCovariateElements Click here to see examples defineCovariateElement(name = “name”, element = “file/path”) defineCovariateElement(name = “name”, element = data.frame(WEIGHT = 70.5, SEX = “M”)) ## End(Not run) Top of the page, PKanalix API, Monolix API, Simulx API. [Simulx] Define individual element Description Define a new individual element. If can be defined an external file or as a data.frame. Usage defineIndividualElement(name, element)  Arguments name (string) Element name. element (string or dataFrame) Element definition from external file path or data frame with individual parameters as columns. See Also  getIndividualElements Click here to see examples defineIndividualElement(name = “name”, element = “file/path”) defineIndividualElement(name = “name”, element = data.frame(Cl = 1, V = 2.5)) defineIndividualElement(name = “name”, element = data.frame(Cl = c(1, 2), V = c(2.5, 5) ## End(Not run) Top of the page, PKanalix API, Monolix API, Simulx API. [Simulx] Define occasion element Description Define a new occasion element. If can be defined an external file or as a data.frame. Usage defineOccasionElement(element)  Arguments element (string or dataFrame) Element definition from external file path or data frame with time and occasion levels as columns. See Also  getOccasionElements Click here to see examples defineOccasionElement(element = “file/path”) defineOccasionElement(element = data.frame(time = c(0, 0.5, 2), occ1 = c(1, 1, 2), occ2 = c(1, 2, 3))) ## End(Not run) Top of the page, PKanalix API, Monolix API, Simulx API. [Simulx] Define output element Description Define a new output element. If can be defined an external file or as a data.frame. Usage defineOutputElement(name, element)  Arguments name (string) Element name. element (string or dataFrame) Element definition from external file path or data frame. See Also  getOutputElements Click here to see examples defineOutputElement(name = “name”, element = list(data = “file/path”, output = “output”)) defineOutputElement(name = “name”, element = list(data = data.frame(time = c(1.25, 2, 5.5)), output = “output”)) defineOutputElement(name = “name”, element = list(data = data.frame(time = c(0, 2, 3, 4, 5), occ1 = c(1, 1, 1, 2, 2), occ2 = c(1, 1, 2, 1, 2)), output = “output”)) defineOutputElement(name = “name”, element = list(data = data.frame(start = 1, interval = 10, final = 100), output = “output”)) defineOutputElement(name = “name”, element = list(data = data.frame(start = c(1, 1, 1, 1), interval = c(10, 5, 10, 5), final = c(100, 120, 150, 200)), output = “output”)) ## End(Not run) Top of the page, PKanalix API, Monolix API, Simulx API. [Simulx] Define population element Description Define a new population element. If can be defined an external file or as a data.frame. Usage definePopulationElement(name, element)  Arguments name (string) Element name. element (string or dataFrame) Element definition from external file path or data frame with population parameters as columns. See Also  getPopulationElements Click here to see examples definePopulationElement(name = “name”, element = “file/path”) definePopulationElement(name = “name”, element = data.frame(Cl_pop = 1, V_pop = 2.5)) definePopulationElement(name = “name”, element = data.frame(Cl_pop = c(1, 3), V_pop = c(2.5, 6)) ## End(Not run) Top of the page, PKanalix API, Monolix API, Simulx API. [Simulx] Define regressor element Description Define a new regression element. If can be defined an external file or as a data.frame. Usage defineRegressorElement(name, element)  Arguments name (string) Element name. element (string or dataFrame) Element definition from external file path or data frame with time and regressors as columns. See Also  getRegressorElements Click here to see examples defineRegressorElement(name = “name”, element = “file/path”) defineRegressorElement(name = “name”, element = data.frame(time = c(0, 0.5, 2), reg1 = c(1, 2, 5.25), reg2 = c(0, 0.25, 1))) defineRegressorElement(name = “name”, element = data.frame(time = c(0, 0.5, 2, 5, 6), reg1 = c(1, 2, 5.25, 6, 7), reg2 = c(0, 0.25, 1, 2, 3), occ1 = c(1,1,1,2,2), occ2 = c(1,1,2,1,2))) ## End(Not run) Top of the page, PKanalix API, Monolix API, Simulx API. [Simulx] Define treatment element Description Define a new treatment element. If can be defined an external file or as a data.frame. Usage defineTreatmentElement(name, element)  Arguments name (string) Element name. element (string or dataFrame) Element definition from external file path or data frame. Note admID, repeat and probaMissDose are optional. In data, tInf and washout are optional. See Also  getTreatmentElements Click here to see examples defineTreatmentElement(name = “name”, element = list(data = “file/path”)) defineTreatmentElement(name = “name”, element = list(probaMissDose=0, admID=1, repeats=c(cycleDuration = 1, NumberOfRepetitions=12), data=data.frame(time=c(1,2), amount=c(1,2), tInf=c(0, 1), washout=c(TRUE, FALSE)))) defineTreatmentElement(name = “name”, element = list(probaMissDose=0, admID=1, repeats=c(cycleDuration = 1, NumberOfRepetitions=12), data=data.frame(time=c(10,10,10,10), amount=c(10,20,30,40), occ1=c(1,1,2,2), occ2=c(1,2,1,2)))) defineTreatmentElement(name = “name”, element = list(probaMissDose=0, admID=1, repeats=c(cycleDuration = 1, NumberOfRepetitions=12), data=data.frame(start=1, interval=2, nbDoses=10, amount=1))) ## End(Not run) Top of the page, PKanalix API, Monolix API, Simulx API. [Simulx] Delete element Description Delete an element of any type. Usage deleteElement(name)  Arguments name (string) Element name. Click here to see examples deleteElement(name = “name”) ## End(Not run) Top of the page, PKanalix API, Monolix API, Simulx API. [Simulx] Delete occasion element Description Delete the occasion element. Usage deleteOccasionElement()  Click here to see examples deleteOccasionElement() ## End(Not run) Top of the page, PKanalix API, Monolix API, Simulx API. [Simulx] Get covariate elements Description Get the list of all available covariate elements for the exploration and simulation. Each element is a list of  “inputType” (string) Type of input definition: can be “manual”, “distribution” or “external”. “file” (string) Path to the file if the inputType is external. NULL else wise. “data” (data.frame) Values of the element. Notice that: – if the project was created from a model file, an covariate element Covariates is created with all values equal 1. – if the project was created using a Monolix project, – an covariate element mlx_Cov is created with the values corresponding of the covariates values of the project. – an covariate element mlx_CovDist is created with the values corresponding of the esimation of the distribution of the covariates of the project. Usage getCovariateElements()  See Also  defineCovariateElement Click here to see examples getCovariateElements()$mlx_Cov

#’$mlx_Cov$inputType

[1] “external”

$mlx_Cov$file

[1] path/to/file

$mlx_Cov$data

id WEIGHT

1 1 79.6

2 2 72.4

3 3 70.5

4 4 72.7

5 5 54.6

$covMan$covMan$inputType [1] “manual”$covMan$file NULL$covMan$data id WEIGHT 1 common 75 ## End(Not run) Top of the page, PKanalix API, Monolix API, Simulx API. [Simulx] Get individual elements Description Get the list of all available individual elements for the exploration and simulation. Each element is a list of  “inputType” (string) Type of input definition: can be “manual” or “external”. “file” (string) Path to the file if the inputType is external. NULL else wise. “data” (data.frame) Values of the element. Notice that: – if the project was created from a model file, an individual element IndivParameters is created with all values equal 1. – if the project was created using a Monolix project, – an individual element mlx_IndivInit is created with the values corresponding of the initial population parameters if the population parameters were not estimated. – an individual element mlx_PopIndiv is created with the values corresponding of the estimated population parameters (without the covariate(s) impact(s)) if the population parameters were estimated. – an individual element mlx_PopIndivCov is created with the values corresponding of the estimated population parameters (with the covariate(s) impact(s)) if the population parameters were estimated. – an individual element mlx_EBEs is created with the values corresponding of the estimated EBEs if the EBEs were estimated. – an individual element mlx_CondMean is created with the values corresponding of the estimated conditional mean if the conditional distribution task was perfored. – an individual element mlx_CondDistSample is created with the values corresponding of the first sample of the conditional ditribution if the conditional distribution task was perfored. Usage getIndividualElements()  See Also  defineIndividualElement Click here to see examples getIndividualElements()$mlx_PopIndiv

$mlx_PopIndiv$inputType

[1] “manual”

$mlx_PopIndiv$file

NULL

$mlx_PopIndiv$data

id Cl V1 Q2 V2 Q3 V3

1 common 2.462069 4.557752 0.1151846 4.355022 1.70242 8.229753

$mlx_EBEs$mlx_EBEs$inputType [1] “external”$mlx_EBEs$file [1] file/to/path$mlx_EBEs$data id Cl V1 Q2 V2 Q3 V3 1 1 2.870556 5.801418 2.12758339 5.963084 0.6649303 13.069996 2 2 2.899189 4.443222 0.31646327 5.226719 2.3678264 9.182623 ## End(Not run) Top of the page, PKanalix API, Monolix API, Simulx API. [Simulx] Get occasion elements Description Get the list of the occasion element for the simulation. It is a list of  “id” (string) Ids of the occastions “names” (string) Name of the occasions. “times” (data.frame) Times of the occasions. “occasions” (data.frame) Values of the element. Usage getOccasionElements()  See Also  defineOccasionElement [Simulx] Get output elements Description Get the list of all available output elements for the exploration and simulation. Each element is a list of  “output” (string) Output name. “inputType” (string) Type of input definition: can be “manual” or “external”. “file” (string) Path to the file if the inputType is external. NULL else wise. “data” (data.frame) Values of the element. Importantly, all the variables in the model file can be used as an output. The user is not consrtrained to the ones defined in the OUTPUT: section. Notice that: – if the project was created from a model file, an outpout element is created for each output of the section OUTPUT: with regular grid from 0 to 100 by 1. – if the project was created using a Monolix project, with for exemple CC as a predicition and y as measurement – an individual element mlx_y1 is created as an external file with the values corresponding of the output values for each id of the project. – an individual element mlx_Cc is created with a regular grid starting from the first time measurement of the project to the final time measurement of the project. Usage getOutputElements()  See Also  defineOutputElement Click here to see examples$output

[1] “y1”

$inputType [1] “manual”$file

NULL

$data id time 1 common 0 2 common 1 3 common 2 ## End(Not run) Top of the page, PKanalix API, Monolix API, Simulx API. [Simulx] Get population elements Description Get the list of all available population elements for the simulation. Each element is a list of  “inputType” (string) Type of input definition: can be “manual” or “external”. “file” (string) Path to the file if the inputType is external. NULL else wise. “data” (data.frame) Values of the element. Notice that: – if the project was created from a model file, a population element PopParameters is created with all values equal 1. – if the project was created using a Monolix project, – a population element mlx_Pop is created with the values corresponding of the Monolix estimated population parameters. – a population element mlx_PopInit is created with the values corresponding of the Monolix initial population parameters if the parameters were not estimated. Usage getPopulationElements()  See Also  definePopulationElement Click here to see examples getPopulationElements()$mlx_Pop

$mlx_Pop$inputType

[1] “manual”

$mlx_Pop$file

NULL

$mlx_Pop$data

id Cl_pop V1_pop Q2_pop V2_pop Q3_pop V3_pop omega_Cl omega_Q2 omega_Q3 omega_V1 omega_V2 omega_V3 b

1 common 2.462069 4.557752 0.1151846 4.355022 1.70242 8.229753 0.2272315 0.92641 0.5745623 0.4080015 0.8127517 0.4464604 0.1106325

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Get regressor elements

Description

Get the list of all available regressor elements for the exploration and simulation.
Each element is a list of

 “inputType” (string) Type of input definition: can be “manual” or “external”. “file” (string) Path to the file if the inputType is external. NULL else wise. “data” (data.frame) Values of the element.

Usage

getRegressorElements()


 defineRegressorElement

$inputType [1] “manual”$file

NULL

$data id time 1 common 0 2 common 1 3 common 2 ## End(Not run) Top of the page, PKanalix API, Monolix API, Simulx API. [Simulx] Get treatment elements Description Get the list of all available treatments elements for the exploration and simulation. Each element is a list of  “inputType” (string) Type of input definition: can be “manual” or “external”. “file” (string) Path to the file if the inputType is external. NULL else wise. “data” (data.frame) Values of the element. Notice that: – if the project was created from a model file, no treatment is added. – if the project was created using a Monolix project, for each administraion type of the project, – an individual element mlx_adm is created as an external file with the values corresponding of the treatment values for each id of the project. Usage getTreatmentElements()  See Also  defineTreatmentElement Click here to see examples ## Not run:$mlx_Adm1

$mlx_Adm1$inputType

[1] “external”

$mlx_Adm1$file

[1] path/to/file

$mlx_Adm1$data

id time amount washout

1 1 0 320 FALSE

2 2 0 320 FALS

## End(Not run)

}

Top of the page, PKanalix API, Monolix API, Simulx API.

Description of the functions of the API

 getStructuralModel Get the model file for the structural model used in the current project. isProjectLoaded Check if the project is loaded loadProject Load a project by parsing the Mlxtran-formated file whose path has been given as an input. newProject Create a new empty project providing model and data specification. saveProject Save the current project as an Mlxtran-formated file.

[Monolix – PKanalix – Simulx] Get structural model file

Description

Get the model file for the structural model used in the current project.
For Simulx, this function will return the structural model only if the project was imported from Monolix, and NULL otherwise.

Usage

getStructuralModel()


Value

A string corresponding to the path to the structural model file.

 setStructuralModel

getStructuralModel() => “/path/to/model/inclusion/modelFile.txt”

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Monolix – PKanalix – Simulx] Get current project load status

Description

[Monolix – PKanalix – Simulx] Get current project load status

Usage

isProjectLoaded()


Value

TRUE if a project is currently loaded, FALSE otherwise

[Monolix – PKanalix – Simulx] Load project from file

Description

Load a project by parsing the Mlxtran-formated file whose path has been given as an input.
The extensions are .mlxtran for Monolix, .pkx for PKanalix, and .smlx for Simulx.
WARNING: R is sensitive between ‘\’ and ‘/’, only ‘/’ can be used.

Usage

loadProject(projectFile)


Arguments

projectFile(character) Path to the project file. Can be absolute or relative to the current working directory.See Also saveProject

Top of the page, PKanalix API, Monolix API, Simulx API.
[Monolix – PKanalix – Simulx] Create new projectDescriptionCreate a new empty project providing model and data specification. The data specification is:

Monolix, PKanalix

• dataFile (string): path to the data file
• observationTypes [optional] (list): a list, indexed by observation name, giving the type of each observation present in the data file. If omitted, all the observations will be considered as “continuous”
• nbSSDoses (int): number of steady-state doses (if there is a SS column)
• mapping [optional](list): a list giving the observation name associated to each y-type present in the data file
(this field is mandatory when there is a column tagged with the “obsid” headerType)

Please refer to  setData documentation for a comprehensive description of the “data” argument structure.

Monolix only

• projectFile (string): path to the datxplore or pkanalix project file defining the data

UsagenewProject(modelFile = NULL, data = NULL) ArgumentsmodelFile(character) Path to the model file. Can be absolute or relative to the current working directory.To use a model from the libraries, you can set modelFile = “lib:modelName.txt”, e.g. modelFile = “lib:oral1_1cpt_kaVCl.txt”data
(list) Structure describing the data.
In case of PKanalix, data is mandatory and modelFile is optional (used only for the CA part and must be from the library).
In case of Monolix, data and modelFile are mandatory. It can be replaced by a projectFile corresponding to a Datxplore or PKanalix project file.
In case of Simulx, modelFile is mandatory and data = NULL. It can be replaced by a projectFile corresponding to a Monolix project. In that case, the Monolix project will be imported into Simulx.See Also newProject saveProject

newProject(data = list(dataFile = “/path/to/data/file.txt”,headerTypes = c(“IGNORE”, “OBSERVATION”),observationTypes = “continuous”),modelFile = “/path/to/model/file.txt”)newProject(data = list(dataFile = “/path/to/data/file.txt”,headerTypes = c(“IGNORE”, “OBSERVATION”, “OBSID”),observationTypes = list(concentration = “continuous”, effect = “discrete”),mapping = list(“1” = “concentration”, “2” = “effect”)),modelFile = “/path/to/model/file.txt”)[Monolix only]newProject(data = list(projectFile = “/path/to/project/file.datxplore”),modelFile = “/path/to/model/file.txt”)[Simulx only]newProject(modelFile = “/path/to/model/file.txt”)new project from an import of a structural modelnewProject(modelFile = “/path/to/monolix/project/file.mlxtran”)new project from an import of a monolix model## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.
[Monolix – PKanalix – Simulx] Save current projectDescriptionSave the current project as an Mlxtran-formated file.
The extensions are .mlxtran for Monolix, .pkx for PKanalix, and .smlx for Simulx.
WARNING: R is sensitive between ‘\’ and ‘/’, only ‘/’ can be used.UsagesaveProject(projectFile = "") ArgumentsprojectFile[optional](character) Path where to save a copy of the current mlxtran model. Can be absolute or relative to the current working directory.If no path is given, the file used to build the current configuration is updated.See Also newProject loadProject

[PKanalix only]saveProject(“/path/to/project/file.pkx”) # save a copy of the model[Monolix only]saveProject(“/path/to/project/file.mlxtran”) # save a copy of the model[Simulx only]saveProject(“/path/to/project/file.smlx”) # save a copy of the model[Monolix – PKanalix – Simulx]saveProject() # update current model## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

Description of the functions of the API

 getAddLines Get the lines that were added to a model. importMonolixProject Import all the elements coming from a Monolix project. setAddLines Lines that can be added to the model file.

[Simulx] Get lines added to the model

Description

Get the lines that were added to a model.

Usage

getAddLines()


 setAddLines

=> “ddt_AUC = Cc”

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Import project from Monolix

Description

Import all the elements coming from a Monolix project. It imports
– the model file,
– the population parameters (if estimated, else wise an element is created with all values at 1),
– the individual parameters (if estimated, else wise an element is created with all values at 1),
– the outputs as an external element,
– the treatments (if any) as an external element,
– the regressors (if any) as an external element,
– the occasion structure (if any) as an external element.

Usage

importMonolixProject(projectFile)


Arguments

projectFile
(string) Path to the project file. Can be absolute or relative to the current working directory.

Details

WARNING: R is sensitive between ‘\’ and ‘/’, only ‘/’ can be used.

importfrommonolix(“/path/to/project/file.mlxtran”) for Linux platform

importfrommonolix(“C:/Users/path/to/project/file.mlxtran”) for Windows platform

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Add lines to the model

Description

Lines that can be added to the model file. The goal is to complete/add new element in the model without rewriting it from scratch.
Notice that all the variable defined in the add lines will be available as an output.

Usage

setAddLines(lines)


Arguments

lines

 getAddLines

setAddLines(c(“if t>24”, “ddt_AUC = Cc”, “end”))

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

Description of the functions of the API

 exportSimulatedData Export the simulated data set into Lixoft suite compatible format. getSimulationResults Get the results of the simulation.

[Simulx] Export simulated data

Description

Export the simulated data set into Lixoft suite compatible format.
It contains simulation results and can be generated only when simulation results are available.
The file is written in the results folder of the current project.de

Usage

exportSimulatedData()


runSimulation

exportSimulatedData()

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Get simulation results

Description

Get the results of the simulation.
The output is a list of two elements: res and IndividualParameters.

A first element called res is provided. It corresponds to the list of the output(s) of the simulation. There is a data frame for each output with the columns id, time, outputName, and group (corresponding to the group name if there are several groups).
A second element called IndividualParameres is provided. It corresponds to the list of data.frame. Each data.frame of the list corresponds to the individual parameters for each group.

Usage

getSimulationResults(id = NULL, rep = NULL)


Arguments

id
[optional](string) If provided, results are retrieved only for this id.

rep
[optional](int) If provided, results are retrieved only for this replicate.

runSimulation

getSimulationResults()

getSimulationResults(id = “1”, rep = 10)

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

Description of the functions of the API

 computeChartsData Compute and export the charts data of scenario.

[Monolix – PKanalix – Simulx] Compute the charts data

Description

Compute and export the charts data of scenario.
Notice that it does not impact the current scenario.

Usage

computeChartsData(exportVPCSimulations = FALSE)


Arguments

exportVPCSimulations(bool) [optional][Monolix] Should VPC simulations be exported if available. Equals FALSE by default.

computeChartsData()## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

Description of the functions of the API

 addGroup Add a new simulation group. getGroupRemaining Get the values of the remaining elements (coming from the observation model) for a group. getGroups Get the structure of each simulation group. getNbReplicates Get the number of replicates. getSameIndividualsAmongGroups Get the informations if the same individuals are simulated among all groups. getSamplingMethod Define which sampling methods is used for the simulation. getSharedIds Get the elements for the shared group. removeGroup Remove a simulation group. removeGroupElement Remove an element of the simulation. renameGroup Rename a simulation group. runSimulation Run the simulation task. setGroupElement Set the new element of a specific group. setGroupRemaining Set the values of the remaining elements (coming from the observation model) for a group. setGroupSize Define the size of a simulation group. setNbReplicates Define the number of replicates of the simulation. setSameIndividualsAmongGroups Define if the same individuals will be simulated among all groups. setSamplingMethod Define which sampling methods will be used for the simulation. setSharedIds Set the elements for the shared group.

Usage

addGroup(group)


Arguments

group
(string) Name of the group to add.

 getGroups

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Get simulation group remaining

Description

Get the values of the remaining elements (coming from the observation model) for a group.

Usage

getGroupRemaining(group)


Arguments

group
(character) Group name

 setGroupRemaining

getGroupRemaining( group = “arm1” )

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Get simulation groups

Description

Get the structure of each simulation group. Each group is defined as a list of all its elements (population parameters, …) .

Usage

getGroups()


 addGroup

getGroups()

[[1]]

[[1]]$name [1] “simulationGroup1” [[1]]$covariate

[1] “mlx_Cov”

[[1]]$parameter [[1]]$parameter$type [1] “population” [[1]]$parameter$name [1] “mlx_Pop” [[1]]$treatment

[[1]]$output [1] “mlx_y1” [[1]]$size

[1] 12

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Get number of replicates

Description

Get the number of replicates.

Usage

getNbReplicates()


 setNbReplicates

getNbReplicates()

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Get same individuals among groups

Description

Get the informations if the same individuals are simulated among all groups.

Usage

getSameIndividualsAmongGroups()


 setSameIndividualsAmongGroups

getSameIndividualsAmongGroups()

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Get sampling method

Description

Define which sampling methods is used for the simulation. The possibilities are to keep the order, sample with replacement and sample without replacement.

Usage

getSamplingMethod()


 setSamplingMethod

getSamplingMethod()

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Get simulation groups sharedIds

Description

Get the elements for the shared group.

Usage

getSharedIds()


 setSharedIds

getSharedIds()

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Remove simulation group

Description

Remove a simulation group.

Usage

removeGroup(group)


Arguments

group
(string) Name of the group to remove.

getGroups,addGroup

removeGroup(“group”)

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Remove element from simulation group

Description

Remove an element of the simulation.

Usage

removeGroupElement(group, element)


Arguments

group
(character) Group name

element
(character) Element to remove

removeGroupElement(group = “group”, element = “element”)

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Rename simulation group

Description

Rename a simulation group.

Usage

renameGroup(currentGroupName, newGroupName)


Arguments

currentGroupName
(string) Name of the current group name.

newGroupName
(string) Name of the new group name.

 getGroups

renameGroup(“currentGroupName”, “newGroupName”)

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Run simulation

Usage

runSimulation()


getSimulationResults

[Simulx] Set elements to simulation group

Description

Set the new element of a specific group.

Usage

setGroupElement(group, elements)


Arguments

group
(character) Group name

elements
(character) Vector of new elements that are already defined

 getGroups

setGroupElement(group = “group”, newElement = c(“element1”, “element2”))

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Set simulation group remaining

Description

Set the values of the remaining elements (coming from the observation model) for a group.

Usage

setGroupRemaining(group, remaining)


Arguments

group
(character) Group name

remaining
(vector) list of the remaining variables

 getGroupRemaining

setGroupRemaining(group=”arm1”, remaining = list(a = 12, b = 3))

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Set simulation group size

Description

Define the size of a simulation group.

Usage

setGroupSize(group, size)


Arguments

group
(string) Name of the group where the size will be changed.

size
(int) Size of the new group.

 getGroups

setGroupSize(“group”, 10)

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Set number of replicates

Description

Define the number of replicates of the simulation.

Usage

setNbReplicates(nb)


Arguments

nb
(int) Number of replicates.

 getNbReplicates

setNbReplicates( nb = 1 )

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Set same individuals among groups

Description

Define if the same individuals will be simulated among all groups.

Usage

setSameIndividualsAmongGroups(value)


Arguments

value
(boolean) Boolean to define if the same individuals will be the same for all groups.

 getSameIndividualsAmongGroups

setSameIndividualsAmongGroups( value = TRUE )

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Set sampling method

Description

Define which sampling methods will be used for the simulation. The possibilities are to keep the order, sample with replacement and sample without replacement.

Usage

setSamplingMethod(method)


Arguments

method
(character) keepOrder, withReplacement, withoutReplacement

 getSamplingMethod

setSamplingMethod( method = “” )

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Simulx] Set simulation groups sharedIds

Description

Set the elements for the shared group.

Usage

setSharedIds(sharedIds)


Arguments

sharedIds
(vector<string>) List of element types. The available types are: covariate, output, treatment, regressor, population, individual

 getSharedIds

setSharedIds( sharedIds = c(“output”, “treatment”) )

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

Description of the functions of the API

 getPreferences Get a summary of the project preferences. getProjectSettings Get a summary of the project settings. setPreferences Set the value of one or several of the project preferences. setProjectSettings Set the value of one or several of the settings of the project.

[Monolix – PKanalix – Simulx] Get project preferences

Description

Get a summary of the project preferences. Preferences are:

 “relativepath” (bool) Use relative path for save/load operations. “threads” (int >0) Number of threads. “timestamping” (bool) Create an archive containing result files after each run. “delimiter” (string) Character use as delimiter in exported result files. “exportchartsData” (bool) Should graphics data be exported. “exportsimulationfiles” (bool) [Simulx] Should simulation results files be exported. “headeraliases” (list("header" = vector)) For each header, the list of the recognized aliases. “ncaparameters” (vector) [PKanalix] Defaulty computed NCA parameters.

Usage

getPreferences(...)


Arguments

[optional] (string) Name of the preference whose value should be displayed. If no argument is provided, all the preferences are returned.

Value

An array which associates each preference name to its current value.

getPreferences() # retrieve a list of all the general settings

getPreferences(“imageFormat”,”exportCharts”)

# retrieve only the imageFormat and exportCharts settings values

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Monolix – PKanalix – Simulx] Get project settings

Description

Get a summary of the project settings.
Associated settings for Monolix projects are:

 “directory” (string) Path to the folder where simulation results will be saved. It should be a writable directory. “exportResults” (bool) Should results be exported. “seed” (0< int <2147483647) Seed used by random generators. “grid” (int) Number of points for the continuous simulation grid. “nbSimulations” (int) Number of simulations. “dataAndModelNextToProject” (bool) Should data and model files be saved next to project.

Associated settings for PKanalix projects are:

 “directory” (string) Path to the folder where simulation results will be saved. It should be a writable directory. “dataNextToProject” (bool) Should data files be saved next to project.

Associated settings for Simulx projects are:

 “directory” (string) Path to the folder where simulation results will be saved. It should be a writable directory. “seed” (0< int <2147483647) Seed used by random generators. “userfilesnexttoproject” (bool) Should user files be saved next to project.

Usage

getProjectSettings(...)


Arguments

[optional] (string) Name of the settings whose value should be displayed. If no argument is provided, all the settings are returned.

Value

An array which associates each setting name to its current value.

 getProjectSettings

getProjectSettings() # retrieve a list of all the project settings

getProjectSettings(“directory”,”seed”)

# retrieve only the directopry and the seed settings values

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Monolix – PKanalix – Simulx] Set preferences

Description

Set the value of one or several of the project preferences. Prefenreces are:

 “relativepath” (bool) Use relative path for save/load operations. “threads” (int >0) Number of threads. “timestamping” (bool) Create an archive containing result files after each run. “delimiter” (string) Character use as delimiter in exported result files. “exportchartsData” (bool) Should graphics data be exported. “exportsimulationfiles” (bool) [Simulx] Should simulation results files be exported. “headeraliases” (list("header" = vector)) For each header, the list of the recognized aliases. “ncaparameters” (vector) [PKanalix] Defaulty computed NCA parameters.

Usage

setPreferences(...)


Arguments

A collection of comma-separated pairs {preferenceName = settingValue}.

 getPreferences

setPreferences(exportCharts = FALSE, delimiter = “,”)

## End(Not run)

Top of the page, PKanalix API, Monolix API, Simulx API.

[Monolix – PKanalix – Simulx] Set project settings

Description

Set the value of one or several of the settings of the project.
Associated settings for Monolix projects are:

 “directory” (string) Path to the folder where simulation results will be saved. It should be a writable directory. “exportResults” (bool) Should results be exported. “seed” (0< int <2147483647) Seed used by random generators. “grid” (int) Number of points for the continuous simulation grid. “nbSimulations” (int) Number of simulations. “dataAndModelNextToProject” (bool) Should data and model files be saved next to project.

Associated settings for PKanalix projects are:

 “directory” (string) Path to the folder where simulation results will be saved. It should be a writable directory. “dataNextToProject” (bool) Should data files be saved next to project.

Associated settings for Simulx projects are:

 “directory” (string) Path to the folder where simulation results will be saved. It should be a writable directory. “seed” (0< int <2147483647) Seed used by random generators. “userfilesnexttoproject” (bool) Should user files be saved next to project.

Usage

setProjectSettings(...)


Arguments

A collection of comma-separated pairs {settingName = settingValue}.

 getProjectSettings