Occasions definition. When the model to simulate contains inter-occasion variability (ie variability between different periods of measurements within the same individual), you should define a single element Occasions. Like for the model, and contrary to the other simulation elements, it is not possible to define several occasion elements to choose from for the simulation.
Demo projects: 3.7. occasions
All other defined elements must be compatible with the structure of occasions.
Common occasions for all subjects
In the interface, it is possible to define a common structure of occasions applied to all simulated subjects. This structure can contain one or several levels of occasions, and one or several occasions per subject.
After defining such common occasion structure, other common elements (parameters, covariates, treatments, outputs and regressors of type “manual” or “regular”) can be defined occasion-wise thanks to a dedicated toggle “occasion-wise values”, as on this example screenshot for covariates:
Moreover, elements defined as external tables may contain one or several columns to assign different values to different subject-occasions.
Subject-specific occasions
To define subject-specific occasions use an external file containing a table with columns ID, time and one or several columns for the occasions. The header names for these columns are free and are used by Simulx. The external file separator can be tab, comma or semicolon. The possible file extensions are .csv or .txt.
Below is an example of the occasions element defined after loading the external table (on the left).
After defining such subject-specific occasion structure, other elements (parameters, covariates, treatments, outputs and regressors) must be common over subjects (type “manual”, “regular” or “distribution”), or can be defined with occasion-wise values as external tables only, with the same occasion structure.
Occasions imported from Monolix
Upon import of a Monolix run, Simulx creates an occasion element with the individual structure of occasions from the Monolix data set.
- mlx_subjects: a table containing the occasions and their starting times for each individual. The table has at least 3 columns: id, time, occ. Additional columns may be present in case of several levels of occasions.
Rules for simulating occasions
- Occasions are not simulated in Exploration: only the first occasion from the selected subject is simulated.
- If occasions are not defined, inter-occasion variability is not taken into account for the simulation of individual parameters.
- From the 2023 version on, the sampling of individual parameters takes into account the inter-occasion variability if one or several occasions are defined. In previous versions (2020 and 2021), if the structure of occasions contains a single occasion for some subject, then the simulation of individual parameters for this subject does not take into account inter-occasion variability.
- When an occasion element has been defined, in case of several replicates, the sampling method has to be ‘Keep Order’.
Occasions in outcomes, results and plots
Occasions are indicated as additional columns in the table of individual parameters. In the plots of individual outputs, occasions are highlighted as dashed yellow lines on hover of one the occasions from the same subject. Furthermore, all plots of results can be stratified by occasions.
When occasions are defined, the definition of outcomes can be made by post-processing the simulation outputs by subject (one outcome value per individual) or by subject-occasion (one outcome value for each occasion of each individual). When the post-processing by subject-occasion is selected, the occasion column(s) appear(s) also in the corresponding outcome table.
