Calculate last dose amount and times since previous doses

This function calculates the last dose amount (LDOS), the time after last dose (TAD), time after first dose (TAFD), and observation occasion (OCC). Use lastdose() to add (or potentially replace) columns to the input data frame; lastdose_list() and lastdose_df() returns calculated information as either list or data.frame format without modifying the input data.

Usage

lastdose(
  data,
  ...,
  include_ldos = TRUE,
  include_tafd = getOption("lastdose.include_tafd", FALSE),
  include_occ = getOption("lastdose.include_occ", TRUE)
)

lastdose_list(
  data,
  time_col = find_time_col(data),
  time_units = getOption("lastdose.time_units", NULL),
  id_col = find_id_col(data),
  fill = -99,
  back_calc = TRUE,
  addl_ties = c("obs_first", "dose_first"),
  comments = find_comments(data),
  include_occ = getOption("lastdose.include_occ", TRUE)
)

lastdose_df(data, ...)

Arguments

data: data set as data frame; see details
...: arguments passed to lastdose_list()
include_ldos: logical; if FALSE then the LDOS data is not appended to the data set. Only used for the lastdose() function.
include_tafd: logical; if FALSE, then time after first dose (TAFD) data is not appended to the data set; this is only used for the lastdose() function.
include_occ: logical; if FALSE then observation occasion counter (OCC; see Details) is not appended to the data set.
time_col: character name for the TIME column; this could be time after first dose or time after first record or time relative to any origin; input may be numeric or POSIXct (e.g. DATETIME); if POSIXct, a numeric value will be calculated based on the value of time_units. The data frame will be searched for the first matching candidate time column using find_time_col(); if you don't want lastdose to search, you should pass in the name of the column to use for TIME.
time_units: for calculating time when the time column inherits POSIXct; you may use any value that is valid for difftime()
id_col: character name for the subject ID column; may be numeric or character; if character, a numeric value is derived. The data frame will be searched for the first matching candidate ID column using find_id_col(); if you don't want lastdose to search, you should pass in the name of the column to use for ID.
fill: the value for TAD and TAFD that is used for records when no doses are found for an individual or when back_calc is FALSE.
back_calc: if TRUE, then the time before the first dose is calculated for records prior to the first dosing record when at least one dosing record is found in the data set. Records before the first dosing record will have negative values.
addl_ties: what to do when doses scheduled through ADDL happen at the same time as observation records; if obs_first then the observation is assumed to happen before the dose and the observation is a trough concentration; if dose_first then the dose is assumed to be administered and the observation made immediately after (with no advance in time). See details.
comments: a logical vector with length equal to the number of rows in data indicating which records are to be ignored when looking for TAD and LDOS.

Details

When calling lastdose() to modify the data frame, two columns will be added (by default): TAD indicating the time after the most-recent dose, and LDOS indicating the amount of the most recent dose. TAFD indicating the time after the first dose record (EVID 1 or 4) can be added via the include_tafd argument and users can opt out from adding LDOS with the include_ldos argument.

When calling lastdose_list() or lastdose_df(), the respective items are accessible with tad, tafd, and ldos (note the lower case form here to distinguish from the columns that might be added to the data frame).

Time after first dose (TAFD): note that time after first dose (TAFD) is the time after the first dosing record (EVID 1 or 4) in the data frame that you pass in. If you don't have a dosing record for the first dose to anchor this calculation, you should opt out.

Occasion (OCC): observation occasions (OCC) occur when there is an observation record (with EVID=0) following a dose record (EVID 1 or 4); OCC starts at 0 and increments with each dose that is followed by at least one observation record. The OCC calculation ignores all commented records (doses or observations).

Handling of commented records: Dosing records that have been "commented" (as indicated with the comments argument) will never be considered as actual doses when determining TAD, TAFD, and LDOS. But commented records (doses and non-doses) will be assigned TAD, TAFD, and LDOS according to the last non-commented dosing record.

Additional notes:

All functions require an input data set as a data frame
The data set should be formatted according to NMTRAN type conventions
Required columns
- A subject ID column (either ID or user-specified)
- A record time column (either TIME or user-specified)
- AMT or amt: dose amount for dosing records
- EVID or evid: event ID; records with EVID or 1 or 4 are considered dosing records
Optional columns
- ADDL or addl: additional doses to administer
- II or ii: dosing interval
An error is generated if required columns are not found; no error or warning if optional columns are not found
All required and optional columns are required to be numeric
Missing values are not allowed in: ID, EVID, ADDL, II
When missing values are found in TIME, both TAD and LDOS are set to missing
An error is generated for missing AMT in dosing records (evid 1 or 4)
No error is generated for missing AMT in non-dosing records

An example illustrating the addl_ties argument: when there is Q24h dosing and both an an additional dose and an observation happen at 24 hours, obs_first will set the observation TAD to 24 and dose_first will set the observation TAD to 0.

Options

These are options that can be set to customize lastdose behavior for the current context. See ?options for how to set an option.

lastdose.time_units: sets the default time unit that is used to calculate relative times when the time column is represented as date-time data (POSIXct)
lastdose.id_col: sets the default value for the id_col argument to last dose; this identifies the column that is to be used to distinguish individuals; the data in this column may be numeric or character
lastdose.include_tafd: sets default value for include_tafd; if TRUE then the time since the first dose record (EVID 1 or EVID 4) in the data set will be automatically appended to the output data frame when calling lastdose(); tafd is always included when calling lastdose_df() and lastdose_list()

Examples

file <- system.file("csv/data1.csv", package="lastdose")

require("Rcpp")
#> Loading required package: Rcpp

data <- read.csv(file)

a <- lastdose(data)

b <- lastdose_df(data)

c <- lastdose_list(data)