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