Description of column-types used to identify subject-occasions

ID: subject identifier

The column is used to identify the different subjects and its content is totally free: numbers / strings… This column is mandatory. Notice that string ‘.’ will not be interpreted as a repetition of the previous line. As a consequence a data set of the form

ID * *
John * * 
John * * 
Mike * * 
. * * 

contains 3 different subjects : ‘John’, ‘Mike’ and ‘.’. It does not generate another occasion for Mike. Even if numbers and strings are allowed, we encourage the user to define Ids using integers for readability and usage simplicity.
Contrarily to NONMEM, the lines corresponding to the same subject do not need to be next to each other. Thus, the following file contains 2 subjects with IDs “1” and “2”.

ID * *
1 * * 
1 * * 
2 * * 
2 * *
1 * *

The IDs are not sorted lexicographical order but by order of appearance in the data set.

Format restrictions (an exception will be thrown otherwise):

  • A data set shall contain one and only one column ID.

OCC: occasion identifiers

It is possible to have, in a data set, one or several columns with the column-type OCC. It corresponds to the same subject (ID should remain the same) but under different circonstances, occasions. For example, if the same subject has two successive different treatments, it should be considered as the same subject with two occasions. The OCC columns can contain only integers. For instance:

John * 1
John * 2
John * 3
How occasions can appear while no OCC column is defined ?

Occasions can be generated even if no OCC column is defined in the data set. In that case, a button arises in the Monolix interface allowing the possibility to add inter occasion variability to the model. This can happen in two cases.

  • Firstly, if there is an EVID column with a value 4 then Monolix defines a washout and create an occasion. Thus, if there is several times where EVID equals 4 for a subject, it will create the same number of occasions. Notice that if EVID equals 4 happens only once at the beginning, only one occasion will be defined and no inter occasion variability would be possible. Thus, the following data set are equivalent.
    1 0 0 1
    1 1 2 1
    1 2 2 1
    1 0 0 2
    1 4 1 2
    1 5 2 2
    1 0 0 0
    1 1 2 0
    1 2 2 0
    1 0 0 4
    1 4 1 0
    1 5 2 0
  • Secondly, if there is a SS column, each steady state creates an occasion. Thus, if two steady states are defined for one subject, then it will generate two occasions. This option will be obsolete and not used in future version of MonolixSuite.
What kind of occasions can be defined?

There are three kinds of occasions

  • Cross over study: In that case, data are collected for each patient during two independent treatment periods of time, there is an overlap on the time definition of the periods. A column OCC can be used used to identify the period. See here for an example.
  • Occasions with whashout: In that case, data are collected for each patient during one period and there are no overlap between the periods. The time is increasing but the dynamical system (i.e. the compartments) is reset when the second period starts. In particular, EVID=4 indicates that the system is reset (washout) for example, when a new dose is administrated. See here for an example.
  • Occasions without whashout: In that case, data are collected for each patient during one period and there are no overlap between the periods. The time is increasing and we want to differentiate periods in terms of occasions without any reset of the dynamical system. For example on the example defined here, multiple doses are administrated to each patient. each period of time between successive doses is defined as a statistical occasion. A column OCC is therefore necessary in the data file to define it.
Frequently asked questions on occasions in the data set
  • Do all the individual need to share the same sequence of occasion? No, the number of occasions and the times defining the occasions can differ from one individual to another.
  • Is there any limit in terms of number of occasions? No.
  • Is it possible to have several levels of occasions? Yes, it can be extended on several level of occasions, see an example here.

Format restrictions (an exception will be thrown otherwise):

  • The OCC columns should contain only integers.