Skip to contents

Add an Extreme Event Parameter

Source: R/derive_param_extreme_event.R
derive_param_extreme_event.Rd

Add a new parameter for the first or last event occurring in a dataset. The variable given in new_var indicates if an event occurred or not. For example, the function can derive a parameter for the first disease progression.

Usage

derive_param_extreme_event(
  dataset = NULL,
  dataset_adsl,
  dataset_source,
  filter_source,
  order = NULL,
  new_var = NULL,
  true_value = "Y",
  false_value = "N",
  mode = "first",
  subject_keys = get_admiral_option("subject_keys"),
  set_values_to,
  check_type = "warning"
)

Arguments

dataset

Input dataset

The PARAMCD variable is expected.

dataset_adsl

ADSL input dataset

The variables specified for subject_keys are expected. For each observation of the specified dataset a new observation is added to the input dataset.

dataset_source

Source dataset

All observations in the specified dataset fulfilling the condition specified by filter_source are considered as an event.

The variables specified by the subject_keys and order parameter (if applicable) are expected.

filter_source

Source filter

All observations in dataset_source fulfilling the specified condition are considered as an event.

For subjects with at least one event new_var is set to true_value.

For all other subjects new_var is set to false_value.

order

Order variable

List of symbols for sorting the source dataset (dataset_source).

Permitted Values: list of variables or desc(<variable>) function calls created by exprs(), e.g., exprs(ADT, desc(AVAL)).

new_var

New variable

The name of the variable which will indicate whether an event happened or not.

true_value

True value

For all subjects with at least one observation in the source dataset (dataset_source) fulfilling the event condition (filter_source), new_var is set to the specified value true_value.

false_value

False value

For all other subjects in dataset_adsl without an event, new_var is set to the specified value false_value.

mode

Selection mode (first or last)

If "first" is specified, the first observation of each subject is selected. If "last" is specified, the last observation of each subject is selected.

Permitted Values: "first", "last"

subject_keys

Variables to uniquely identify a subject

A list of symbols created using exprs() is expected.

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 = "PD", PARAM = "Disease Progression") is expected. The values must be symbols, character strings, numeric values, or NA. Note, if you require a date or datetime variable to be populated, this needs to be defined here.

check_type

Check uniqueness?

If "warning" or "error" is specified, a message is issued if the observations of the input dataset restricted to the source parameter (source_param) are not unique with respect to the subject keys (subject_key parameter) and order variables (order parameter).

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

Value

The input dataset with a new parameter indicating if and when an event occurred

Details

  1. The source dataset (dataset_source) is restricted to observations fulfilling filter_source.

  2. For each subject (with respect to the variables specified for the subject_keys parameter) either the first or last observation from the restricted source dataset is selected. This is depending on mode, (with respect to order, if applicable) where the event condition (filter_source parameter) is fulfilled.

  3. For each observation in dataset_adsl a new observation is created. For subjects with event new_var is set to true_value. For all other subjects new_var is set to false_value. For subjects with event all variables from dataset_source are kept. For subjects without event all variables which are in both dataset_adsl and dataset_source are kept.

  4. The variables specified by the set_values_to parameter are added to the new observations.

  5. The new observations are added to input dataset.

See also

BDS-Findings Functions for adding Parameters/Records: default_qtc_paramcd(), derive_expected_records(), derive_extreme_event(), derive_extreme_records(), derive_locf_records(), derive_param_bmi(), derive_param_bsa(), derive_param_computed(), derive_param_doseint(), derive_param_exist_flag(), derive_param_exposure(), derive_param_framingham(), derive_param_map(), derive_param_qtc(), derive_param_rr(), derive_param_wbc_abs(), derive_summary_records()

Examples

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

# Derive a new parameter for the first disease progression (PD)
adsl <- tribble(
  ~USUBJID, ~DTHDT,
  "1",      ymd("2022-05-13"),
  "2",      ymd(""),
  "3",      ymd("")
) %>%
  mutate(STUDYID = "XX1234")

adrs <- tribble(
  ~USUBJID, ~ADTC,        ~AVALC,
  "1",      "2020-01-02", "PR",
  "1",      "2020-02-01", "CR",
  "1",      "2020-03-01", "CR",
  "1",      "2020-04-01", "SD",
  "2",      "2021-06-15", "SD",
  "2",      "2021-07-16", "PD",
  "2",      "2021-09-14", "PD"
) %>%
  mutate(
    STUDYID = "XX1234",
    ADT = ymd(ADTC),
    PARAMCD = "OVR",
    PARAM = "Overall Response",
    ANL01FL = "Y"
  ) %>%
  select(-ADTC)

derive_param_extreme_event(
  adrs,
  dataset_adsl = adsl,
  dataset_source = adrs,
  filter_source = PARAMCD == "OVR" & AVALC == "PD",
  order = exprs(ADT),
  new_var = AVALC,
  true_value = "Y",
  false_value = "N",
  mode = "first",
  set_values_to = exprs(
    PARAMCD = "PD",
    PARAM = "Disease Progression",
    ANL01FL = "Y",
    ADT = ADT
  )
)
#> # A tibble: 10 x 7
#>    USUBJID AVALC STUDYID ADT        PARAMCD PARAM               ANL01FL
#>    <chr>   <chr> <chr>   <date>     <chr>   <chr>               <chr>  
#>  1 1       PR    XX1234  2020-01-02 OVR     Overall Response    Y      
#>  2 1       CR    XX1234  2020-02-01 OVR     Overall Response    Y      
#>  3 1       CR    XX1234  2020-03-01 OVR     Overall Response    Y      
#>  4 1       SD    XX1234  2020-04-01 OVR     Overall Response    Y      
#>  5 2       SD    XX1234  2021-06-15 OVR     Overall Response    Y      
#>  6 2       PD    XX1234  2021-07-16 OVR     Overall Response    Y      
#>  7 2       PD    XX1234  2021-09-14 OVR     Overall Response    Y      
#>  8 2       Y     XX1234  2021-07-16 PD      Disease Progression Y      
#>  9 1       N     XX1234  NA         PD      Disease Progression Y      
#> 10 3       N     XX1234  NA         PD      Disease Progression Y      

# derive parameter indicating death
derive_param_extreme_event(
  dataset_adsl = adsl,
  dataset_source = adsl,
  filter_source = !is.na(DTHDT),
  new_var = AVALC,
  true_value = "Y",
  false_value = "N",
  mode = "first",
  set_values_to = exprs(
    PARAMCD = "DEATH",
    PARAM = "Death",
    ANL01FL = "Y",
    ADT = DTHDT
  )
)
#> # A tibble: 3 x 8
#>   USUBJID DTHDT      STUDYID AVALC PARAMCD PARAM ANL01FL ADT       
#>   <chr>   <date>     <chr>   <chr> <chr>   <chr> <chr>   <date>    
#> 1 1       2022-05-13 XX1234  Y     DEATH   Death Y       2022-05-13
#> 2 2       NA         XX1234  N     DEATH   Death Y       NA        
#> 3 3       NA         XX1234  N     DEATH   Death Y       NA