Simulx single page documentation

1.Overview #

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.

 Composition of thee parts of simulx: definition, exploration and simulation.

How does it work?

Start with:

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

Home tab of the Simulx interface with three methods to start a project: add new project, open project and import from Monolix.

  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 used in 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.
  • 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) log normal distribution of covariates from the dataset with empirical mean and variance for continuous covariates and multinomial low based on frequencies of modalities for categorical covariates.
  • treatment:
    • mlx_AdmID: (table) ids, amounts and dosing times (+ tinf/rate or washouts) read from the dataset for each administration type.
  • outputs:
    • mlx_observationName: (table) ids and measurement times read from the dataset for each output of the observation model
    • mlx_predictionName: (vector) uniform time grid with 250 points on the same time interval as the observations for each continuous output of the structural model.
    • mlx_TableName: (vector) uniform time grid with 250 points on the same time interval as the observations for each variable of the structural model defined as table in the OUTPUT block.
  • occasions:
    • mlx_Occ [if used in the model]: (table) ids, times and occ(s) read from the dataset.
  • regressors
    • mlx_Reg [if used in the model]: (table) ids, times and regressor values and names read from the dataset.

Default exploration and simulation scenarios

Exploration:

  • Indiv.params: mlx_IndivInit or mlx_PopIndiv.
  • Treatment: one exploration group with mlx_AdmId for all administration IDs.
  • Output: mlx_predictionName for all predictions defined in the model.

Simulation:

  • Size: number of individuals read from the dataset.
  • Parameters: mlx_PopInit or mlx_Pop.
  • Treatment: mlx_AdmId for all administration IDs.
  • Output: mlx_observationName for all observations.
  • Covariates: mlx_cov if used in the model.
  • Regressor: mlx_reg if used in the model.

Interface allows to have an overview on all defined elements, modify them and create new ones as well as build simulation scenarios. But, 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

[Demo projects: 1.overview – importFromMonolix]

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:

  • Which “loading dose” strategy assures a rapid steady state without a concentration peak?
  • Do multi-dose treatments meet the efficacy and safety criteria?
  • What is the uncertainty of the percentage of individuals in a target due to the variability between individuals and due to the size of a trial group?

Model:
The PK model includes an administration with a first order absorption and a lag time. It has one compartment and a linear elimination. The PD model is an indirect turnover model with inhibition of the production. All individual parameters have log-normal distribution besides the Imax parameter, which is logitNormally distributed. In addition, the log-transformed scaled weight covariate explains intra-individual variability of the volume, age covariate has an effect on the clearance and sex covariate on the baseline response. Finally, the combined-1 error model is used in the observation model of the concentration, and the constant model of the response.

0. Re-simulation of the Monolix project

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.

  

1. Exploration of the loading dose strategies

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:

  • 14 days with a 4mg single dose OD
  • 1 day with a load dose 8mg OD followed by 13 days with a 4mg single dose OD
  • 2 days with load doses 8mg OD followed by 12 days with a 4mg single dose OD

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

Output is the concentration prediction on a regular time grid over the whole treatment period (t = 0:1:336) and the plot displays all exploration groups together. The two-days loading dose gives a high concentration peak and without a loading dose the steady state is reached too slowly. As a result, further analysis focuses on treatments with one day of a loading dose.

2. Treatment comparison: percentage of individuals in the target

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

What is more, 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 then half of the individuals have Ctrough below the safety threshold (blue frame below).

3. Clinical trial simulation and uncertainty of the results

The previous step shows that the high dose level violates the safety criteria in more then 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.

[In the demo project, 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 then 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 then selected 0.05, then a test group (GR_OD_N30) is a “success”. Results summary in the “group comparison” section shows that only 3% of the test group replicates are successful (left image below), which suggests that OD dosing regimen is not significantly better then BID. Larger trial size might give different results. Change reference group to gr_BID_N100 et re-run the outcomes&endpoints task. Percentage of successful replicates for gr_OD_N100 is higher, 9%, (right image below), but it is comparable to the previous result.

 

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.
    New covariate element pop-up window. Covariate called cov_healthy of the distribution type. Weight is a continuous covariate with log-normal distribution around atypical value. Patient is a categorical covariate with two modalities: probability 1 for the HV-healthy-volunteers and probability 0 for the RA-patients with rheumatoid arthritis.
  • 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.
    New treatment element pop-up window. Treatment called trt_amt3 of a regular type. Treatment starts at time equal to zero. Interdose interval is 1 day. There are 7 doses. It is followed by 7 days without a treatment, which is defined by using a cycle of length 14. The cycle is repeated once. An option scale-by-covariate multiplies the amount of a dose by weight.
  • 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).

Simulx interface of the exploration tab. There is one exploration group with 3 mg per kg dose level. The plot shows the ration of the free receptor to the baseline during the whole treatment period. The reference curve corresponds to the receptor synthesis rate of healthy individuals. The second curve, with higher values of the ratio, corresponds to the rate three times larger.

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.

Simulx interface of the Simulation tab. A scenario is composed of 6 groups for three dose levels and two population types. Group size, population parameters and the output are in the shared section. Covariate dependent treatment and covariates element are group specific.

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

Definition of an endpoint. It has one outcome, which is true if the ratio between the free receptor and the baseline is below 10 percent. The endpoint gives the percentage of individual with true outcomes. Option group comparison is on. It is a direct comparison with odds ratio to be larger than 0.6. The lowest dose healthy group is the reference.

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.

Simulx interface of the plots tab with the outcome distribution chart. Stacked representation of the outcomes is selected, with true outcomes at the bottom and false outcomes on top.

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.

Simulx interface of the results tab with the group comparison section. All tests groups for healthy individuals are marked as a success. Only the highest dose level group for unhealthy patients is marked as a success.

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.

Definition of simulation elements: create new element, view it, edit, duplicate or delete.

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.

 

Loading or modifying a model

Several buttons are available on the top of the page to load or modify a model:

  • Browse: to load a new model file by browsing if from the computer.
  • Load from library: to load a model from the built-in libraries. Note that all models from the libraries contain only structural models ([LONGITUDINAL] block) with no individual models for the parameters or covariates.
  • Reload: to reload the same model after modifying it using the built-in editor or with any text editor.
  • Open in editor: to opens the current model in the built-in editor.

Loading or updating a model with the buttons “Browse”, “Load from library” or “Reload” deletes all definition elements to avoid incompatibilities with previously defined elements and the new model.

 

Model imported from Monolix

When importing a model from Monolix, the model that appears in the interface of Monolix comes from two sources:

  • The structural model ([LONGITUDINAL] block) used in the Monolix project, copied in a new file stored in the result folder of the Simulx project, in a subfolder names ModelFile/.
  • The [INDIVIDUAL] and (if there are covariates in the model) [COVARIATE] blocks, derived from the statistical model set up in Monolix, saved directly in the .smlx file.

 

Warning: When opening a model in the editor with “Open in editor”, only the new structural model file is opened for modifications. If this model is changed and reloaded, it will replace the two model sources mentioned above. It means that the [INDIVIDUAL] and [COVARIATE] blocks are removed. To keep these blocks in the modified model, they have to be pasted in the file together with the [LONGITUDINAL] block.

 

Additional lines

Below a model definition, there is a field to write additional lines, which are included “on the fly” in the model. This is convenient for example to define new variables for simulations, 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.

 

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

Both of these elements are vectors and are common for all ids.

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 (if the distribution is lognormal or logitnormal, sd is the standard deviation of the distribution in the Gaussian space), or uniform with two interval limits. 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.

2.6.Treatments #

Treatments definition includes times and amounts of the doses applied to the model. Treatments are applied to the model via the macros depot(), iv() or oral() used in the model. Moreover, treatments definition has an administration id, which allows to choose to which macros used in the model the doses are applied.

When used in “Exploration” or “Simulation“, several treatment elements can be combined together.  For instance, a loading dose of type manual followed by maintenance doses of type regular, or a oral dose with adm=2 and an iv dose with adm=1.

The units of time and amounts must be consistent with the units of the Monolix data set or with the model definition when starting from scratch.






Demo projects: 3.1. treatments


New treatments element

Several types of elements can be defined:

  • Regular: It is used for regularly spaced dosing times with a unique amount and a unique infusion duration or rate (optional). It requires the start time, inter-dose internal, number of doses, and amount.
  • Manual: It is a vector that has one or several dosing times with identical or different amounts. The + and – buttons allow to add and remove doses.
  • External: An external text file with columns id (optional), occasions (optional), time (mandatory), amount (mandatory), tinf or rate (optional), washout (optional). The occasions headers must correspond to the occasion names defined in the occasion element. When id and occasion columns are present, then they must be the first columns. When the id column is not present, the treatment is considered ‘common’, i.e the same for all individuals. The washout column can contain zeros (no washout) or ones (washout).

    The external file can be tab, comma or semicolon separated. The possible file extensions are .csv or .txt.

 

Additional treatments definition specifications:

  • adm: [all] the administration id of the treatment element (integer). The doses of a treatment element with adm=2 apply to all model macros defined with adm=2, for instance oral(adm=2, ka). Macros used in the model without adm are implicitly defined with adm=1.
  • infusion duration or rate: [regular/manual] the list button on the right allows to display the infusion column. The value is understood as either a duration or a rate, depending on the chosen option.
  • washout: [manual] the list button on the right allows to display the washout column. When the washout tick-box is selected, a washout is applied just before the dose. A washout means that all model variables are reset to their initial values.
  • repeat: [regular/manual] This option allows to repeat a base pattern of doses several times (number of repetitions), with a given periodicity (cycle duration). In the example below, the dose is given on the three first days of the week, for 4 weeks. The doses on the first week are defined using the type ‘regular’ with three doses and an inter-dose interval of 1 day. This base pattern is then repeated every 7 days (cycle duration), 3 times (number of repetitions) in addition to the first week.
  • scale amount by a covariate: [regular/manual] This option allows to personalize the dose given to different individuals by scaling the dose amount with the selected covariate and with a specific intercept for the linear relationship: \(\text{Scaled amount} = \text{Amount} \times \text{Selected covariate} + \text{Intercept}\).

non-compliance probability: [all] The doses defined are applied to the model with a given probability (1-p) , where p is the probability to miss a dose. This allows to simulate non-adherence to a treatment. Which doses are applied and which are not rely on the random number seed defined in the project settings to ensure reproducibility.

Treatment elements imported from Monolix

Importing a Monolix project generates automatically a treatment element for each administration id defined in the Monolix data set.

  • mlx_AdmX: contains treatment information for admID=X for each individual including: dosing times, amount, infusion duration or rates (optional) and washouts (optional, from EVID=3 or EVID=4 in Monolix). The Monolix data set column SS is replaced by additional dose lines as defined by the Monolix setting “number of steady-state doses”. The ADDL column is also replaced by additional dose lines.

2.7.Outputs #

Outputs of simulations are variables from the longitudinal model of continuous, discrete or event type. There are two outputs groups:

  • Main outputs
    • Model predictions defined in the structural model as the “output” (eg. Cc).
    • Observations (model predictions with an error model) defined in the observation model (eg. y1).
    • All variables defined in the structural model as “tables” (eg. AUC).
  • Intermediate outputs
    • Variables computed in the structural model and not listed as an “output” or “table” in the OUTPUT block (eg. amount in the peripheral compartment, time varying clearance).
    • Regressors.
    • Variables defined with the “additional lines” in the model definition.

Loading a model automatically generates the “main outputs”. Model predictions and tables are on a default time grid. If a project is built from scratch, then model observations use also the default time grid. Otherwise, in case of project imported from Monolix, they are on a grid given by the measurement times from the Monolix dataset.






Projects: 3.5.outputs, 7.noncontinuous_outputs


New output element

Outputs correspond to output variables, which can be written or selected from the list (green frame).

It is possible to have different outputs of the same variable. For example, one output shows the time evolution over a treatment period and another gives a value at the end of treatment to define an endpoint. However, charts display these outputs on one plot with merged time grids.

There are three output types.

  • Regular: It is a vector on a regular time grid (start time, step, final time, (occ)) common for all subjects.
  • Manual: It is a vector with manually defined list of time points (use “space” to separate them) common for all subjects.
  • External: It is a file with a table that has: a mandatory column “time” for time points, an optional column “id” (in the absence of the “id” column the time grid is equal for all subjects), and an optional column “occ” for occasions.

Occasions

By default, the regular and manual output types apply to all subject-occasions. If occasions are common among all individuals, then an option “occasion-wise values” is available. In this case each occasion has a separate time grid.

Non-continuous outputs

  • Time-to-Event: time limits (start time and final time) define the observation period during which the survival curve is computed.
  • Categorical: time grid corresponds to different categories (eg. levels).
  • Count: time grid defines counting periods.

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

Several treatment elements can be selected, they can be defined in different exploration groups, or combined within an exploration group. Each exploration group is produceds a separate prediction. If several treatments are combined within an exploration group, the prediction corresponds to the treatments given together to the same individual.

In the demo shown below, two exploration groups are defined, the first corresponds to the treatment element singleDose_150, while the second corresponds to the combination of loadingDose_100 and multipleDoses_50. The two exploration groups are represented by two prediction curves in different colors.

 

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.

If several output elements based on the same variable are selected, they are plotted on the same plot with merged grids.

By default each output is plotted on a separate plot, as seen below. This can be changed in the exploration settings.

 

Interactive modification of parameter values or dosing regimen

  • 3.exploration/PK_exploration.smlx

The right panel can be used to modify interactively the parameters values or the dosing regimens and check in real-time the impact on the model dynamics.

The figure below shows the parameter section highlighted in green, where the values can be changed via the small arrows or by entering new values with the keyboard. The “reset” button highlighted here in blue resets the parameters to their initial values. On the plot, the solid curves correspond to the current predictions, while reference curves has been added as dashed lines.

On the next figure, the section “Treatment” highlighted in green shows the elements from the treatment multipleDoses_50 that can be modified. Reference curves are added by clicking on the button highlighted in purple. Each successive reference curve is represented a line in the panel as highlighted in blue, with an icon to restore the reference parameters or remove the reference.

Moreover, hovering on a reference line highlights the corresponding reference on the plot in yellow, as seen on the following figure:

 

Defining new parameter or treatment elements

  • 3.exploration/PK_exploration.smlx

It is possible to save the modified parameters or treatments as new elements with the button marked as green on the figure below. It opens a window to create a new manual element of type Individual parameters or Treatment. A new parameter element created this way will automatically replace the previously selected element in Exploration, unless the corresponding checkbox is unchecked (blue mark on the figure).

Creating a new Treatment element as shown below replaces by default the initial treatment element with the new one, but it is also possible to add the new treatment to a new exploration group.

 

 

Sending elements to simulation

The button “Send elements to simulation” sends all elements selected in Exploration to the selection in the tab Simulation. Exploration groups are turned into simulation groups with a default size of 1 individual per group.

 

Plots settings

  • 3.exploration/PKPD_exploration.smlx

The panel “Settings” can be used to control some elements of the plots, such as the scale of the curves displayed on each plot.

On the following figure, two variables Cc and E are displayed on separate plots, with logscale on the Y-axis.

Below, the two variables are displayed on the same plot. Each variable keeps its own grid.

 

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.

A screenshot of the Simulation tab with an typical example of s simulation of a population of individuals in two groups with different treatment.

 

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.

steps to create two simulation groups

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.A simulation scenario with three groups having different levels of an oral dose.
  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.A simulation scenario with two groups having different ethnicity described by covariates: caucasian and asian.

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

A simulation scenario setting of two treatment groups, which have shared parameters, covariates and outputs. The option

4.2.Outcomes and endpoints #

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: takes the average, minimum or maximum 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’.
  • 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.

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.

To learn more about plots in the exploration tab, click here – it is a special documentation page for the model Exploration feature.


Plots tab structure and settings in Simulx is the same as in Monolix and Pkanalix. The left panel (green frame) contains the list of available plots grouped by outcome type or by chart type. Central region displays one selected plot, for instance output distribution of Cc. Each simulation group has its own subplot. On top of the plotting area, there are layout options and a button to export current plot as an image (blue frame). The right panel is for plots settings, such as display or axis options, definition of bins or visual cues. In addition, separate sub-tabs at the bottom of this panel (red frame) allow to stratify plots data and change preferences of the plotting area.

  • Simulation outputs. Only output elements used in a simulation scenario generate plots. If more then one simulation output element uses the same model output, then all these simulation outputs are merged on one same plot. For instance, concentration during the whole treatment period on a fine grid and Ctrough on the last treatment day – both using model prediction Cc. Title name of the plot corresponds to the model output name.
  • Outcomes. Outcomes of different endpoints have separate plots, for instance “Cmax” and “CmaxBelow800”. If there is more then one outcome in an endpoint, then a plot displays the combination of them. Moreover, it appears in the plots list as “<endpointName>_outcome”, for instance “SafetyAndEfficacy_outome”.
  • Endpoints distribution is generated only for simulations with replicates.

Plots for continuous data

There are two types of plots for continuous outputs. Firstly, the individual output subplot, which contains individual curves. Secondly, the output distribution with the percentiles. Title of each outcome section in the plot list corresponds to the name of a model variable, for instance Cc for model predictions or y1 for model observations. It is not the name of the output element selected in the simulation tab.

Individual output

Individual output plots represent individual curves computed for each id and each occasion (if present in the model). It is possible to DISPLAY lines, dots and median with standard deviations (green frame), or a combination of them. The statistics (median and standard deviations) use the binning options available in the BINS section of the settings (blue frame). If simulation uses replicates, then by default a plot shows only one replicate. However, 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.

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

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.

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.

5.Simulx API #

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 element definition

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.

Description of the functions concerning the project management specific to Simulx

Description of the functions concerning the results

Description of the functions concerning the scenario

Description of the functions concerning the scenario specific to Simulx

Description of the functions concerning the commons-settings

Examples

  • Simple example to load an existing project, run the simulation and look at the results :
# load and initialize the API
library(lixoftConnectors) 
initializeLixoftConnectors(software="simulx")

# Get the project
demoPath = '/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 is the user’s home folder (on windows C:/Users/toto if toto is your username).

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 treatmen element.
deleteElement Delete an element of any type.
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. #’ @examples

Usage

defineCovariateElement(name, element)

See Also

getCovariateElements

Click here to see examples

## Not run:

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 R-functions, Monolix R-functions, Simulx R-functions.


[Simulx] Define individual element

Description

Define a new individual element. If can be defined an external file or as a data.frame.#’ @examples
## Not run:
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)

Usage

defineIndividualElement(name, element)

See Also

getIndividualElements


[Simulx] Define occasion element

Description

Define a new occasion element. If can be defined an external file or as a data.frame. Only one occasion element can be defined.

Usage

defineOccasionElement(element)

See Also

getOccasionElements

Click here to see examples

## Not run:

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 R-functions, Monolix R-functions, Simulx R-functions.


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

See Also

getOutputElements

Click here to see examples

## Not run:

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 R-functions, Monolix R-functions, Simulx R-functions.


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

See Also

getPopulationElements

Click here to see examples

## Not run:

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 R-functions, Monolix R-functions, Simulx R-functions.


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

See Also

getRegressorElements

Click here to see examples

## Not run:

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 R-functions, Monolix R-functions, Simulx R-functions.


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

Note

admID, repeat and probaMissDose are optional. In data, tInf and reset are optional.

See Also

getTreatmentElements

Click here to see examples

## Not run:

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), reset=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 R-functions, Monolix R-functions, Simulx R-functions.


[Simulx] Delete element

Description

Delete an element of any type.

Usage

deleteElement(name)

Click here to see examples

## Not run:

deleteElement(name = “name”)

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[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(name)

See Also

defineCovariateElement

Click here to see examples

## Not run:

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 R-functions, Monolix R-functions, Simulx R-functions.


[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

## Not run:

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 R-functions, Monolix R-functions, Simulx R-functions.


[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

## Not run:

$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 R-functions, Monolix R-functions, Simulx R-functions.


[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

## Not run:

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 R-functions, Monolix R-functions, Simulx R-functions.


[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()

See Also

defineRegressorElement

Click here to see examples

## Not run:

$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 R-functions, Monolix R-functions, Simulx R-functions.


[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 R-functions, Monolix R-functions, Simulx R-functions.

5.3.Description of the functions concerning the project management #

Description of the functions of the API

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.

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

See Also

setStructuralModel

Click here to see examples

## Not run:

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

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


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

Click here to see examples

## Not run:

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

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

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[Monolix – PKanalix – Simulx] Create new project

Description

Create a new empty project providing model and data specification. The data specification is:

Monolix, PKanalix
  • dataFile (string): path to the data file
  • headerTypes (array<character>): vector of headers
  • 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

Usage

newProject(modelFile = NULL, data = NULL)

Arguments

modelFile (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

Click here to see examples

## Not run:

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 model

newProject(modelFile = “/path/to/monolix/project/file.mlxtran”)

new project from an import of a monolix model

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[Monolix – PKanalix – Simulx] Save current project

Description

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

Usage

saveProject(projectFile = "")
[Pkanalix only]
saveProject("/path/to/project/file.pkx")
[Monolix only]
saveProject("/path/to/project/file.mlxtran")
[Simulx only]
saveProject("/path/to/project/file.smlx")

Arguments

projectFile
[optional](character) Path where to save a copy of the current 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

Click here to see examples

## Not run:

saveProject(“/path/to/project/file.mlxtran”) # save a copy of the model

saveProject() # update current model

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.

5.4.Description of the functions concerning the project management specific to Simulx #

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

See Also

setAddLines

Click here to see examples

## Not run:

getAddLines()

=> “ddt_AUC = Cc”

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


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

Click here to see examples

## Not run:

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 R-functions, Monolix R-functions, Simulx R-functions.


[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
(string) Additional lines to define.

See Also

getAddLines

Click here to see examples

## Not run:

setAddLines(“ddt_AUC = Cc”)

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

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.

5.5.Description of the functions concerning the results #

Description of the functions of the API

getSimulationResults Get the results of the simulation.

[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()

See Also

runSimulation

Click here to see examples

## Not run:

getSimulationResults()

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.

5.6.Description of the functions concerning the scenario #

Description of the functions of the API

abort Stop the current task run.
computeChartsData Compute and export the charts data of scenario.

[Monolix – PKanalix] Stop the current task run

Description

Stop the current task run.

Usage

abort()

Click here to see examples

## Not run:

abort()

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[Monolix – Simulx] Compute the charts data

Description

Compute and export the charts data of scenario.
Notice that it does not impact the current scenario. Call abort to stop the execution.

To launch the function in the background, so that functions which do not modify the project (“get” functions for example) remains available, set the input argument “wait” to FALSE.

Usage

computeChartsData(wait = TRUE, exportVPCSimulations = FALSE)

Arguments

wait
(bool) Should R wait for run completion before giving back the hand to the user. Equals TRUE by default.

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

See Also

isRunning abort

Click here to see examples

## Not run:

computeChartsData()

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.

5.7.Description of the functions concerning the scenario specific to Simulx #

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.

[Simulx] Add simulation group

Description

Add a new simulation group.

Usage

addGroup(group)

Arguments

group
(string) Name of the group to add.

See Also

getGroups

Click here to see examples

## Not run:

addGroup(“group”)

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[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

See Also

setGroupRemaining

Click here to see examples

## Not run:

getGroupRemaining( group = “arm1” )

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[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()

See Also

addGroup

Click here to see examples

## Not run:

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] “mlx_Adm1”

[[1]]$output

[1] “mlx_y1”

[[1]]$size

[1] 12

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[Simulx] Get number of replicates

Description

Get the number of replicates.

Usage

getNbReplicates()

See Also

setNbReplicates

Click here to see examples

## Not run:

getNbReplicates()

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[Simulx] Get same individuals among groups

Description

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

Usage

getSameIndividualsAmongGroups()

See Also

setSameIndividualsAmongGroups

Click here to see examples

## Not run:

getSameIndividualsAmongGroups()

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[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()

See Also

setSamplingMethod

Click here to see examples

## Not run:

getSamplingMethod()

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[Simulx] Get simulation groups sharedIds

Description

Get the elements for the shared group.

Usage

getSharedIds()

See Also

setSharedIds

Click here to see examples

## Not run:

getSharedIds()

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[Simulx] Remove simulation group

Description

Remove a simulation group.

Usage

removeGroup(group)

Arguments

group
(string) Name of the group to remove.

See Also

getGroups,addGroup

Click here to see examples

## Not run:

removeGroup(“group”)

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[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

Click here to see examples

## Not run:

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

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


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

See Also

getGroups

Click here to see examples

## Not run:

renameGroup(“currentGroupName”, “newGroupName”)

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[Simulx] Run simulation

Description

Run the simulation task.

Usage

runSimulation(wait = TRUE)

See Also

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

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

See Also

getGroups

Click here to see examples

## Not run:

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

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[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

See Also

getGroupRemaining

Click here to see examples

## Not run:

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

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


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

See Also

getGroups

Click here to see examples

## Not run:

setGroupSize(“group”, 10)

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[Simulx] Set number of replicates

Description

Define the number of replicates of the simulation.

Usage

setNbReplicates(nb)

Arguments

nb
(int) Number of replicates.

See Also

getNbReplicates

Click here to see examples

## Not run:

setNbReplicates( nb = 1 )

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


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

See Also

getSameIndividualsAmongGroups

Click here to see examples

## Not run:

setSameIndividualsAmongGroups( value = TRUE )

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[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

See Also

getSamplingMethod

Click here to see examples

## Not run:

setSamplingMethod( method = “” )

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[Simulx] Set simulation groups sharedIds

Description

Set the elements for the shared group.

Usage

setSharedIds(sharedIds)

Arguments

method
(character) The available types are: covariate, output, treatment, regressor, population, individual

See Also

getSharedIds

Click here to see examples

## Not run:

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

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.

5.8.Description of the functions concerning the commons-settings #

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.
“dpi” (bool) Apply high density pixel correction.
“imageFormat” (string) Image format used to save monolix graphics.
“delimiter” (string) Character use as delimiter in exported result files.
“exportCharts” (bool) Should graphics images be exported.
“exportChartsData” (bool) Should graphics data be exported.
“headerAliases” (list(“header” = vector<string>)) For each header, the list of the recognized aliases.

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.

Click here to see examples

## Not run:

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 R-functions, Monolix R-functions, Simulx R-functions.


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

See Also

getProjectSettings

Click here to see examples

## Not run:

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 R-functions, Monolix R-functions, Simulx R-functions.


[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.
“dpi” (bool) Apply high density pixel correction.
“imageFormat” (string) Image format used to save monolix graphics.
“delimiter” (string) Character use as delimiter in exported result files.
“exportCharts” (bool) Should graphics images be exported.
“exportChartsData” (bool) Should graphics data be exported.
“headerAliases” (list(“header” = vector<string>)) For each header, the list of the recognized aliases.

Usage

setPreferences(...)

Arguments


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

See Also

getPreferences

Click here to see examples

## Not run:

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

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.


[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}.

See Also

getProjectSettings

Click here to see examples

## Not run:

setProjectSettings(directory = “/path/to/export/directory”, seed = 12345)

## End(Not run)


Top of the page, PKanalix R-functions, Monolix R-functions, Simulx R-functions.

Help Guide Powered by Documentor
Suggest Edit
modal close image