Setting the 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.
Loading or creating a model
In Simulx, structural models are provided as external .txt files, whose path is saved into the Monolix project.
There are three options to load a structural model:
Use the option “Browse” to load an existing file containing a structural model.
Use “Load from library” to select a model from the available model libraries. Models from the libraries are not saved as external files but are generated on-the-fly. Once loaded, it is possible to open the content of a library model, edit it and save it as an external file.
Use “New model” to open the built-in editor, write your own model using the Mlxtran language, and save it as an external file.
Loading another model 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 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. If the project is imported from Monolix, this section is created automatically. However, when building a project from scratch, the [INDIVIDUAL] section can be generated automatically starting with version 2024 by clicking “+ ADD INDIVIDUAL”. This will add an [INDIVIDUAL] section with all parameters in the model with a lognormal distribution and random 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.
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.
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. Note that in version 2024 and later, this is accessed by clicking the button “+ ADD LINES”.
This is convenient for example to use variables for simulations that are not defined in the Mlxtran model code, such as the AUC, a change from baseline, or the survival function (see example below). The model file itself is not modified, the additional lines are saved in the .smlx file.
By default, the additional lines are added in a new section EQUATION: below the structural model. In order to add additional lines in the PK block, it is necessary to add “PK:” at the beginning of the additional lines. This is convenient to add a new route of administration, using the iv(), oral() or depot() macro for instance. If this new administration depends on a parameter (e.g the absorption rate ka), the parameter needs to be fixed in the additional lines. It cannot be added to the input parameter list. It is not possible to add additional lines in the [INDIVIDUAL] or [COVARIATE] blocks.
This function is available also with lixoftConnectors functions: setAddLines() and getAddLines(), see here for more details.
When using “import from Monolix”, “additional lines” fields can (sometimes) be unavailable. In this case, open the Monolix project in Monolix and use “Export to Simulx”. This problem has been fixed in the 2021R1 version.
In the example below, a oral absortion route in added to the demo TMDD_exploration.smlx, which originally had only iv:
