Required Packages

The examples of this vignette require the following packages.

library(admiral)
library(admiralonco)
library(pharmaverseadam)
library(dplyr)
library(lubridate)

Read in Data

To start, all datasets needed for the creation of the time-to-event dataset should be read into the environment. This will be a company specific process.

For example purpose, the ADaM datasets—which are included in {pharmaverseadam}—are used. An alternative might be to use ADEVENT as input.

data("adsl")
data("adrs_onco")
adrs <- adrs_onco

Derive Parameters (CNSR, ADT, STARTDT)

To derive the parameter dependent variables like CNSR, ADT, STARTDT, EVNTDESC, SRCDOM, PARAMCD, … the admiral::derive_param_tte() function can be used. It adds one parameter to the input dataset with one observation per subject. Usually it is called several times.

For each subject it is determined if an event occurred. In the affirmative the analysis date ADT is set to the earliest event date. If no event occurred, the analysis date is set to the latest censoring date.

The events and censorings are defined by the admiral::event_source() and the admiral::censor_source() class respectively. It defines

• which observations (filter parameter) of a source dataset (dataset_name parameter) are potential events or censorings,
• the value of the CNSR variable (censor parameter), and
• which variable provides the date (date parameter).

The date can be provided as date (--DT variable), datetime (--DTM variable), or character ISO-8601 date (--DTC variable).

CDISC strongly recommends CNSR = 0 for events and positive integers for censorings. {admiral}/{admiralonco} enforce this recommendation. Therefore the censor parameter is available for admiral::censor_source() only. It is defaulted to 1.

The dataset_name parameter expects a character value which is used as an identifier. The actual data which is used for the derivation of the parameter is provided via the source_datasets parameter of admiral::derive_param_tte(). It expects a named list of datasets. The names correspond to the identifiers specified for the dataset_name parameter. This allows to define events and censoring independent of the data.

adsl_death_event <- event_source(
  dataset_name = "adsl",
  date = DTHDT,
  set_values_to = exprs(
    EVNTDESC = "STUDY DEATH",
    SRCDOM = "ADSL",
    SRCVAR = "DTHDT"
  )
)

adsl <- adsl %>%
  derive_vars_merged(
    dataset_add = adrs,
    filter_add = PARAMCD == "RSP" & AVALC == "Y" & ANL01FL == "Y",
    by_vars = get_admiral_option("subject_keys"),
    new_vars = exprs(TEMP_RESPDT = ADT)
  )

adtte <- derive_param_tte(
  dataset_adsl = adsl,
  start_date = RANDDT,
  event_conditions = list(death_event),
  censor_conditions = list(lastalive_censor, rand_censor),
  source_datasets = list(adsl = adsl, adrs = adrs),
  set_values_to = exprs(PARAMCD = "OS", PARAM = "Overall Survival")
) %>%
  derive_param_tte(
    dataset_adsl = adsl,
    start_date = RANDDT,
    event_conditions = list(pd_event, death_event),
    censor_conditions = list(lasta_censor, rand_censor),
    source_datasets = list(adsl = adsl, adrs = adrs),
    set_values_to = exprs(PARAMCD = "PFS", PARAM = "Progression Free Survival")
  ) %>%
  derive_param_tte(
    dataset_adsl = filter(adsl, !is.na(TEMP_RESPDT)),
    start_date = TEMP_RESPDT,
    event_conditions = list(pd_event, death_event),
    censor_conditions = list(lasta_censor),
    source_datasets = list(adsl = adsl, adrs = adrs),
    set_values_to = exprs(PARAMCD = "RSD", PARAM = "Duration of Response")
  )

pd_nact_event <- event_source(
  dataset_name = "adsl",
  filter = PDDT < NACTDT | is.na(NACTDT),
  date = PDDT,
  set_values_to = exprs(
    EVNTDESC = "Disease Progression prior to NACT",
    SRCDOM = "ADSL",
    SRCVAR = "PDDT"
  )
)

death_nact_event <- event_source(
  dataset_name = "adsl",
  filter = DTHDT < NACTDT | is.na(NACTDT),
  date = DTHDT,
  set_values_to = exprs(
    EVNTDESC = "Death prior to NACT",
    SRCDOM = "ADSL",
    SRCVAR = "DTHDT"
  )
)

lasta_nact_censor <- censor_source(
  dataset_name = "adsl",
  date = LASTANDT,
  set_values_to = exprs(
    EVNTDESC = "Last Tumor Assessment prior to NACT",
    CNSDTDSC = "Last Tumor Assessment prior to NACT",
    SRCDOM = "ADSL",
    SRCVAR = "LASTANDT"
  )
)

adtte <- derive_param_tte(
  dataset_adsl = adsl,
  start_date = RANDDT,
  event_conditions = list(pd_nact_event, death_nact_event),
  censor_conditions = list(lasta_nact_censor, rand_censor),
  source_datasets = list(adsl = adsl),
  set_values_to = exprs(PARAMCD = "PFSNACT", PARAM = "Progression Free Survival prior to NACT")
)

Derive Analysis Value (AVAL)

The analysis value (AVAL) can be derived by calling admiral::derive_vars_duration().

This example derives the time to event in days.

adtte <- adtte %>%
  derive_vars_duration(
    new_var = AVAL,
    start_date = STARTDT,
    end_date = ADT
  )

Other time units, such as months that we commonly see in oncology analyses, can be requested by specifying the out_unit parameter. See the example below. Note that because of the underlying lubridate::time_length() function that is used here this may perform slightly differently to your expectations, e.g. both time_length(ymd("2021-01-01") %--% ymd("2021-02-01"), "month") and time_length(ymd("2021-02-01") %--% ymd("2021-03-01"), "month") results in exactly 1 month, which is a logical approach but it gives a different result to the convention of assuming every month has exactly equal days and just using /30.4375 here or some other such convention. The difference would only be noticed for small durations, but if the user prefers an alternative approach they could calculate in the default days and then add extra processing to convert to months with their company-specific convention.

adtte_months <- adtte %>%
  derive_vars_duration(
    new_var = AVAL,
    start_date = STARTDT,
    end_date = ADT,
    out_unit = "months"
  )

Derive Analysis Sequence Number (ASEQ)

The {admiral} function admiral::derive_var_obs_number() can be used to derive ASEQ:

adtte <- adtte %>%
  derive_var_obs_number(
    by_vars = get_admiral_option("subject_keys"),
    order = exprs(PARAMCD),
    check_type = "error"
  )

Add ADSL Variables

Variables from ADSL which are required for time-to-event analyses, e.g., treatment variables or covariates can be added using admiral::derive_vars_merged().

adtte <- adtte %>%
  derive_vars_merged(
    dataset_add = adsl,
    new_vars = exprs(ARMCD, ARM, ACTARMCD, ACTARM, AGE, SEX),
    by_vars = get_admiral_option("subject_keys")
  )