Description of column-types used to define the dose regimen

AMT: dose amount

The content of column AMT will be called the dose-column. It shall either contain a double value or string “.”. When there is no EVID or MDV column, when a dose-column contains a double value different from 0 then it will be considered as a dose-line (i.e. a line containing dose information). If the value of the dose is 0, then it will be interpreted as a dose-line if the response-column (i.e. the content of column with column-type Y) contains a string “.”. When a line contains both dose and response information, dose information is not taken into account, it is considered as a response-line. The following table sums up the different situations

AMT Y Comment
10 .      Considered as a dose line
10 0      Considered as a response line
10 10      Considered as a response line
0 .      Considered as a dose line
0 0      Considered as a response line
0 10      Considered as a response line
. .      Ignored
. 0      Considered as a response line
. 10      Considered as a response line

Notice that in the case of the definition of both a non null amount and a measurement, the choice was made to favor the measurementTo solve it without any EVID column, the user should provide two distinct lines to provide both a dose-line and a response lineFor instance, in the following data set

TIME ID AMT Y
12.1 John 1.1 12.6

the line is considered as a response-line, a measurement is set at 12.6 at time 12.1 and no dose is added. Of course it is possible to specify a response and a dose at same time but lines shall be duplicated as in the following data set

TIME ID AMT Y
12.1 Tom . 12.6
12.1 Tom 1.1 .

In that case, the first line is again considered as a response-line, a measurement is set at 12.6 at time 12.1. But the second line is considered as a dose amount at time 12.1 with an amount 1.1.

Format restrictions (an exception will be thrown otherwise):

  • A data set shall not contain more than one column-type AMT.
  • AMT column shall either contain a double value or string “.”.

ADM: Administration type

The goal of this column is to be able to define several types of administration (e.g. oral administration, intravenous,…). The integer in the ADM column works like a flag, which can be used in the model file to link the dose informations of the data set to a specific administration route in the model. For instance, with the following data set:

ID TIME AMT ADM Y
John 0 10 1 .
Eric 0 20 2 .

and the following PK block in the Mlxtran model file:

PK:
iv(type=1)
oral(type=2, ka)

the subject John will receive a dose of 10 via a bolus iv, while subject Eric will receive a dose of 20 orally with first-order rate constant ka. The identifier in the ADM column should match the “type=” field of the macro. We recommend using ADM to define the type of dose only, and set ADM=”.” for response-lines (in this case, the string “.” will not be interpreted as a repetition of the previous column).

Moreover, it is possible to combine the information of the type of response (as YTYPE) in case of response-lines. Thus, if there are several outputs and several administration routes it is possible to set all the information in the ADM column. The several possibilities using YTYPE and ADM are summarized in the following table

Type of line \ Case YTYPE off / ADM off   YTYPE on/ ADM off   YTYPE off / ADM on   YTYPE on/ ADM on
Response line Only one output Defined using YTYPE Defined using ADM      Defined using YTYPE
Dose line Only one administration route (type = 1) Only one administration route (type = 1) Defined using ADM     Defined using ADM

Notice that, for readability and better understanding), we strongly recommend to

  • use ADM to define the type of dose only, and set ADM=”.” for response-lines
  • use YTYPE to define the type of output, and set YTYPE = “.” or the first value for dose lines

Format restrictions (an exception will be thrown otherwise):

  • For dose-lines, the column shall contain only positive integers. For response-lines strings or integers are allowed.
  • A data set shall not contain more than one ADM column-type.

RATE, TINF: rate and infusion duration

These columns enable to define the rate (RATE column-type) or duration (TINF column-type) of doses administered as infusions. The column content is meaningful only for dose-lines. The rate and duration information is transferred to the model via the use of the iv macro. If a RATE is defined, the duration of the infusion will be AMT/RATE. If a TINF is defined, the rate will be AMT/TINF.

Format restrictions (an exception will be thrown otherwise):

  • A data set shall not contain more than one column with column-type RATE or TINF.
  • “.” or 0 means a bolus dose, without any infusion rate or time.
  • Values can be any double value.
  • If a negative value is used in combination with the iv macro, the administration will be a bolus.

SS, II: steady-state and inter-dose interval

Steady-state is used to specify that any transitory effect is over and that the system response is now a periodic function of doses. To do this, a fixed number of doses (by default 4) is added before the dose entered with the SS flag set to true (so 5 doses in total, by default). The period between doses is set to the interdose-interval II.

The number of added doses can be changed in the preferences.xmlx file, located in <home>/lixoft/monolix/config in the user folder. The number of doses is defined in the line <dosesToAddForSteadyState value="5"/>, and can for instance be changed to <dosesToAddForSteadyState value="20"/>.

On the following example:

ID TIME AMT SS II EVID Y
Tom 0 10 1 2 1 .

5 doses are applied, at times  -8, -6, -4, -2 and 0. The above data set is thus equivalent to:

ID TIME AMT SS II EVID Y
Tom  -8 10 0 0 4 .
Tom  -6 10 0 0 1 . 
Tom  -4 10 0 0 1 . 
Tom  -2 10 0 0 1 . 
Tom   0 10 0 0 1 . 

The first added dose will have a wash-out, thus for clarity an EVID column has been included in the previous example. But of course it is possible to specify a steady-state even if there is no EVID column in the data set. However an II column is mandatory to specify the period between the five added doses to reach steady-state. The absence of this column will throw an exception (see here under for the complete list of exceptions).

It is possible to find in a data set a mix of steady-state and non steady-state doses. To prevent doses from colliding, if a normal dose is present before a steady-state dose, a new occasion will be created for the steady-state dose. The following data set, with a normal dose at  t=0 and a steady-state dose at t=10 with an interdose-interval of 3:

ID TIME Y AMT SS  II 
1 0 . 10 0 0                
1 0 10 . . .
1 1 6 . . .
1 2 3.5 . . .
1 10 . 10 1 3
1 11 9 . . .
1 12 6 . . .
1 13 3 . . .
1 14 2 . . .


leads to the following simulation, with 2 occasions, such that the normal dose at t=0 does not collide with the doses at t=-2, 1, 4, 7, 10, added to be at steady-state at t=10:

scheme-SS

Format restrictions (an exception will be thrown otherwise):

  • A data set shall not contain more than one column with column-type SS.
  • A data set shall not contain more than one column with column-type II.
  • When a data set contains a column with column-type SS, there must be a column with column-type II.
  • When a data set contains a column with column-type II and no column with column-type SS or ADDL then a SS column is created with:
    • SS = 1 when inter-dose interval is strictly positive.
    • SS = 0 otherwise.
  • When a data set contains a column with column-type II and no column with column-type SS but a column with column-type ADDL then a SS column is created with:
    • SS = 1 when inter-dose interval is strictly positive and ADDL = 0.
    • SS = 0 otherwise.
  • The column is meaningful only for dose-lines. Its format shall be (for all lines including response-lines for which SS information is not applicable) :
    • SS shall be either 0 or 1 (‘.’ will be replaced by 0).
    • II shall contain a double value and it shall be positive (or null).
      • when SS = 0 then the value shall be null.
      • when SS = 1, the value shall be strictly positive.

ADDL: additional dose line

Additional dose lines is a useful shortcut to specify dose regimens with repetitive treatments. ADDL is the number of times the dose shall be repeated and column II contains the dose repetition interval. For instance to specify a dose of 10 every 12 hours during 3 days it is possible to write:

ID TIME AMT 
Tom 0 10
Tom 12 10
Tom 24 10
Tom 36 10
Tom 48 10
Tom 60 10
Tom 72 10

but ADDL and II (interdose-interval) can also be used to specify the same information in a single line

ID TIME AMT ADDL II 
Tom 0 10 6 12

Notice that in the proposed example, ADDL should be at 6 to have 6 additional administrations. This is very useful for periodic treatments. Two important remarks concerning regression values:

  • If there is a regression-column (i.e. a column with column-type X), its value will also be repeated for added doses even though this value has not been specified but obtained via interpolation.
  • When regression values are defined after the first added dose, warnings are generated. Indeed these values will not be repeated and can possibly interfere with automatically added regression values at dose time. So the warning is generated for the user to confirm that its data make sense.

Format restrictions (an exception will be thrown otherwise):

  • ADDL shall only contain positive (or null) integers or “.” (which will be replaced by 0).
  • When there is an ADDL column there must be an II (interdose interval) column to indicate the inter dose timing.
  • For dose-lines with ADDL strictly positive, the II value must be strictly positive.