Skip to contents

Dataset columns

Source: vignettes/articles/rxode2-dataset-columns.Rmd
rxode2-dataset-columns.Rmd

Data for rxode2 (and nlmixr2) follows NONMEM dataset conventions; most NONMEM-ready datasets can be used directly. This page is the column-by-column reference. For worked examples of each kind of dose see Dosing event types; to build the data in R instead of by hand see Building event tables with et().

Differences from NONMEM

In general, rxode2 event tables follow NONMEM dataset conventions with the following exceptions and extensions:

  • The compartment data item (cmt) can be a string/factor with compartment names.
    • You may turn off a compartment with a negative compartment number or "-cmt" where cmt is the compartment name.
    • The compartment data item (cmt) can still be a number; the number of a compartment is defined by the order of appearance of its name in the model. You can assign compartment numbers explicitly with cmt(cmtName) at the beginning of the model.
  • An additional column dur can specify the duration of infusions:
    • Bioavailability changes will change the rate of infusion when dur/amt are fixed in the input data.
    • Similarly, when specifying rate/amt for an infusion, bioavailability changes will alter the infusion duration since rate/amt are fixed.
  • Some infrequent NONMEM columns are not supported: pcmt, call.
  • NONMEM-style events are supported (0: Observation, 1: Dose, 2: Other, 3: Reset, 4: Reset+Dose). Additional events are supported:
    • evid=5 or replace event: replaces the value of a compartment with the value specified in the amt column (equivalent to deSolve replace).
    • evid=6 or multiply event: multiplies the compartment value by the amt column (equivalent to deSolve multiply).
    • evid=7 or transit/phantom event: puts the dose in the dose() function and calculates time since last dose tad(), but does not place the dose in the compartment. This allows the transit() function to be applied easily.

Columns by type of use

Data for input into rxode2 (and nlmixr2) is similar to NONMEM data; most NONMEM-ready datasets can be used directly.

Subject identification

Column Meaning
ID Subject identifier – integer, character, or factor

Observation columns

Column Meaning
DV Dependent variable (measurement)
CENS Censoring indicator (0 = not censored, 1 = left censored, -1 = right censored)
LIMIT Censoring bound used with CENS (see below)
MDV Missing dependent variable indicator
CMT Compartment name or number for the observation
DVID Dependent variable identifier for multiple endpoints
EVID Event identifier

Dosing columns

Column Meaning
AMT Dose amount
CMT Compartment name or number for the dose
EVID Event identifier
ADDL Number of additional doses identical to this one
II Inter-dose interval
RATE or DUR Infusion rate or duration
SS Steady-state flag

Complete column quick-reference table

Data Item Meaning Notes
id Individual identifier Integer, factor, character, or numeric
time Individual time Numeric
amt Dose amount Positive for doses; zero/NA for observations
rate Infusion rate Duration = amt/rate; rate=-1: rate modeled; rate=-2: duration modeled
dur Infusion duration Rate = amt/dur
evid Event ID 0=Obs; 1=Dose; 2=Other; 3=Reset; 4=Reset+Dose; 5=Replace; 6=Multiply; 7=Transit
cmt Compartment Name or number; prefix - to turn off
ss Steady-state flag 0=non-SS; 1=SS; 2=SS + keep prior states
ii Inter-dose interval Time between doses
addl Additional doses Number of doses identical to this one
dvid DV identifier Identifies which endpoint an observation belongs to

Per-column details

AMT column

The AMT column defines the amount of a dose administered to CMT. For observation rows it should be 0 or NA. For zero-order infusions the rate or duration is set via RATE or DUR.

CENS / LIMIT columns

CENS indicates whether the observation in DV is censored:

  • CENS = 0: not censored; LIMIT is ignored.
  • CENS = 1: left censored (e.g., below the limit of quantification); the true value lies in (LIMIT, DV).
  • CENS = -1: right censored (above limit of quantification); the true value lies in (DV, LIMIT).

rxode2 stores these values so that nlmixr2 can use them in likelihood calculations.

CMT column

CMT indicates the compartment where an event occurs. A character string or factor (the preferred form) is matched by name in the model. An integer is matched by the order in which compartments appear in the model. Prefix with - (e.g. cmt="-depot") to turn off a compartment.

DUR column

DUR defines the duration of a zero-order infusion. When DUR is specified, the infusion rate is computed as rate = amt/dur. Bioavailability changes affect the rate, not the duration.

DV column

DV is the dependent variable in the observation compartment defined by CMT / DVID. It may be missing (MDV=1) or censored (CENS!=0).

DVID column

DVID identifies which endpoint an observation belongs to in multi-endpoint models. It maps to the cond field in $predDf and can be specified as a name (matching the endpoint variable) or integer.

EVID column

The event identifier for a row of data:

EVID Meaning
0 Observation
1 Dose
2 Other (e.g. turn off compartment)
3 Reset all compartments to initial values
4 Reset + dose
5 Replace compartment value with amt
6 Multiply compartment value by amt
7 Transit/phantom dose (dose() / tad() only)

Output-only EVID values (visible when addDosing=TRUE, subsetNonmem=FALSE):

EVID Meaning
-1 Modeled-rate infusion end (rate=-1)
-2 Modeled-duration infusion end (rate=-2)
-10 Rate-specified infusion end (rate>0)
-20 Duration-specified infusion end (dur>0)
101, 102, … Modeled times 1, 2, … (mtime)

Use addDosing=NA to see classic EVID equivalents instead.

ID column

ID separates individuals (persons, animals, etc.). The solver re-initializes the numerical integrator and samples new random effects with each new ID. It may be an integer, character, or factor.

RATE column

RATE specifies a zero-order infusion rate. The infusion duration is computed as dur = amt/rate. Special values:

  • rate = -1: rate is modeled (set via rate(cmt) in the model block); equivalent to NONMEM RATE=-1.
  • rate = -2: duration is modeled (set via dur(cmt) in the model block); equivalent to NONMEM RATE=-2.

When RATE is fixed in the dataset, a bioavailability change alters the infusion duration. When DUR is fixed instead, a bioavailability change alters the infusion rate.

Covariate columns

Any column that is not one of the reserved columns above and whose name matches a model variable is treated as a covariate. Covariates that change over time within a subject are interpolated between records (see the covsInterpolation argument of rxSolve()); values that are constant per subject can instead be supplied with rxSolve(..., iCov=). See Covariates for examples.

SS, II and ADDL columns

  • SS = 1 solves the dose to steady state before applying it; SS = 2 does the same but adds the result to the current state (for non-uniform regimens). II gives the dosing interval used to reach steady state.
  • ADDL repeats the dose ADDL more times, every II time units. The repeated doses are plain doses: an SS flag or an EVID=4 reset applies only to the first one, as in NONMEM.

See Dosing event types for examples.

Other notes

  • NONMEM’s DV is not required; rxode2 is an ODE solving framework and DV is only used by nlmixr2.
  • NONMEM’s MDV is not required; missingness is captured in EVID.
  • Instead of NONMEM-compatible data, deSolve-compatible data frames are also accepted.
  • The classic RxODE EVID encoding is also supported (see Classic rxode2 Events).

Next steps