This function calculates the last dose amount (LDOS), the time after
last dose (TAD), and time after first dose (TAFD). 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.
lastdose(
data,
...,
include_ldos = TRUE,
include_tafd = getOption("lastdose.include_tafd", FALSE)
)
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)
)
lastdose_df(data, ...)data set as data frame; see details
arguments passed to lastdose_list()
logical; if FALSE then the LDOS data is not
appended to the data set. Only used for the lastdose() function.
logical; if FALSE, then TAFD data is not appended
to the data set. Only used for the lastdose() function.
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.
for calculating time when the time column inherits
POSIXct; you may use any value that is valid for difftime()
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.
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.
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.
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.
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.
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: 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.
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.
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()
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)