Skip to contents

Derive a Disposition Reason at a Specific Timepoint

Source: R/derive_vars_disposition_reason.R
derive_vars_disposition_reason.Rd

Derive a disposition reason from the the relevant records in the disposition domain.

Usage

derive_vars_disposition_reason(
  dataset,
  dataset_ds,
  new_var,
  reason_var,
  new_var_spe = NULL,
  reason_var_spe = NULL,
  format_new_vars = format_reason_default,
  filter_ds,
  subject_keys = get_admiral_option("subject_keys")
)

Arguments

dataset

Input dataset

dataset_ds

Dataset containing the disposition information (e.g. ds)

The dataset must contain:

  • STUDYID, USUBJID,

  • The variable(s) specified in the reason_var (and reason_var_spe, if required)

  • The variables used in filter_ds.

new_var

Name of the disposition reason variable

A variable name is expected (e.g. DCSREAS).

reason_var

The variable used to derive the disposition reason

A variable name is expected (e.g. DSDECOD).

new_var_spe

Name of the disposition reason detail variable

A variable name is expected (e.g. DCSREASP). If new_var_spe is specified, it is expected that reason_var_spe is also specified, otherwise an error is issued.

Default: NULL

reason_var_spe

The variable used to derive the disposition reason detail

A variable name is expected (e.g. DSTERM). If new_var_spe is specified, it is expected that reason_var_spe is also specified, otherwise an error is issued.

Default: NULL

format_new_vars

The function used to derive the reason(s)

This function is used to derive the disposition reason(s) and must follow the below conventions

  • If only the main reason for discontinuation needs to be derived (i.e. new_var_spe is NULL), the function must have at least one character vector argument, e.g. format_reason <- function(reason) and new_var will be derived as new_var = format_reason(reason_var). Typically, the content of the function would return reason_var or NA depending on the value (e.g. if_else ( reason != "COMPLETED" & !is.na(reason), reason, NA_character_)). DCSREAS = format_reason(DSDECOD) returns DCSREAS = DSDECOD when DSDECOD is not 'COMPLETED' nor NA, NA otherwise.

  • If both the main reason and the details needs to be derived (new_var_spe is specified) the function must have two character vectors argument, e.g. format_reason2 <- function(reason, reason_spe) and new_var will be derived as new_var = format_reason(reason_var), new_var_spe will be derived as new_var_spe = format_reason(reason_var, reason_var_spe). Typically, the content of the function would return reason_var_spe or NA depending on the reason_var value (e.g. if_else ( reason == "OTHER", reason_spe, NA_character_)). DCSREASP = format_reason(DSDECOD, DSTERM) returns DCSREASP = DSTERM when DSDECOD is equal to 'OTHER'.

Default: format_reason_default, see format_reason_default() for details.

filter_ds

Filter condition for the disposition data.

Filter used to select the relevant disposition data. It is expected that the filter restricts dataset_ds such that there is at most one observation per patient. An error is issued otherwise.

Permitted Values: logical expression.

subject_keys

Variables to uniquely identify a subject

A list of quosures where the expressions are symbols as returned by vars() is expected.

Value

the input dataset with the disposition reason(s) (new_var and if required new_var_spe) added.

Details

This functions returns the main reason for discontinuation (e.g. DCSREAS or DCTREAS). The reason for discontinuation is derived based on reason_var (e.g. DSDECOD) and format_new_vars. If new_var_spe is not NULL, then the function will also return the details associated with the reason for discontinuation (e.g. DCSREASP). The details associated with the reason for discontinuation are derived based on reason_var_spe (e.g. DSTERM), reason_var and format_new_vars.

See also

format_reason_default()

ADSL Functions that returns variable appended to dataset: derive_var_age_years(), derive_var_disposition_status(), derive_var_dthcaus(), derive_var_extreme_dtm(), derive_var_extreme_dt(), derive_vars_aage(), derive_vars_period()

Author

Samia Kabi

Examples

library(dplyr, warn.conflicts = FALSE)
library(admiral.test)
data("admiral_dm")
data("admiral_ds")

# Derive DCSREAS using the default format
admiral_dm %>%
  derive_vars_disposition_reason(
    dataset_ds = admiral_ds,
    new_var = DCSREAS,
    reason_var = DSDECOD,
    filter_ds = DSCAT == "DISPOSITION EVENT"
  ) %>%
  select(STUDYID, USUBJID, DCSREAS)
#> # A tibble: 306 x 3
#>    STUDYID      USUBJID     DCSREAS                    
#>    <chr>        <chr>       <chr>                      
#>  1 CDISCPILOT01 01-701-1015 NA                         
#>  2 CDISCPILOT01 01-701-1023 ADVERSE EVENT              
#>  3 CDISCPILOT01 01-701-1028 NA                         
#>  4 CDISCPILOT01 01-701-1033 STUDY TERMINATED BY SPONSOR
#>  5 CDISCPILOT01 01-701-1034 NA                         
#>  6 CDISCPILOT01 01-701-1047 ADVERSE EVENT              
#>  7 CDISCPILOT01 01-701-1057 SCREEN FAILURE             
#>  8 CDISCPILOT01 01-701-1097 NA                         
#>  9 CDISCPILOT01 01-701-1111 ADVERSE EVENT              
#> 10 CDISCPILOT01 01-701-1115 ADVERSE EVENT              
#> # … with 296 more rows

# Derive DCSREAS and DCSREASP using a study-specific format
format_dcsreas <- function(x, y = NULL) {
  if (is.null(y)) {
    if_else(!x %in% c("COMPLETED", "SCREEN FAILURE") & !is.na(x), x, NA_character_)
  } else {
    if_else(x == "OTHER", y, NA_character_)
  }
}
admiral_dm %>%
  derive_vars_disposition_reason(
    dataset_ds = admiral_ds,
    new_var = DCSREAS,
    reason_var = DSDECOD,
    new_var_spe = DCSREASP,
    reason_var_spe = DSTERM,
    format_new_vars = format_dcsreas,
    filter_ds = DSCAT == "DISPOSITION EVENT"
  ) %>%
  select(STUDYID, USUBJID, DCSREAS, DCSREASP)
#> # A tibble: 306 x 4
#>    STUDYID      USUBJID     DCSREAS                     DCSREASP
#>    <chr>        <chr>       <chr>                       <chr>   
#>  1 CDISCPILOT01 01-701-1015 NA                          NA      
#>  2 CDISCPILOT01 01-701-1023 ADVERSE EVENT               NA      
#>  3 CDISCPILOT01 01-701-1028 NA                          NA      
#>  4 CDISCPILOT01 01-701-1033 STUDY TERMINATED BY SPONSOR NA      
#>  5 CDISCPILOT01 01-701-1034 NA                          NA      
#>  6 CDISCPILOT01 01-701-1047 ADVERSE EVENT               NA      
#>  7 CDISCPILOT01 01-701-1057 NA                          NA      
#>  8 CDISCPILOT01 01-701-1097 NA                          NA      
#>  9 CDISCPILOT01 01-701-1111 ADVERSE EVENT               NA      
#> 10 CDISCPILOT01 01-701-1115 ADVERSE EVENT               NA      
#> # … with 296 more rows