Derive a Time-to-Event Parameter

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

Usage

derive_param_tte(
  dataset = NULL,
  dataset_adsl,
  source_datasets,
  by_vars = NULL,
  start_date = TRTSDT,
  event_conditions,
  censor_conditions,
  create_datetime = FALSE,
  set_values_to,
  subject_keys = get_admiral_option("subject_keys"),
  check_type = "warning"
)

Arguments

dataset

Input dataset PARAMCD is expected.

dataset_adsl

ADSL input dataset

The variables specified for start_date, 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.

Permitted Values: list of variables created by exprs() e.g. exprs(USUBJID, VISIT)

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.

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 exprs() defining the variables to be set for the new parameter, e.g. exprs(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 exprs() is expected.

check_type

Check uniqueness

If "warning", "message", or "error" is specified, the specified message is issued if the observations of the source datasets are not unique with respect to the by variables and the date and order specified in the event_source() and censor_source() objects.

Permitted Values: "none", "message", "warning", "error"

Value

The input dataset with the new parameter added

Details

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 and order) 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.
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/ADTM variable) from the single dataset is selected. If there is more than one event with the same date, the first event with respect to the order of events in event_conditions 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 and order) 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.
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/ADTM variable) from the single dataset is selected. If there is more than one censoring with the same date, the last censoring with respect to the order of censorings in censor_conditions 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 variable specified for start_date is joined from the ADSL dataset. Only subjects in both datasets are kept, i.e., subjects with both an event or censoring and an observation in dataset_adsl.
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).
The new observations are added to the output dataset.

Examples

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

adsl <- admiral_adsl

# derive overall survival parameter
death <- event_source(
  dataset_name = "adsl",
  filter = DTHFL == "Y",
  date = DTHDT,
  set_values_to = exprs(
    EVNTDESC = "DEATH",
    SRCDOM = "ADSL",
    SRCVAR = "DTHDT"
  )
)

last_alive_dt <- censor_source(
  dataset_name = "adsl",
  date = LSTALVDT,
  set_values_to = exprs(
    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 = exprs(
    PARAMCD = "OS",
    PARAM = "Overall Survival"
  )
) %>%
  select(-STUDYID) %>%
  filter(row_number() %in% 20:30)
#> # A tibble: 11 × 9
#>    USUBJID     EVNTDESC  SRCDOM SRCVAR  CNSR ADT        STARTDT    PARAMCD PARAM
#>    <chr>       <chr>     <chr>  <chr>  <int> <date>     <date>     <chr>   <chr>
#>  1 01-701-1203 LAST DAT… ADSL   LSTAL…     1 2013-08-03 2013-02-02 OS      Over…
#>  2 01-701-1211 DEATH     ADSL   DTHDT      0 2013-01-14 2012-11-15 OS      Over…
#>  3 01-701-1234 LAST DAT… ADSL   LSTAL…     1 2013-09-22 2013-03-30 OS      Over…
#>  4 01-701-1239 LAST DAT… ADSL   LSTAL…     1 2014-07-11 2014-01-11 OS      Over…
#>  5 01-701-1275 LAST DAT… ADSL   LSTAL…     1 2014-06-14 2014-02-07 OS      Over…
#>  6 01-701-1287 LAST DAT… ADSL   LSTAL…     1 2014-07-26 2014-01-25 OS      Over…
#>  7 01-701-1294 LAST DAT… ADSL   LSTAL…     1 2013-06-14 2013-03-24 OS      Over…
#>  8 01-701-1302 LAST DAT… ADSL   LSTAL…     1 2013-11-05 2013-08-29 OS      Over…
#>  9 01-701-1317 LAST DAT… ADSL   LSTAL…     1 2014-11-20 2014-05-22 OS      Over…
#> 10 01-701-1324 LAST DAT… ADSL   LSTAL…     1 2013-04-02 2012-10-02 OS      Over…
#> 11 01-701-1341 LAST DAT… ADSL   LSTAL…     1 2013-02-07 2013-01-05 OS      Over…

# derive duration of response
# only observations for subjects in dataset_adsl are created
adsl <- tribble(
  ~USUBJID, ~DTHFL, ~DTHDT,            ~RSPDT,
  "01",     "Y",    ymd("2021-06-12"), ymd("2021-03-04"),
  "02",     "N",    NA,                NA,
  "03",     "Y",    ymd("2021-08-21"), NA,
  "04",     "N",    NA,                ymd("2021-04-14")
) %>%
  mutate(STUDYID = "AB42")

adrs <- tribble(
  ~USUBJID, ~AVALC, ~ADT,              ~ASEQ,
  "01",     "SD",   ymd("2021-01-03"), 1,
  "01",     "PR",   ymd("2021-03-04"), 2,
  "01",     "PD",   ymd("2021-05-05"), 3,
  "02",     "PD",   ymd("2021-02-03"), 1,
  "04",     "SD",   ymd("2021-02-13"), 1,
  "04",     "PR",   ymd("2021-04-14"), 2,
  "04",     "CR",   ymd("2021-05-15"), 3
) %>%
  mutate(STUDYID = "AB42", PARAMCD = "OVR")

pd <- event_source(
  dataset_name = "adrs",
  filter = AVALC == "PD",
  date = ADT,
  set_values_to = exprs(
    EVENTDESC = "PD",
    SRCDOM = "ADRS",
    SRCVAR = "ADTM",
    SRCSEQ = ASEQ
  )
)

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

lastvisit <- censor_source(
  dataset_name = "adrs",
  date = ADT,
  censor = 1,
  set_values_to = exprs(
    EVENTDESC = "LAST TUMOR ASSESSMENT",
    SRCDOM = "ADRS",
    SRCVAR = "ADTM",
    SRCSEQ = ASEQ
  )
)

first_response <- censor_source(
  dataset_name = "adsl",
  date = RSPDT,
  censor = 1,
  set_values_to = exprs(
    EVENTDESC = "FIRST RESPONSE",
    SRCDOM = "ADSL",
    SRCVAR = "RSPDT"
  )
)

derive_param_tte(
  dataset_adsl = filter(adsl, !is.na(RSPDT)),
  start_date = RSPDT,
  event_conditions = list(pd, death),
  censor_conditions = list(lastvisit, first_response),
  source_datasets = list(adsl = adsl, adrs = adrs),
  set_values_to = exprs(
    PARAMCD = "DURRSP",
    PARAM = "Duration of Response"
  )
)
#> # A tibble: 2 × 11
#>   USUBJID ADT        STUDYID EVENTDESC     SRCDOM SRCVAR SRCSEQ  CNSR STARTDT   
#>   <chr>   <date>     <chr>   <chr>         <chr>  <chr>   <dbl> <int> <date>    
#> 1 01      2021-05-05 AB42    PD            ADRS   ADTM        3     0 2021-03-04
#> 2 04      2021-05-15 AB42    LAST TUMOR A… ADRS   ADTM        3     1 2021-04-14
#> # ℹ 2 more variables: PARAMCD <chr>, PARAM <chr>

# derive time to adverse event for each preferred term
adsl <- 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 <- 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")

ae_ext <- derive_vars_dt(
  ae,
  dtc = AESTDTC,
  new_vars_prefix = "AEST",
  highest_imputation = "M",
  flag_imputation = "none"
)

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

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

derive_param_tte(
  dataset_adsl = adsl,
  by_vars = exprs(AEDECOD),
  start_date = TRTSDT,
  event_conditions = list(ttae),
  censor_conditions = list(eos),
  source_datasets = list(adsl = adsl, ae = ae_ext),
  set_values_to = exprs(
    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)
#> # A tibble: 4 × 7
#>   USUBJID STARTDT    PARAMCD PARAM                       ADT         CNSR SRCSEQ
#>   <chr>   <date>     <chr>   <chr>                       <date>     <int>  <dbl>
#> 1 01      2020-12-06 TTAE1   Time to First Cough Advers… 2021-03-04     0      2
#> 2 01      2020-12-06 TTAE2   Time to First Flu Adverse … 2021-01-01     0      3
#> 3 02      2021-01-16 TTAE1   Time to First Cough Advers… 2021-02-03     1     NA
#> 4 02      2021-01-16 TTAE2   Time to First Flu Adverse … 2021-02-03     1     NA

# Resolve tie when serious AE share a date by sorting with order argument
adsl <- 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 <- tribble(
  ~USUBJID, ~AESTDTC,     ~AESEQ, ~AESER, ~AEDECOD,
  "01",     "2021-01-03",      1, "Y",    "Flu",
  "01",     "2021-01-03",      2, "Y",    "Cough",
  "01",     "2021-01-20",      3, "N",    "Headache"
) %>% mutate(
  AESTDT = ymd(AESTDTC),
  STUDYID = "AB42"
)

derive_param_tte(
  dataset_adsl = adsl,
  start_date = TRTSDT,
  source_datasets = list(adsl = adsl, ae = ae),
  event_conditions = list(event_source(
    dataset_name = "ae",
    date = AESTDT,
    set_values_to = exprs(
      EVENTDESC = "Serious AE",
      SRCSEQ = AESEQ
    ),
    filter = AESER == "Y",
    order = exprs(AESEQ)
  )),
  censor_conditions = list(censor_source(
    dataset_name = "adsl",
    date = EOSDT,
    censor = 1,
    set_values_to = exprs(EVENTDESC = "End of Study")
  )),
  set_values_to = exprs(
    PARAMCD = "TTSAE",
    PARAM = "Time to First Serious AE"
  )
)
#> # A tibble: 2 × 9
#>   USUBJID STUDYID EVENTDESC    SRCSEQ  CNSR ADT        STARTDT    PARAMCD PARAM 
#>   <chr>   <chr>   <chr>         <dbl> <int> <date>     <date>     <chr>   <chr> 
#> 1 01      AB42    Serious AE        1     0 2021-01-03 2020-12-06 TTSAE   Time …
#> 2 02      AB42    End of Study     NA     1 2021-02-03 2021-01-16 TTSAE   Time …

Usage

Arguments

Value

Details

See also

Examples