derive_param_tte: Derive a Time-to-Event Parameter
In epijim/admiral: ADaM in R Asset Library

Description Usage Arguments Details Value Author(s) Examples

Add a time-to-event parameter to the input dataset.

derive_param_tte(
  dataset = NULL,
  dataset_adsl,
  source_datasets,
  by_vars = NULL,
  start_date = TRTSDT,
  start_date_imputation_flag = NULL,
  start_time_imputation_flag = NULL,
  event_conditions,
  censor_conditions,
  create_datetime = FALSE,
  set_values_to,
  subject_keys = vars(STUDYID, USUBJID)
)

`dataset`	Input dataset The `PARAMCD` variable is expected.
`dataset_adsl`	ADSL input dataset The variables specified for `start_date`, `start_imputation_flag`, and `subject_keys` are expected.
`source_datasets`	Source datasets A named list of datasets is expected. The `dataset_name` field of `tte_source()` refers to the dataset provided in the list.
`by_vars`	By variables If the parameter is specified, separate time to event parameters are derived for each by group. The by variables must be in at least one of the source datasets. Each source dataset must contain either all by variables or none of the by variables. The by variables are not included in the output dataset.
`start_date`	Time to event origin date The variable `STARTDT` is set to the specified date. The value is taken from the ADSL dataset. If the event or censoring date is before the origin date, `ADT` is set to the origin date. If the specified variable is imputed, the corresponding date imputation flag must specified for `start_imputation_flag`.
`start_date_imputation_flag`	Date imputation flag for start date If the start date is imputed, the corresponding date imputation flag must be specified. The variable `STARTDTF` is set to the specified variable.
`start_time_imputation_flag`	Time imputation flag for start date If the start time is imputed, the corresponding time imputation flag must be specified. The variable `STARTTMF` is set to the specified variable.
`event_conditions`	Sources and conditions defining events A list of `event_source()` objects is expected.
`censor_conditions`	Sources and conditions defining censorings A list of `censor_source()` objects is expected.
`create_datetime`	Create datetime variables? If set to `TRUE`, variables `ADTM` and `STARTDTM` are created. Otherwise, variables `ADT` and `STARTDT` are created.
`set_values_to`	Variables to set A named list returned by `vars()` defining the variables to be set for the new parameter, e.g. `vars(PARAMCD = "OS", PARAM = "Overall Survival")` is expected. The values must be symbols, character strings, numeric values, expressions, or `NA`.
`subject_keys`	Variables to uniquely identify a subject A list of symbols created using `vars()` is expected.

The following steps are performed to create the observations of the new parameter:

Deriving the events:

For each event source dataset the observations as specified by the filter element are selected. Then for each patient the first observation (with respect to date) is selected.
The ADT variable is set to the variable specified by the date element. If the date variable is a datetime variable, only the datepart is copied. If the source variable is a character variable, it is converted to a date. If the date is incomplete, it is imputed as the first possible date.
The CNSR variable is added and set to the censor element.
The variables specified by the set_values_to element are added.
The selected observations of all event source datasets are combined into a single dataset.
For each patient the first observation (with respect to the ADT variable) from the single dataset is selected.

Deriving the censoring observations:

For each censoring source dataset the observations as specified by the filter element are selected. Then for each patient the last observation (with respect to date) is selected.
The ADT variable is set to the variable specified by the date element. If the date variable is a datetime variable, only the datepart is copied. If the source variable is a character variable, it is converted to a date. If the date is incomplete, it is imputed as the first possible date.
The CNSR variable is added and set to the censor element.
The variables specified by the set_values_to element are added.
The selected observations of all censoring source datasets are combined into a single dataset.
For each patient the last observation (with respect to the ADT variable) from the single dataset is selected.

For each subject (as defined by the subject_keys parameter) an observation is selected. If an event is available, the event observation is selected. Otherwise the censoring observation is selected.

Finally

the variables specified for start_date and start_imputation_flag are joined from the ADSL dataset,
the variables as defined by the set_values_to parameter are added,
the ADT/ADTM variable is set to the maximum of ADT/ADTM and STARTDT/STARTDTM (depending on the create_datetime parameter), and
the new observations are added to the output dataset.

The input dataset with the new parameter added

Stefan Bundfuss

library(dplyr, warn.conflicts = FALSE)
library(lubridate, warn.conflicts = FALSE)
data("adsl")

death <- event_source(
  dataset_name = "adsl",
  filter = DTHFL == "Y",
  date = DTHDT,
  set_values_to = vars(
    EVNTDESC = "DEATH",
    SRCDOM = "ADSL",
    SRCVAR = "DTHDT"
  )
)

last_alive_dt <- censor_source(
  dataset_name = "adsl",
  date = LSTALVDT,
  set_values_to = vars(
    EVNTDESC = "LAST DATE KNOWN ALIVE",
    SRCDOM = "ADSL",
    SRCVAR = "LSTALVDT"
  )
)

derive_param_tte(
  dataset_adsl = adsl,
  event_conditions = list(death),
  censor_conditions = list(last_alive_dt),
  source_datasets = list(adsl = adsl),
  set_values_to = vars(
    PARAMCD = "OS",
    PARAM = "Overall Survival"
  )
) %>%
  select(-STUDYID) %>%
  filter(row_number() %in% 20:30)

# derive time to adverse event for each preferred term #
adsl <- tibble::tribble(
  ~USUBJID, ~TRTSDT,           ~EOSDT,
  "01",     ymd("2020-12-06"), ymd("2021-03-06"),
  "02",     ymd("2021-01-16"), ymd("2021-02-03")
) %>%
  mutate(STUDYID = "AB42")

ae <- tibble::tribble(
  ~USUBJID, ~AESTDTC,           ~AESEQ, ~AEDECOD,
  "01",     "2021-01-03T10:56", 1,      "Flu",
  "01",     "2021-03-04",       2,      "Cough",
  "01",     "2021",             3,      "Flu"
) %>%
  mutate(STUDYID = "AB42")

ttae <- event_source(
  dataset_name = "ae",
  date = AESTDTC,
  set_values_to = vars(
    EVNTDESC = "AE",
    SRCDOM = "AE",
    SRCVAR = "AESTDTC",
    SRCSEQ = AESEQ
  )
)

eos <- censor_source(
  dataset_name = "adsl",
  date = EOSDT,
  set_values_to = vars(
    EVNTDESC = "END OF STUDY",
    SRCDOM = "ADSL",
    SRCVAR = "EOSDT"
  )
)

derive_param_tte(
  dataset_adsl = adsl,
  by_vars = vars(AEDECOD),
  start_date = TRTSDT,
  event_conditions = list(ttae),
  censor_conditions = list(eos),
  source_datasets = list(adsl = adsl, ae = ae),
  set_values_to = vars(
    PARAMCD = paste0("TTAE", as.numeric(as.factor(AEDECOD))),
    PARAM = paste("Time to First", AEDECOD, "Adverse Event"),
    PARCAT1 = "TTAE",
    PARCAT2 = AEDECOD
  )
) %>%
  select(USUBJID, STARTDT, PARAMCD, PARAM, ADT, CNSR, SRCSEQ)