Disposition Dates (e.g. EOSDT)

The functions derive_vars_dt() and derive_vars_merged() can be used to derive a disposition date. First the character disposition date (DS.DSSTDTC) is converted to a numeric date (DSSTDT) calling derive_vars_dt(). The DS dataset is extended by the DSSTDT variable because the date is required by other derivations, e.g., RANDDT as well. Then the relevant disposition date is selected by adjusting the filter_add argument.

To add the End of Study date (EOSDT) to the input dataset, a call could be:

# convert character date to numeric date without imputation
ds_ext <- derive_vars_dt(
  ds,
  dtc = DSSTDTC,
  new_vars_prefix = "DSST"
)

adsl <- adsl %>%
  derive_vars_merged(
    dataset_add = ds_ext,
    by_vars = exprs(STUDYID, USUBJID),
    new_vars = exprs(EOSDT = DSSTDT),
    filter_add = DSCAT == "DISPOSITION EVENT" & DSDECOD != "SCREEN FAILURE"
  )

The ds_ext dataset:

The adsl dataset:

The derive_vars_dt() function allows to impute partial dates as well. If imputation is needed and missing days are to be imputed to the first of the month and missing months to the first month of the year, set highest_imputation = "M".

Disposition Status (e.g. EOSSTT)

The function derive_vars_merged() can be used to derive the End of Study status (EOSSTT) based on DSCAT and DSDECOD from DS. The relevant observations are selected by adjusting the filter_add argument. A function mapping DSDECOD values to EOSSTT values can be defined and used in the new_vars argument. The mapping for the call below is

• "COMPLETED" if DSDECOD == "COMPLETED"
• NA_character_ if DSDECOD is "SCREEN FAILURE"
• "DISCONTINUED" otherwise

Example function format_eosstt():

format_eosstt <- function(x) {
  case_when(
    x %in% c("COMPLETED") ~ "COMPLETED",
    x %in% c("SCREEN FAILURE") ~ NA_character_,
    TRUE ~ "DISCONTINUED"
  )
}

The customized mapping function format_eosstt() can now be passed to the main function. For subjects without a disposition event the end of study status is set to "ONGOING" by specifying the missing_values argument.

adsl <- adsl %>%
  derive_vars_merged(
    dataset_add = ds,
    by_vars = exprs(STUDYID, USUBJID),
    filter_add = DSCAT == "DISPOSITION EVENT",
    new_vars = exprs(EOSSTT = format_eosstt(DSDECOD)),
    missing_values = exprs(EOSSTT = "ONGOING")
  )

This call would return the input dataset with the column EOSSTT added.

If the derivation must be changed, the user can create his/her own function to map DSDECOD to a suitable EOSSTT value.

Disposition Reason(s) (e.g. DCSREAS, DCSREASP)

The main reason for discontinuation is usually stored in DSDECOD while DSTERM provides additional details regarding subject’s discontinuation (e.g., description of "OTHER").

The function derive_vars_merged() can be used to derive a disposition reason (along with the details, if required) at a specific timepoint. The relevant observations are selected by adjusting the filter_add argument.

To derive the End of Study reason(s) (DCSREAS and DCSREASP), the function will map DCSREAS as DSDECOD, and DCSREASP as DSTERM if DSDECOD is not "COMPLETED", "SCREEN FAILURE", or NA, NA otherwise.

adsl <- adsl %>%
  derive_vars_merged(
    dataset_add = ds,
    by_vars = exprs(USUBJID),
    new_vars = exprs(DCSREAS = DSDECOD, DCSREASP = DSTERM),
    filter_add = DSCAT == "DISPOSITION EVENT" &
      !(DSDECOD %in% c("SCREEN FAILURE", "COMPLETED", NA))
  )

This call would return the input dataset with the column DCSREAS and DCSREASP added.

If the derivation must be changed, the user can define that derivation in the filter_add argument of the function to map DSDECOD and DSTERM to a suitable DCSREAS/DCSREASP value.

The call below maps DCSREAS and DCREASP as follows:

• DCSREAS as DSDECOD if DSDECOD is not "COMPLETED" or NA, NA otherwise
• DCSREASP as DSTERM if DSDECOD is equal to OTHER, NA otherwise

adsl <- adsl %>%
  derive_vars_merged(
    dataset_add = ds,
    by_vars = exprs(USUBJID),
    new_vars = exprs(DCSREAS = DSDECOD),
    filter_add = DSCAT == "DISPOSITION EVENT" &
      DSDECOD %notin% c("SCREEN FAILURE", "COMPLETED", NA)
  ) %>%
  derive_vars_merged(
    dataset_add = ds,
    by_vars = exprs(USUBJID),
    new_vars = exprs(DCSREASP = DSTERM),
    filter_add = DSCAT == "DISPOSITION EVENT" & DSDECOD %in% "OTHER"
  )

Randomization Date (RANDDT)

The function derive_vars_merged() can be used to derive randomization date variable. To map Randomization Date (RANDDT), the call would be:

adsl <- adsl %>%
  derive_vars_merged(
    dataset_add = ds_ext,
    filter_add = DSDECOD == "RANDOMIZED",
    by_vars = exprs(STUDYID, USUBJID),
    new_vars = exprs(RANDDT = DSSTDT)
  )

This call would return the input dataset with the column RANDDT is added.

Death Date (DTHDT)

The function derive_vars_dt() can be used to derive DTHDT. This function allows the user to impute the date as well.

Example calls:

adsl <- adsl %>%
  derive_vars_dt(
    new_vars_prefix = "DTH",
    dtc = DTHDTC
  )

This call would return the input dataset with the columns DTHDT added and, by default, the associated date imputation flag (DTHDTF) populated with the controlled terminology outlined in the ADaM IG for date imputations. If the imputation flag is not required, the user must set the argument flag_imputation to "none".

If imputation is needed and the date is to be imputed to the first day of the month/year the call would be:

adsl <- adsl %>%
  derive_vars_dt(
    new_vars_prefix = "DTH",
    dtc = DTHDTC,
    date_imputation = "first"
  )

See also Date and Time Imputation.

Cause of Death (DTHCAUS)

The cause of death DTHCAUS can be derived using the function derive_vars_extreme_event().

Since the cause of death could be collected/mapped in different domains (e.g. DS, AE, DD), it is important the user specifies the right source(s) to derive the cause of death from.

For example, if the date of death is collected in the AE form when the AE is Fatal, the cause of death would be set to the preferred term (AEDECOD) of that Fatal AE, while if the date of death is collected in the DS form, the cause of death would be set to the disposition term (DSTERM). To achieve this, the event() objects within derive_vars_extreme_event() must be specified and defined such that they fit the study requirement.

An example call to derive_vars_extreme_event() would be:

adsl <- adsl %>%
  derive_vars_extreme_event(
    by_vars = exprs(STUDYID, USUBJID),
    events = list(
      event(
        dataset_name = "ae",
        condition = AEOUT == "FATAL",
        set_values_to = exprs(DTHCAUS = AEDECOD),
      ),
      event(
        dataset_name = "ds",
        condition = DSDECOD == "DEATH" & grepl("DEATH DUE TO", DSTERM),
        set_values_to = exprs(DTHCAUS = DSTERM),
      )
    ),
    source_datasets = list(ae = ae, ds = ds),
    tmp_event_nr_var = event_nr,
    order = exprs(event_nr),
    mode = "first",
    new_vars = exprs(DTHCAUS)
  )

The function also offers the option to add some traceability variables (e.g. DTHDOM would store the domain where the date of death is collected, and DTHSEQ would store the xxSEQ value of that domain). The traceability variables should be added to the event() calls and included in the new_vars parameter of derive_vars_extreme_event().

adsl <- adsl %>%
  select(-DTHCAUS) %>% # remove it before deriving it again
  derive_vars_extreme_event(
    by_vars = exprs(STUDYID, USUBJID),
    events = list(
      event(
        dataset_name = "ae",
        condition = AEOUT == "FATAL",
        set_values_to = exprs(DTHCAUS = AEDECOD, DTHDOM = "AE", DTHSEQ = AESEQ),
      ),
      event(
        dataset_name = "ds",
        condition = DSDECOD == "DEATH" & grepl("DEATH DUE TO", DSTERM),
        set_values_to = exprs(DTHCAUS = DSTERM, DTHDOM = "DS", DTHSEQ = DSSEQ),
      )
    ),
    source_datasets = list(ae = ae, ds = ds),
    tmp_event_nr_var = event_nr,
    order = exprs(event_nr),
    mode = "first",
    new_vars = exprs(DTHCAUS, DTHDOM, DTHSEQ)
  )

Following the derivation of DTHCAUS and related traceability variables, it is then possible to derive grouping variables such as death categories (DTHCGRx) using standard tidyverse code.

adsl <- adsl %>%
  mutate(DTHCGR1 = case_when(
    is.na(DTHDOM) ~ NA_character_,
    DTHDOM == "AE" ~ "ADVERSE EVENT",
    str_detect(DTHCAUS, "(PROGRESSIVE DISEASE|DISEASE RELAPSE)") ~ "PROGRESSIVE DISEASE",
    TRUE ~ "OTHER"
  ))

Duration Relative to Death

The function derive_vars_duration() can be used to derive duration relative to death like the Relative Day of Death (DTHADY) or the numbers of days from last dose to death (LDDTHELD).

Example calls:

• Relative Day of Death

adsl <- adsl %>%
  derive_vars_duration(
    new_var = DTHADY,
    start_date = TRTSDT,
    end_date = DTHDT
  )

• Elapsed Days from Last Dose to Death

adsl <- adsl %>%
  derive_vars_duration(
    new_var = LDDTHELD,
    start_date = TRTEDT,
    end_date = DTHDT,
    add_one = FALSE
  )

Grouping (e.g. AGEGR1 or REGION1)

Numeric and categorical variables (AGE, RACE, COUNTRY, etc.) may need to be grouped to perform the required analysis. {admiral} provides the derive_vars_cat() function to create such groups. This function is especially useful if more than one variable needs to be created for each condition, e.g., AGEGR1 and AGEGR1N.

Additionally, one needs to be careful when considering the order of the conditions in the lookup table. The category is assigned based on the first match. That means catch-all conditions must come after specific conditions, e.g. !is.na(AGE) must come after AGE < 18.

# create lookup tables
agegr1_lookup <- exprs(
  ~condition,           ~AGEGR1,
  AGE < 18,               "<18",
  between(AGE, 18, 64), "18-64",
  AGE > 64,               ">64",
  is.na(AGE),         "Missing"
)

region1_lookup <- exprs(
  ~condition,                          ~REGION1,
  COUNTRY %in% c("CAN", "USA"), "North America",
  !is.na(COUNTRY),          "Rest of the World",
  is.na(COUNTRY),                     "Missing"
)

adsl <- adsl %>%
  derive_vars_cat(
    definition = agegr1_lookup
  ) %>%
  derive_vars_cat(
    definition = region1_lookup
  )

Alternatively, you can also solve this task with custom functions:

format_agegr1 <- function(var_input) {
  case_when(
    var_input < 18 ~ "<18",
    between(var_input, 18, 64) ~ "18-64",
    var_input > 64 ~ ">64",
    TRUE ~ "Missing"
  )
}
format_region1 <- function(var_input) {
  case_when(
    var_input %in% c("CAN", "USA") ~ "North America",
    !is.na(var_input) ~ "Rest of the World",
    TRUE ~ "Missing"
  )
}

adsl %>%
  mutate(
    AGEGR1 = format_agegr1(AGE),
    REGION1 = format_region1(COUNTRY)
  )

Population Flags (e.g. SAFFL)

Since the populations flags are mainly company/study specific no dedicated functions are provided, but in most cases they can easily be derived using derive_var_merged_exist_flag.

An example of an implementation could be:

adsl <- adsl %>%
  derive_var_merged_exist_flag(
    dataset_add = ex,
    by_vars = exprs(STUDYID, USUBJID),
    new_var = SAFFL,
    condition = (EXDOSE > 0 | (EXDOSE == 0 & str_detect(EXTRT, "PLACEBO")))
  )