Data and event records
In the earlier chapters we saw that the population data \(y_{ij}\), \(x_{ij}\), \(z_i\), etc, have a hierarchical (nested) structure: the data describe observations for each subject as well as varying subject information. Since NONMEM uses tabulated data to represent this intra- and inter-subject variability, we should expect certain redundancy in the encoding.
A NONMEM input data set consists of event records 1, representing temporal events such as dosing, observation, and events as the beginning of a urine collection and a measured change in kidney function. Data records (rows in the data file) 2 correspond to different events, and must be in the order of time.
Data records also represent individuals, by grouping an individual's records in contiguous records with a same ID. We refer to such a group an individual record. Data records in an individual record must also be ordered in time.
In the case of single subject data set, the records do not necessarily correspond on a one-to-one basis to either animal or human subjects: an individual record is simply any group of contiguous data records containing only one observation record and having the same ID data item. (Although, the presence of a multivariate observation means the individual record containing it has several observation records, each containing one element of the observation). In this case the time ordering of data records refers to the time ordering of data records across all records.
The first 9 records of a typical NONMEM data set is shown below.
|
|
We see the nine records correspond to two individual records: five events for individual with ID=1, and four for individual with ID=2. Three of these events are observation events, with DV (Dependent Variable) provided. Label ID and DV are reserved data items, same for TIME (event time) and MDV (Missing Dependent Variable). Label C1, C2, …, CN are concomitant variable data items for additional event specification (such as EVID, see below) as well as covariates. Null (blank) entries are read in as zeros. They can also be explicitly put in as "." (dot) and "0".
Now we discuss commonly used data items for population data. See Reference manual for additional ones and more details.
Depdent variable: DV and MDV
There must always be a Dependent Variable data item labeled DV. This is for observations \(y\). There can be only one DV data item per data record. The position of the DV column can be flexible.
MDV complemets DV to indicate missing observations 3:
- MDV=0: DV for that record contains an observation value. The record is referred to as an observation record.
- MDV=1: DV for that record does not contain a value of an observation.
Subject identification: ID
For population data one must supply subject identification data item ID, and organize the data into two or more "individual records". An individual record is a group of contiguous data records with a same ID for a same individual. ID column does not have to be consecutive, increasing, unique, or begin with 1. For example, an ID column of 3, 5, 6, 10, 3, is acceptable as a sequence of IDs. Note the two instances of "3" IDs. Since they are separated by different IDs (5, 6, 10), they represent different individuals.
Event identification: EVID
Every event record must have EVID. This data item identifies the type of event.
- EVID=0: observation event. The DV data item in the record is an observation, and MDV=0 (if specified). When EVID!=0 DV data item can be any value or blank, and the MDV=1.
- EVID=1: dose event. There are three types of doses: bolus dose, infusion of finite duration, and continuous constant rate infusion (effectively of infinite duration and leading to steady-state, thus also called steady -state infusion). A dose event corresponds to either the time a bolus dose is given, or the time an infusion is initiated, or the time a steady-state infusion terminates.
- EVID=2: other-type event, namely neither an observation nor dose event. Examples include the time a urine collection begins/ends and the time a change in a covariate (such as glomelular filtration rate) is noted.
- EVID=3: reset event. With a reset event the kinetic system is reinitialized. Time is reset to TIME in the record, the amounts in each compartment to zero, and the on/off status of each compartment to its initial status.
- EVID=4: reset-dose event. It combines a dose event and a reset event by first resetting the system then applying the dose according to the information given.
TIME and DATE
Every event record must have TIME 4 to specify the time of the event.
Unless in reset and reset-dose events where time is reset, event records must be ordered (within an individual record) in time. Namely, \(t_A\le t_B\) when event record A is followed by event record B.
TIME may contain clock time, hh:mm or hh:mm:ss. If certain record's TIME contains colon ":", all the TIME values will be converted to elapsed (relative) values in hour. Incorporating DATE (see below), they are relative to each individual's first data record (the first record has TIME=0), such as
|
|
Note that recorded time is over 24, indicating the records span into the second and third day. Alternatively, one can use DATE to represent the above records:
|
|
DATE supports calendar dates in month-day-year format. The year can be skipped or supplied in two-digit and 4-digit format:
|
|
Using DATE will trigger time convertion even if without ":" in TIME column.
Reset events and reset-dose events also set TIME=0.
In addition, one can use the TRANSLATE=(TIME/f/d) option of $DATA record to request that TIME values be divided by f (typically, f is 24 to convert hours to days, with d significant digits.
Dose Amount: AMT
In a dose event AMT gives the amount of a (instantaneous) bolus dose or a finite-duration infusion, incorporating bioavailability fraction. If other data items in a dose event record (see below) indicate that the event record marks the termination of a steady-state infusion, then if given AMT must be 0. If all doses are steady-state infusions, AMT can be omitted.
In observation, other-type, and reset event records, if given AMT must be 0 . In a reset-dose event record the AMT data item should satisfy the requirements of the AMT data item in a dose event record.
Bolus dose
A dose record with AMT>0, RATE=0 and SS=0 specifies a bolus dose. Recall that if the $PK record computes a bioavailability fraction parameter for the compartment into which the dose is introduced, then the contents of the AMT data item is multiplied by the current value of this parameter before the amount is added to the compartment. A bolus dose enters the dose compartment immediately; the predicted (scaled) amount in the dose compartment, if displayed in a table or scatterplot, will include the dose. For example, a record
|
|
for the model in Chapter 1 would be for a bolus dose, because RATE and SS are not given in the $INPUT control record (recall that blank/null are treated as zero).
A bolus dose to the central compartment might be interpreted as an IV bolus dose; to the depot it might be an oral tablet; to a peripheral compartment it might be an intra-muscular injection.
Dose rate: RATE
In a dose record the RATE data item can have values
- RATE>0: an infusion rate.
- RATE=0: instantaneous bolus dose.
- RATE=-1: the dose is either a zero-order bolus dose with rate modeled in PK or a rate-modeled steady-state infusion.
- RATE=-2: a zero-order bolus dose and that its duration is modeled in PK. In this case a positive AMT must be specified.
RATE must be 0 in observation, other-type, and reset event records. In a reset-dose event record the RATE data item should satisfy the requirements of the RATE data item in a dose event record.
RATE can be omitted if all doses are bolus.
Infusion dose
Infusions are doses having AMT>0 and RATE>0, with duration AMT/RATE, and there is no explicit "end of infusion" record.
As with bolus doses, AMT is first multiplied by the bioavailability parameter for the dose compartment, if any. Drug amounts in the system cannot be affected in a detectable way at the time an infusion begins by any drug introduced by the infusion; the predicted (scaled) amount in the dose compartment in the output will not include the dose. Infusions may overlap. That is, subsequent dose records may start new infusions before old ones have finished. It is acceptable if an infusion’s duration is large enough to extend beyond the time of the last event record for the individual, but the remainder of the drug is ignored. A reset or reset-dose event, or a steady-state dose event (SS=1, see next section), will also terminate any ongoing infusions.
For example,
|
|
defines an infusion dose that begins at TIME=4, and terminates at TIME=4+10/2=9.
Interdose interval: II
- If some steady-state dose event record has a positive AMT data item, then the II must be specified.
- If some non-steady-state dose event record has a positive ADDL data item, II must be specified.
II can be 0 or positive. For repeated doses II specifies the period.
II must be 0 in steady-state infusion. observation, other-type, and reset event records. In a reset-dose event record II should satisfy the requirements of II in a dose event record.
The same rule of hh:mm and DATE data for TIME applies to II. For example, II accepts ":30" for half-hour dose interval and it will be converted to "0.5". Similarly, one can use the TRANSLATE=(TIME/f/d) option of $DATA record to request that II values be divided by f (typically, f is 24 to convert hours to days, with d significant digits.
Steady State: SS
Steady state is an idealized state in a kinetic system. It is when the drug amount in the system has reached a periodic pattern after a sequence of repeated dose at a regular dose cycle 5. The doses in each cycle may consist of a mixture of bolus doses and infusions of finite duration. For example, a dose cycle with 4-hours period may consist of a bolus dose of 10mg, immediately followed by a 30 minute infusion of 10mg, so that the combination of doses is repeated every 4 hours. When the system is at such a state, we call the doses and cycles stead-state doses and steady-state cycles.
Mathematically the state state is defined as following, Let the dose times of certain cycle be \(t_1\le t_2\le \dots \le t_n\), and of the next cycle be \(t_1+T, t_2+T, \dots, t_n+T\), then at \(t_1+2T, t_2+2T, \dots, t_n+2T\), etc. The system is at steady state if for any \(t\) in interval \([t_1, t_1+T)\) the drug amounts in the compartments \(A(t)\) equal to \(A(t+T)\), the amounts at \(t+T\).
Intead of specifying a repeated number of dose event records, we use a special record for the last dose cycle (for steady-state infusions only records for the terminations are required, as shown above). These records are called steady-state dose records. They describe the administration of a sequence of same doses that leads to the steady state at the specified TIME. This sequence of implied doses is assumed to be ongoing since forever. In other words, the implied dose times started at \(t=-\infty\). We use SS to flag steady-state dose records (see Reference manual for details, including the interpretation of SS=3).
- SS=0 indicates that the dose is not a steady state dose.
- SS=1 indicates that the dose is a steady state dose, and that the compartment amounts are to be reset to the steady-state amounts resulting from the given dose.
- SS=2 indicates that the dose is a steady state dose, and that the compartment amounts are to be set to the sum of the steady-state amounts resulting from the given dose plus whatever those amounts would have been at the event time were the steady-state dose not given.
Steady state with multiple bolus doses
These are dose events having AMT>0, RATE=0, SS=1, and II>0. The II specifies the period of dose cycles. As with non-steady-state bolus doses, AMT is first multiplied by the bioavailability parameter for the dose compartment, if any.
Figure below shows how drug levels vary with time. The concentration-time profiles over each interdose interval look the same since, in principle, there is an infinite number of implied doses.
For example,
|
|
specifies that an infinite number of bolus doses, 10 units each, have been given 12 hours apart, with the last at time 8AM by which the system has reached steady state.
Steady state with multiple infusions
These are dose events having AMT>0, RATE>0, SS=1, and II>0. Each such event describes the last of a series of regularly spaced infusions, all of the same amount and rate. As with a non-steady-state infusion, the duration of each infusion is given by AMT/RATE. Figure 3.2 shows how drug levels vary with time. The concentration-time profiles over each interdose interval look the same since, in principle, there is an infinite number of implied doses. See figure below.
For example,
|
|
specifies that infusions, each 10 units and of duration 10/5=2, are assumed to have been given 6 hours apart, with the last of these started at time 4PM, at which time steady-state is reached. The daily dose times were 4AM, 10AM, 4PM, and 10PM. Steady-state levels can be predicted between times 16 (4 PM) and 22 (10 PM) (provided there are no further doses introduced during this interval).
Steady State with constant infusion
These are dose events having AMT=0, RATE>0, SS=1, and II=0. Such an event consists of infusion with the stated rate, starting at time \(-\infty\), and ending at the time on the dose event record. Bioavailability fractions do not apply to these doses. Figure below shows how drug levels vary with time.
For example,
|
|
specifies a steady-state infusion at rate 2, ending at 4 PM. A steady-state level can be predicted only at this time.
Multiple Steady-State doses
Doses with SS=2 are similar to non-steady-state doses in that compartment amounts are computed in two steps. First, compartment amounts are computed at the time on the dose event record based on the prior dosing history of the system. Second, steady-state amounts are computed from the dosing information on the record and added to the existing compartment amounts. Thus, if the kinetics are linear, this results in an application of the superposition principle wherein the amounts in the system resulting from doses described by dose event records preceding the time of the steady-state dose are superposed on the (steady-state) amounts in the system resulting from the steady-state dose and the implied doses.
As with any steady-state dose, the steady-state amounts are obtained using the values of the pharmacokinetic parameters computed from the information on the steady-state dose record. In the case that SS=2, though, if these values differ from those computed from the information on the previous dose record(s), then the compartment amounts at the time in the steady-state dose record are not truly steady-state amounts, and the computed steady-state levels are not valid predictions. NONMEM will not detect this error. We emphasize that superposition is only valid with linear kinetic systems. SS=2 records can be used to achieve the specification of complicated dosing regimens. For example, figure below shows how drug levels vary with time when two different doses are alternated. In this illustration, two steady-state doses are specified, each with interdose interval I and with time between the two steady-state doses equal to I/2. Even more complex patterns are possible.
For example,
|
|
describes the following dosing regimen: a dose of 10 units every morning at 8AM and a dose of 15 units every evening at 8PM. Note that steady-state is not truly established until after the second dose record; any observation events interposed between the two dose records will reflect only the first steady-state dosage (i.e., 10 units every 8AM). Another way to achieve the same steady-state is to use
|
|
This describes doses of 10 units every 12 hours, the last of which is given at 8PM (i.e. at 8 AM and 8 PM daily), plus additional doses of 5 units at 8PM daily. In both examples, the steady-state levels can be predicted from time 20 hours to time 32 hours.
Combining non-steady-state with steady-state Doses
Non-steady-state dose records may appear before, among, or after steady-state dose records. Such a dose record may occur before a steady-state dose record to reflect a separate transient dose given among a series of regular doses leading to steady-state. One such example is when a patient under steady-state mistakenly takes an extra dose shortly before his appointment.
A non-steady-state dose record may occur after a steady-state dose record in order to continue the pattern of doses beyond the steady-state dose. One may use this approach to calculate the system state beyond the end time for the last cycle specified in the steady-state record. For example,
|
|
shows that the last two records continue the steady-state pattern of the first two. Steady-state levels may be predicted between times 20 and 56.
Similarly, a steady-state constant infusion may be extended with a non-steady-state infusion. In the example below, steady-state levels can be predicted from time 0 to time 100.
|
|
Compartment: CMT and PCMT
The observation compartment of a record contains the prediction for
an observation. It can be either a scaled drug amount or a
modification of this quantity. Every dose event is associated with a
dose compartment . A kinetic model has default designation for
these compartments, called default observation compartment and
default dose compartment, respectively. Some kinetic models have the
defaults built into the model definition, some can be user-specified
(see $MODEL record). Hereon unless otherwise specified by
observation/dose compartment we we their defaults.
On/Off of compartments
Some compartments can be switched on or off at event record times. When off, a compartment contains no drug; when on, drug distributes according to the kinetic model. For example, an output compartment may be turned on at the start of urine collection, or a depot compartment turned off once negligible drug remains to avoid unnecessary computation.
Each compartment has an initial on/off status at the start of an individual record and retains that status until explicitly changed. In single-subject datasets, “individual record” refers to the entire dataset. Only specific compartments in a kinetic model can be switched, and both switchable compartments and their initial statuses are defined—either built into the model or set by the user in subroutine MODEL.
A dose event turns on the dose compartment at dosing time if not already active. During an observation event, the observation compartment must be either the default one (always on) or a compartment currently on.
If drug would normally move from compartment A to B, turning off B implies turning off A. In that case the drug amount either enters the output compartment (if on) or is lost from the system.
CMT data item
The optional CMT data item specifies the relevant compartment for a record:
- for an observation record, it specifies the observation compartment;
- for a dose record, it specifies the dose compartment;
- it turns a compartment on/off at the event time: a positive compartment number means ON, negative means OFF.
For observation/dose(reset-dose) compartment for an observation/dose record. Not given or CMT=0 implies the use of default compartments.
If all one wants to accomplish at a certain time is to turn a compartment on (e.g. the output compartment, in order to begin a urine collection), then one should construct an other-type event record that simply turns the compartment on, by giving the compartment number in CMT.
To turn a compartment off at a given time, one should construct an other-type event record that gives the negative value of the compartment number. This also applies to an observation record, provided the observation compartment is the output compartment or an output-type compartment. In this case the compartment must be on at the event time, but it is turned off "immediately thereafter". Thus one can record the observation of a urine concentration in an event record and conveniently turn off the urine collection using the same record 6. An output-type compartment is initally off, may be turned on and off, and may not receive a dose. It must be turned on with an other-type event record in order start accumulating drug.
With a reset or reset-dose event record the on/off status of each compartment is reset to its initial status, and then if the compartment data item is nonzero, the designated compartment is turned on or off according to whether the data item is positive or negative (it must be plus with a reset-dose event record).
Prediction Compartment
NONMEM computes a prediction for each data record, regardless if it contains an observation: one can use other-type event records at times of interest, and output the predition in tables.
- Data records with CONT=1 are ignored thus the prediction is 0.
- For the last data record of an observation event record, the prediction is always either the scaled drug amount in the observation compartment, or a modification of this quantity.
- For the last data record of a non-observation record, the prediction is
the prediction that would result for an observation of the default observation compartment, unless otherwise specified using PCMT.
The optional PCMT data item specifies the compartment number for the prediction for the last data record of the event record. Thus predictions for different compartments can be displayed. Not given or PCMT=0 in a non-observation event record implies the prediction for the last data record of the event record is the prediction that would result for an observation of the default observation compartment.
By convention, the number of the output compartment may also be given by the PCMT data item as the number 1000 (this is true regardless of the type of the event record). With small models (number of compartments <= 99), this number may also be given as 100.
Additional doses: ADDL
Instead of specifying a series of records for identical doses, user can use ADDL on a single dose event record. The dose specified on the dose event record is called the initiating dose, so that
- ADDL=0 means only the initiating dose in the record is administored;
- ADDLn= for a positive
nmeansndoses, additional to the initiating dose, are given. In that case one must use II to specify the constant interdose interval.
If the initiating dose is lagged, the additional doses are also lagged. The additional dose time are the time when such a dose actually enters the system, accounting for lag, if any. It is a nonevent dose time. At each additional dose time a dose like the initiating dose automatically enters the system. Until such a time as all the additional doses have entered, or until the last event time in an individual record is attained, whichever comes first, the dose record initiating the dose series is said to be active. Afterwards, the record is said to be inactive (The additional dose data item can also be used when all the data are from a single subject, and then the term 'last event time in an individual record' should be understood to mean the last event time in the data set. This is a consequence of the single-subject assumption). There can be at most 10 active dose event records at a time.
Note that
- the administration of an additional dose will not be expressed explicitly in a NONMEM table or scatterplot;
- If given, ADDL must be 0 in observation, other-type, and reset event records.
- ADDL must be 0 when the initiating dose is a steady-state infusion. However, the ADDL data item can be nonzero when the initiating dose is any other type of steady-state dose. In this case, after the steady-state dose, an additional number of (transient) doses just like the steady-state dose are given. (Recall that the steady-state dose is just the last of many doses identical to it, leading to a steady-state). On the other hand, any steady-state dose event record with SS1 will deactivate any previous dose event record which happens to be active. Also, a reset and a reset-dose event record will deactivate any previous dose event record which happens to be active. Also, if a compartment is turned off with an other-type event record, this deactivates any previous dose event record with a dose to this compartment which happens to be active.
Examples
Output compartment
Consider the one-compartment model with first-order absorption with the sequence of events, including the collections and observations of urine concentration \(C_u\):
| 6:00AM | a bolus dose of 100 is given; |
| 8:00AM | a urine collection is started; |
| 9:30AM | \(C_u\) and urine volume (UVOL) are measured and a new collection is started; |
| 11:45AM | \(C_p\), \(C_u\), and UVOL are measured. |
The data records are as follows:
|
|
Notice that urine collections start with an other-type event record (EVID=2) with CMT=3 for the output compartment. This turns on the compartment on at 8AM, i.e. to begin accounting for the amount accumulating in this compartment from 8AM. To use other-type event records one must include the EVID data item. The CMT data item must be present in all event records since in order to specify the output compartment. The DV value on the observation record at 9:30AM is \(C_u\). The negative CMT in this record indicates that the output compartment is turned off at 9:30AM. Then to continue the collection, the compartment is explicitly turned on (line 5). Note that UVOL is recorded on both observation records at time 11:45AM. Strictly speaking, it need only be recorded on the sec- ond (\(C_u\) observation). See the plasma-urine modeling examples.
Strictly speaking, the event records feature is part of PREDPP, NONMEM's populaion PK modeling sub-library. Traditionally NONMEM uses a more general format. But since essentially all modern NONMEM applications use event records for data specification and control records (see next chapter), that is what we will do in this document.
In NONMEM v7.2+, there is no limit on the number of data items per data record. Ealier NONMEM v7.x versions limit it to 50 but this can be changed from the PD constant in file resources/SIZES.f90.
In NONMEM v7.3+, there is no limit on the number of observation records per individual. Ealier NONMEM v7.x versions limit it to 250. To change this limit, see Reference manual: Internals & API - Size parameters.
An example is when ADVAN9, ADVAN15, or ADVAN17 is used to solve algebraic equations solved. In this case TIME is optional.
The steady-state kinetics described here is general, but the approach of SS data item in this section is not applicable to delay differential equations and some other systems, e.g., those with changes in kinetics outside the dosing interval. See empirical approach for steady state for those situations.
Alternatively one can specify a dedicated subsequent other-type event record with the same time data item.