Column_mappings

Column mappings

The column mapping file is an ASCII text file (*.txt) that contains a series of statements that define the association between model concepts and columns in a dataset:


  id(subjectIDColumnNameame)

Example: id(SubjectID) says that “SubjectID” is the data column signifying the subject identifier. (SubjectID is not used by Phoenix, but the column mapping is still required. It is acceptable to map to a nonexistent column, such as: id(zzzDummyID).)


  time(timeColumnName)

Example: time(T) says that T is the data column signifying time. The time values can be either simple decimal numbers, or they can be in hh:mm[:sec] format, with an optional “AM” or “PM”. Note that 12:06AM=0:06=0.1, and 1:30PM=13:30=13.5. This format works for hours but it does not imply any particular time units are being used. The AM and PM suffixes can be either lower or upper case.

Normally, time increases monotonically from one row to the next within each subject. If it does not, an error message is generated. However, if there is a reset column, time is allowed to be reset when that occurs. Also, if the /sort option is sent to the engine, data is automatically sorted by subject ID and time, so data does not have to be initially ordered.


  reset(resetColumnName=c(lowValue, highValue))

Example: reset(RESET=c(3, 4)) says that RESET is the data column signifying a resetting of subject time. If the value in the reset column is between three and four inclusive, time is allowed to be reset on that row. Also, all compartments in the model are reset to their initial values.


  date(dateColumnName[, formatString [, centuryBase]])

Examples:

     date(DATE)
     date(DATE, mdy)
     date(DATE, mdy, 1980)

says that DATE is the data column signifying the date. The default format of the date is month-day-year with arbitrary separators. If two-digit years are given, they are assumed to be between 1980–2079, which is the default.


  covr(covariateName <- columnName)

Example: covr(W <- BW) says that BW is the data column signifying the model covariate W. If the model contains covariate variables, then every covariate must be mapped in this way, or else an error message is generated.


  fcovr(covariateName <- columnName)

Example: fcovr(W <- BW)

fcovr is identical to covr, except for the handling of covariate value changes. A covariate is set whenever it has any non-null value in a data record. Normally if a covariate such as bodyweight (BW) is set to value BW1 at time T1, and another value BW2 is set to a subsequent time point T2, the second value BW2 holds during the interval (T1,T2), so it is carried back in time. Similarly, BW1 holds at time T1 and during the period extending back from T1 to T0, the closest previous time where the covariate is set.

If fcovr is used, the first value BW1 holds during the forward interval (T1,T2), and gets reset to BW2 at time T2. However, if the covariate is interpolated, it does not matter if covr or fcovr are used, because the value is linearly interpolated.


  obs(observedVariableName <- columnName)

Example: obs(cObs <- Conc) says that Conc is the data column signifying the observed variable. Use the obs mapping for all observation types such as observe, multi, count, event, and LL.

obs(cObs <- Conc, bql <- BQL) also says that the data column BQL contains the flag specifying that the observed value is less than or equal to the value in column Conc. To use this feature, it is also necessary that the bql option is used in the observe statement in the model.


  mdv(mdvColumnName)

Example: mdv(MDV) says that MDV is the data column signifying “missing data values” for any observation. If this column is present, then on any given row it specifies if there are any missing observations on that row. If the MDV value is 0 (zero) or “.”, then the observation on that row is present, otherwise it is missing.


  dose(dosepointName <- columnName)

Examples: dose(A1 <- Dose) says that Dose is the data column signifying the amount of drug administered to dosepoint A1.

dose(A1 <- Dose, Rate) also says that data column Rate specifies the infusion rate associated with the dose. If the rate is zero or unspecified, then the dose is a bolus. The concepts “bolus” and “infusion” are not limited to the central compartment but can apply to a dosepoint on any compartment, including an absorption compartment.

There are also the statements dose1 and dose2, whose syntax is identical to dose. These match up with the dosepoint1 and dosepoint2 statements in the model. This is because there can be more than one dosepoint with the same name, so multiple dosepoints are referred to by sequential numbers, such as dosepoint 1 and dosepoint 2. dose can be used as a synonym for dose1, and dosepoint can be used as a synonym for dosepoint1.


  ss(ss columnName, doseCycleDescription)

Examples:

     ss(SS, 10 bolus(A1) 24 dt)
     ss(SS, Dose bolus(A1) II dt)
     ss(SS, 10 bolus(A1) 16 dt 10 bolus(A1) 8 dt)

says that SS is the data column that brings the model to steady-state. On a given row, if the value in the SS column is other than 0 (zero) or “.”, the model is brought to steady state by running the dose cycle description as many times as necessary.

ss(SS, 10 bolus(A1) 24 dt) says the dose cycle is “administer 10 units of drug in a bolus to dosepoint A1, and then wait 24 time units.” The dose cycle description has a simple syntax in reverse polish notation (RPN):
number: Provide a number for an ensuing operation.
column-name: Provide a column name for ensuing operation.
bolus (dosepoint): Give the previous number as a bolus to a dosepoint.
dt: Sleep for the length of time of the preceding number
inf(dosepoint): Take the previous two numbers as an amount and a rate and give an infusion to a dosepoint.
bolus2, inf2: Same as bolus and inf but for dosepoint2.
value op value: Simple arithmetic operators. op=+, –, *, /, ^.

When defining a dose cycle, there must be at least one dt statement. In general, a dt statement should come at the end of the cycle, so that any infusions or time lags in the cycle finish before the start of the next cycle. If a dose occurs on the same data row as an ss statement, then the model is first brought to steady state, and then the dose is administered.


  addl(ssColumnName, doseCycleDescription)

Examples:

     addl(ADDL, 24 dt 10 bolus(A1))
     addl(ADDL, II dt Dose bolus(A1))

says that ADDL is the data column signifying additional doses. On a given row, if the value in the ADDL column is other than 0 (zero) or “.”, then additional dose cycles are given according to the dose cycle description.

The syntax of the dose cycle description is the same as for ss. The dt statement should come first in the dose cycle, since ADDL is usually specified on the same row as a dose, and it indicates follow-on doses.


  table(
     [optionalFile]
     [optionalDosepoints]
     [optionalCovariates]
     [optionalObservations]
     [optionalTimes]
     variableList
     )

Example:

     table(file="foo.csv"
         time(0,10,seq(2,8,0.1))
         dose(A1)
         covr(BW)
         obs(Conc)
         BW, C, cObs, V, Ke
         )

says a table is generated in file foo.csv, which consists of the variables BW, C, cObs, V, and Ke, whose values are generated at times 0, 2, 2.1,… 7.9, 8, and 10. (Note that the seq operator specifies a sequence of numbers, so seq(60,80,5) is shorthand for “60, 65, 70, 75, 80”). Values are also generated at the times of observations of Conc, when BW changes, and when a dose is given to A1. The times do not need to be specified in order, because they are automatically sorted. If multiple table statements are used, then multiple tables are generated.

The following are the contents of a column mapping file for the Theophylline model example:

   colstheo.txt 
   id(xid)
   covr(dose <- dose)
   covr(time <- time)
   obs(cObs <- yobs)