Derive a Disposition Status at a Specific Timepoint

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

Usage

derive_var_disposition_status(
  dataset,
  dataset_ds,
  new_var,
  status_var,
  format_new_var = format_eoxxstt_default,
  filter_ds,
  subject_keys = get_admiral_option("subject_keys")
)

Arguments

dataset

Input dataset.

dataset_ds

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

It must contain:

• STUDYID, USUBJID,

• The variable(s) specified in the status_var

• The variables used in filter_ds.

new_var

Name of the disposition status variable.

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

status_var

The variable used to derive the disposition status.

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

format_new_var

The format used to derive the status.

Default: format_eoxxstt_default() defined as:

format_eoxxstt_default <- function(status) {
  case_when(
    status %in% c("SCREEN FAILURE", "SCREENING NOT COMPLETED") ~ "NOT STARTED",
    status == "COMPLETED" ~ "COMPLETED",
    !status %in% c("COMPLETED", "SCREEN FAILURE", "SCREENING NOT COMPLETED")
    & !is.na(status) ~ "DISCONTINUED",
    TRUE ~ "ONGOING"
  )
}

where status is the status_var.

filter_ds

Filter condition for the disposition data.

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 status (new_var) added. new_var is derived based on the values given in status_var and according to the format defined by format_new_var (e.g. when the default format is used, the function will derive new_var as: "NOT STARTED" if status is "SCREEN FAILURE" or "SCREENING NOT COMPLETED", "COMPLETED" if status_var == "COMPLETED", "DISCONTINUED" if status is not in ("COMPLETED","SCREEN FAILURE", "SCREENING NOT COMPLETED") nor NA, "ONGOING" otherwise).

See also

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

Author

Samia Kabi

Examples

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

# Default derivation: EOSSTT =
#- NOT STARTED when status_var is SCREEN FAILURE or SCREENING NOT COMPLETED
#- COMPLETED when status_var is COMPLETED
#- DISCONTINUED when status_var is not COMPLETED nor SCREEN FAILURE nor
#  SCREENING NOT COMPLETED nor NA
#- ONGOING otherwise

admiral_dm %>%
  derive_var_disposition_status(
    dataset_ds = admiral_ds,
    new_var = EOSSTT,
    status_var = DSDECOD,
    filter_ds = DSCAT == "DISPOSITION EVENT"
  ) %>%
  select(STUDYID, USUBJID, EOSSTT)
#> # A tibble: 306 x 3
#>    STUDYID      USUBJID     EOSSTT      
#>    <chr>        <chr>       <chr>       
#>  1 CDISCPILOT01 01-701-1015 COMPLETED   
#>  2 CDISCPILOT01 01-701-1023 DISCONTINUED
#>  3 CDISCPILOT01 01-701-1028 COMPLETED   
#>  4 CDISCPILOT01 01-701-1033 DISCONTINUED
#>  5 CDISCPILOT01 01-701-1034 COMPLETED   
#>  6 CDISCPILOT01 01-701-1047 DISCONTINUED
#>  7 CDISCPILOT01 01-701-1057 NOT STARTED 
#>  8 CDISCPILOT01 01-701-1097 COMPLETED   
#>  9 CDISCPILOT01 01-701-1111 DISCONTINUED
#> 10 CDISCPILOT01 01-701-1115 DISCONTINUED
#> # … with 296 more rows

# Specific derivation: EOSSTT =
#- NOT STARTED when status_var = SCREEN FAILURE
#- COMPLETED when status_var = COMPLETED
#- DISCONTINUED DUE TO AE when status_var = ADVERSE EVENT
#- DISCONTINUED NOT DUE TO AE when status_var != ADVERSE EVENT nor COMPLETED
#  nor SCREEN FAILURE nor missing
#- ONGOING otherwise

format_eoxxstt1 <- function(x) {
  case_when(
    x == "SCREEN FAILURE" ~ "NOT STARTED",
    x == "COMPLETED" ~ "COMPLETED",
    x == "ADVERSE EVENT" ~ "DISCONTINUED DUE TO AE",
    !(x %in% c("ADVERSE EVENT", "COMPLETED", "SCREEN FAILURE")) & !is.na(x) ~
      "DISCONTINUED NOT DUE TO AE",
    TRUE ~ "ONGOING"
  )
}

admiral_dm %>%
  derive_var_disposition_status(
    dataset_ds = admiral_ds,
    new_var = EOSSTT,
    status_var = DSDECOD,
    format_new_var = format_eoxxstt1,
    filter_ds = DSCAT == "DISPOSITION EVENT"
  ) %>%
  select(STUDYID, USUBJID, EOSSTT)
#> # A tibble: 306 x 3
#>    STUDYID      USUBJID     EOSSTT                    
#>    <chr>        <chr>       <chr>                     
#>  1 CDISCPILOT01 01-701-1015 COMPLETED                 
#>  2 CDISCPILOT01 01-701-1023 DISCONTINUED DUE TO AE    
#>  3 CDISCPILOT01 01-701-1028 COMPLETED                 
#>  4 CDISCPILOT01 01-701-1033 DISCONTINUED NOT DUE TO AE
#>  5 CDISCPILOT01 01-701-1034 COMPLETED                 
#>  6 CDISCPILOT01 01-701-1047 DISCONTINUED DUE TO AE    
#>  7 CDISCPILOT01 01-701-1057 NOT STARTED               
#>  8 CDISCPILOT01 01-701-1097 COMPLETED                 
#>  9 CDISCPILOT01 01-701-1111 DISCONTINUED DUE TO AE    
#> 10 CDISCPILOT01 01-701-1115 DISCONTINUED DUE TO AE    
#> # … with 296 more rows