Introduction to admiralonco

The admiralonco package extends admiral to handle oncology-specific data transformations in clinical trials. It provides functions that help prepare ADaM datasets while ensuring compliance with CDISC standards.

This tutorial will cover all functions in admiralonco, explaining their purpose, usage, and providing practical examples.

Getting Started

Basic Concepts and Terminology

Oncology clinical trials rely on standardized datasets to evaluate patient responses. The ADaM datasets ensure consistency and regulatory compliance.

• RECIST (Response Evaluation Criteria in Solid Tumors): Defines response categories such as Complete Response (CR), Partial Response (PR), Stable Disease (SD), and Progressive Disease (PD).
• ADaM (Analysis Data Model): A standardized format ensuring traceability from raw clinical trial data.
• CDISC (Clinical Data Interchange Standards Consortium): The governing body defining standards like SDTM (Study Data Tabulation Model) and ADaM.

Loading the Package and Exploring Available Functions

First, ensure that you have admiral installed before using admiralonco:

# Install admiral first
install.packages("admiral") 
# Install admiralonco
remotes::install_github("pharmaverse/admiralonco") 

Once installed, load the package:

library(admiral)
library(admiralonco)

To explore available functions:

ls("package:admiralonco")

Understanding the Relationship Between admiral and admiralonco

admiralonco builds on admiral, inheriting its structure and conventions while introducing functions specific to oncology trials. While admiral provides general ADaM transformations, admiralonco focuses on tumor assessments, response datasets, and disease progression.

admiral_adrs Dataset

The admiral_adrs dataset is a sample ADaM dataset created using admiralonco. It is structured to capture tumor response assessments from oncology trials.

Dataset Overview

• 3694 rows: Each row represents a specific tumor response assessment for a patient.
• 76 columns: Capturing subject details, response categories, visit information, and derived variables.

Column Descriptions

Below is a detailed breakdown of all 76 columns in the dataset:

Column Descriptions

• DOMAIN: Dataset domain identifier.
• STUDYID: Unique study identifier.
• USUBJID: Unique subject identifier.
• VISITNUM: Numeric visit number.
• VISIT: Name of the visit.
• RSTESTCD: Short test code for response assessment.
• RSTEST: Full description of the test performed.
• RSORRES: Original result of the tumor response test.
• RSSTRESC: Standardized tumor response result.
• RSEVAL: Evaluator of the response (e.g., investigator, independent review).
• RSEVALID: Identifier for the evaluator.
• RSACPTFL: Flag indicating if the response was accepted.
• RSDTC: Date of tumor response assessment.
• RSSEQ: Sequence number for ordering records.
• RANDDT: Date of randomization.
• PARAMCD: Short parameter code.
• PARAM: Full description of the parameter.
• PARCAT1: First-level category for the parameter.
• PARCAT2: Second-level category for the parameter.
• PARCAT3: Third-level category for the parameter.
• ADT: Analysis date.
• ADTF: Analysis date flag.
• AVISIT: Analysis visit name.
• AVALC: Categorical version of analysis value.
• AVAL: Analysis value.
• ANL01FL: Flag indicating if the record is in the primary analysis.
• ANL02FL: Flag for additional sensitivity analysis.
• ASEQ: Analysis sequence number.
• SUBJID: Subject ID within the study.
• RFSTDTC: Reference start date/time.
• RFENDTC: Reference end date/time.
• RFXSTDTC: Treatment start date.
• RFXENDTC: Treatment end date.
• RFICDTC: Date/time of informed consent.
• RFPENDTC: Date/time of end of participation.
• DTHDTC: Date of death.
• DTHFL: Death flag.
• SITEID: Study site identifier.
• AGE: Age of the subject.
• AGEU: Age unit.
• SEX: Subject's sex.
• RACE: Subject's race.
• ETHNIC: Subject's ethnicity.
• ARMCD: Code for assigned treatment arm.
• ARM: Name of assigned treatment arm.
• ACTARMCD: Code for actual treatment arm.
• ACTARM: Name of actual treatment arm.
• COUNTRY: Country of enrollment.
• DMDTC: Date of demographic collection.
• DMDY: Day of demographic collection.
• TRT01P: Planned treatment for the first period.
• TRT01A: Actual treatment for the first period.
• TRTSDTM: Treatment start date/time.
• TRTSTMF: Treatment start time flag.
• TRTEDTM: Treatment end date/time.
• TRTETMF: Treatment end time flag.
• TRTSDT: Treatment start date.
• TRTEDT: Treatment end date.
• TRTDURD: Treatment duration in days.
• SCRFDT: Screening visit date.
• EOSDT: End-of-study date.
• EOSSTT: End-of-study status.
• FRVDT: First relapse visit date.
• DTHDT: Date of death.
• DTHADY: Death analysis day.
• LDDTHELD: Last documented date the subject was alive.
• LSTALVDT: Last known alive date.
• AGEGR1: Age group classification.
• SAFFL: Safety population flag.
• RACEGR1: Race group classification.
• REGION1: Geographic region classification.
• LDDTHGR1: Last documented death group.
• DTH30FL: Death within 30-day flag.
• DTHA30FL: Alternate 30-day death flag.
• DTHB30FL: Additional 30-day death flag.

Using the aval_resp Function

The aval_resp function in admiralonco is used to convert categorical tumor response values into standardized numeric values. This helps ensure consistency in oncology data analysis, particularly when assessing patient responses according to RECIST criteria.

Function Behavior

The function takes a character vector as input and returns numeric values based on the following mapping:

• 1 if the input is "CR" (Complete Response)
• 2 if the input is "PR" (Partial Response)
• 3 if the input is "SD" (Stable Disease)
• 4 if the input is "NON-CR/NON-PD" (Neither Complete Response nor Progressive Disease)
• 5 if the input is "PD" (Progressive Disease)
• 6 if the input is "NE" (Not Evaluable)
• 7 if the input is "MISSING"
• NA otherwise

Example Usage

Below is an example demonstrating how to use aval_resp in R. This example assumes that the admiralonco package is installed and that an ADaM dataset containing tumor response data is available.

library(admiral)
library(admiralonco)
library(dplyr)

# Sample dataset
adrs <- tibble(
    USUBJID = c("001", "002", "003", "004", "005", "006", "007"),
    AVISIT = c("Week 8", "Week 8", "Week 8", "Week 8", "Week 8", "Week 8", "Week 8"),
    AVALC = c("CR", "PR", "SD", "NON-CR/NON-PD", "PD", "NE", "MISSING")  # Tumor response categories
)

# Deriving numeric response values

adrs <- adrs %>%

mutate(AVAL = aval_resp(AVALC))
# Display the dataset

print(adrs)

In this example:

• The dataset adrs contains tumor response categories in the AVALC column.
• The aval_resp function converts these categorical values into numeric equivalents based on predefined rules.
• For example, "CR" is mapped to 1, "PR" to 2, "SD" to 3, and so on.

This function ensures standardized tumor response scoring, making it easier to conduct statistical analyses and generate regulatory reports.

Pre-Defined Time-to-Event (TTE) Source Objects

admiralonco provides several pre-defined tte_source objects that can be used as input to the function admiral::derive_param_tte(). These objects help in deriving time-to-event (TTE) endpoints in clinical trials by standardizing event and censoring definitions.

Available Pre-Defined Objects

• death_event: Defines death as an event.
• lastalive_censor: Censors subjects based on their last known alive date.
• pd_event: Defines progressive disease (PD) as an event.
• lasta_censor: Censors subjects based on the last tumor assessment.
• rand_censor: Censors subjects at randomization.
• trts_censor: Censors subjects at the start of treatment.

To see the definition of a specific object, print it in the R console:

print(death_event)

This will display details such as the input dataset, applied filters (if any), relevant date variable, and metadata fields like EVNTDESC, CNSDTDSC, SRCDOM, SRCVAR, and SRCSEQ.

Example Usage

Below is an example demonstrating how to list and print all available tte_source objects in admiralonco:

library(admiral)
library(admiralonco)

# List all available TTE source objects in admiralonco
tte_objects <- admiral::list_tte_source_objects(package = "admiralonco")$object

# Print each object definition
for (obj in tte_objects) {
    cat("Object Name:", obj, "\n")
    print(get(obj, envir = getNamespace("admiralonco")))
    cat("\n")
}

In this example:

• We retrieve all pre-defined tte_source objects available in admiralonco.
• Each object is printed along with its details.
• This helps users understand the structure and purpose of each object before applying them in derive_param_tte().

For more details on using these objects, refer to admiral::derive_param_tte().

Deriving Best Overall Response (BOR) with derive_param_bor

The derive_param_bor function in admiralonco is designed to calculate the Best Overall Response (BOR) in oncology clinical trials. It evaluates tumor response records over time and selects the best response based on predefined criteria.

Function Purpose

This function determines BOR without requiring confirmation. It can restrict calculations to records occurring before the first Progressive Disease (PD) if desired. The result is then added as a new parameter in the dataset.

Function Syntax

derive_param_bor( 
    dataset, 
    dataset_adsl, 
    filter_source, 
    source_pd = NULL, 
    source_datasets = NULL, 
    reference_date, 
    ref_start_window, 
    missing_as_ne = FALSE, 
    aval_fun, 
    set_values_to, 
    subject_keys = get_admiral_option("subject_keys") 
  )

Function Arguments

• dataset: The primary dataset from which BOR will be derived. It should include PARAMCD, ADT, AVALC, and relevant subject identifiers.
• dataset_adsl: The ADSL dataset containing baseline subject information. New BOR rows will be added for each subject.
• filter_source: Defines which records should be used in deriving BOR.
• source_pd: (Optional) A date source object specifying the first PD date. If included, BOR is only derived from records before this date.
• source_datasets: A list linking the dataset used in source_pd to the actual data source.
• reference_date: The key date used for BOR evaluation (e.g., treatment start date or randomization date).
• ref_start_window: Defines a window period for stable disease (SD) responses. SD records before this window are excluded.
• missing_as_ne: If TRUE, subjects without response assessments are assigned "NE" instead of "MISSING."
• aval_fun: A function mapping AVALC values to numeric AVAL values.
• set_values_to: Specifies new column values for the derived BOR parameter (e.g., PARAMCD = "BOR").
• subject_keys: Defines the columns that uniquely identify each subject.

How BOR is Determined

• All CR, PR, and PD records contribute to Best Overall Response.
• SD or NON-CR/NON-PD records are only included if they occur after the defined reference window.
• Subjects with only SD or NON-CR/NON-PD responses before the window are assigned "NE."
• The best response is chosen in this priority order: CR > PR > SD > NON-CR/NON-PD > PD > NE > MISSING.
• The function generates the AVAL column using the aval_fun function.

Example Usage

The following example demonstrates how to derive BOR using different patient response values.

library(magrittr)
library(dplyr)
library(tibble)
library(lubridate)
library(admiral)
library(admiralonco)
  
  # Construct ADSL dataset
adsl <- tribble(
    ~USUBJID, ~TRTSDTC,
    "A101", "2022-05-15",
    "A102", "2022-06-20",
    "A103", "2022-07-10",
    "A104", "2022-08-05"
  ) %>%
    mutate(TRTSDT = ymd(TRTSDTC), STUDYID = "ZZ9101")
    
# Create ADRS dataset with different responses
response_obs <- tribble(
    ~USUBJID, ~ADTC, ~AVALC, ~ANL01FL,
  "A101", "2022-05-18", "PR", "Y",
  "A101", "2022-06-25", "CR", "Y",
  "A102", "2022-06-22", "SD", "Y",
  "A103", "2022-07-12", "PD", "Y",
  "A104", "2022-08-07", "NON-CR/NON-PD", "Y"
  ) %>%
  mutate(PARAMCD = "OVR")
  
# Define PD occurrence
pd_obs <- tribble(
    ~USUBJID, ~ADTC, ~AVALC,
    "A102", "2022-07-05", "Y",
    "A103", "2022-07-15", "Y"
  ) %>%
    mutate(PARAMCD = "PD")
    
# Merge datasets
adrs <- bind_rows(response_obs, pd_obs) %>%
    mutate(ADT = ymd(ADTC), STUDYID = "ZZ9101") %>%
    select(-ADTC) %>%
    derive_vars_merged(dataset_add = adsl, by_vars = exprs(STUDYID, USUBJID), new_vars = exprs(TRTSDT))
      

# Define PD date source
pd_date <- date_source(
                         dataset_name = "adrs",
                         date = ADT,
                         filter = PARAMCD == "PD"
)
  
# Custom function for numeric mapping
aval_fun_custom <- function(arg) {
    case_when(
    arg == "CR" ~ 10,
    arg == "PR" ~ 20,
    arg == "SD" ~ 30,
    arg == "NON-CR/NON-PD" ~ 40,
    arg == "PD" ~ 50,
    arg == "NE" ~ 60,
    arg == "MISSING" ~ 70,
    TRUE ~ NA_real_
    )
  }

# Compute Best Overall Response
derive_param_bor(
    adrs,
    dataset_adsl = adsl,
    filter_source = PARAMCD == "OVR" & ANL01FL == "Y",
    source_pd = pd_date,
    source_datasets = list(adrs = adrs),
    aval_fun = aval_fun_custom,
    reference_date = TRTSDT,
    ref_start_window = 25,
    set_values_to = exprs(PARAMCD = "BOR", PARAM = "Best Overall Response")
) %>%
  filter(PARAMCD == "BOR")

Deriving Clinical Benefit with derive_param_clinbenefit

The derive_param_clinbenefit function in admiralonco calculates a new parameter indicating clinical benefit or disease control in oncology trials. It identifies subjects who exhibit a response (such as CR, PR, SD, or NON-CR/NON-PD) within a specific time frame and before disease progression (PD).

Function Overview

This function evaluates patient responses at different time points and determines if they meet the criteria for clinical benefit. It allows customization of response categories and applies filtering based on disease progression.

Function Syntax

derive_param_clinbenefit( 
    dataset, 
    dataset_adsl, 
    filter_source, 
    source_resp, 
    source_pd = NULL, 
    source_datasets, 
    reference_date, 
    ref_start_window, 
    aval_fun, 
    clinben_vals = c("CR", "PR", "SD", "NON-CR/NON-PD"), 
    set_values_to, 
    subject_keys = get_admiral_option("subject_keys") 
  )

Function Arguments

• dataset: The primary dataset containing tumor response assessments. This dataset is where the clinical benefit parameter will be added.
• dataset_adsl: The ADSL dataset containing baseline information for each subject.
• filter_source: A filter condition used to extract relevant response records.
• source_resp: A date_source object that defines how response status is determined.
• source_pd: (Optional) A date_source object specifying how disease progression is identified.
• source_datasets: A list linking dataset names to actual data sources.
• reference_date: The date used to establish when response assessments should be evaluated.
• ref_start_window: Defines how many days must pass after the reference date before a response is considered valid for clinical benefit.
• aval_fun: A function mapping response values from categorical to numeric.
• clinben_vals: A vector of response values that qualify as clinical benefit (default: CR, PR, SD, NON-CR/NON-PD).
• set_values_to: Specifies values to assign for the new clinical benefit parameter.
• subject_keys: Defines the subject-level identifiers.

Clinical Benefit Determination Process

• Subjects are filtered based on the provided response condition (filter_source).
• Only non-PD assessments occurring after ref_start_window are considered.
• For eligible subjects, the earliest qualifying response is selected.
• The response date is set as the earlier of the first evaluable response or the response start date.
• Subjects who meet the clinical benefit criteria receive AVALC = "Y"; those who do not receive AVALC = "N".

Example Usage

The example below demonstrates how to apply derive_param_clinbenefit with different values.

library(lubridate)
library(dplyr)
library(admiral)
library(admiralonco)


# Construct ADSL dataset
adsl <- tibble::tribble(
  ~ USUBJID,  ~ TRTSDT,
  "B201",  ymd("2021-06-10"),
  "B202",  ymd("2021-07-15"),
  "B203",  ymd("2021-08-05"),
  "B204",  ymd("2021-09-20")
) %>%
  mutate(STUDYID = "ZZ345")

# Create ADRS dataset with different response values
adrs <- tibble::tribble(
  ~ USUBJID,~ PARAMCD,~ AVALC,~ ADT,
  "B201","RSP","Y", ymd("2021-07-10"),
  "B202","RSP","N", ymd("2021-08-01"),
  "B203","RSP","N", NA,
  "B204","RSP","N", NA,
  "B201","PD", "N", NA,
  "B202","PD", "Y", ymd("2021-08-10"),
  "B203","PD","N", NA,
  "B204","PD","N", NA,
   "B201","OVR","PR", ymd("2021-07-15"),
  "B202","OVR","SD",
  ymd("2021-08-05"),
  "B202","OVR","PD", ymd("2021-08-10"),
  "B203","OVR","CR", ymd("2021-09-01"),
  "B204","OVR","NE", ymd("2021-10-10")
) %>%
  mutate(STUDYID = "ZZ345", ANL01FL = "Y") %>%
  derive_vars_merged(
    dataset_add = adsl,
    by_vars = exprs(STUDYID, USUBJID),
    new_vars = exprs(TRTSDT)
  )

# Define date sources
pd_date <- date_source(
  dataset_name = "adrs",
  date = ADT,
  filter = PARAMCD == "PD" &
    AVALC == "Y" & ANL01FL == "Y"
)

resp_date <- date_source(
  dataset_name = "adrs",
  date = ADT,
  filter = PARAMCD == "RSP" &
    AVALC == "Y" & ANL01FL == "Y"
)

# Compute Clinical Benefit Rate
derive_param_clinbenefit(
  dataset = adrs,
  dataset_adsl = adsl,
  filter_source = PARAMCD == "OVR" &
    ANL01FL == "Y",
  source_resp = resp_date,
  source_pd = pd_date,
  source_datasets = list(adrs = adrs),
  reference_date = TRTSDT,
  ref_start_window = 30,
  set_values_to = exprs(PARAMCD = "CBR", PARAM = "Clinical Benefit Rate")
) %>%
  filter(PARAMCD == "CBR")

This function helps standardize clinical benefit assessment by automatically identifying patients who meet predefined response criteria before progression.

Deriving Confirmed Best Overall Response (CBOR) with derive_param_confirmed_bor

The derive_param_confirmed_bor function in admiralonco calculates the confirmed Best Overall Response (BOR) for oncology trials. It identifies patient responses that are supported by a confirmatory assessment, ensuring more robust and reliable outcome classification.

Function Overview

This function determines BOR with confirmation, meaning that a response (such as CR or PR) must be validated by a subsequent assessment. The confirmatory evaluation must occur within a specified time window and follow predefined response consistency rules.

Function Syntax

  derive_param_confirmed_bor( 
                                dataset, 
                                dataset_adsl, 
                                filter_source, 
                                source_pd = NULL, 
                                source_datasets = NULL, 
                                reference_date, 
                                ref_start_window, 
                                ref_confirm, 
                                max_nr_ne = 1, 
                                accept_sd = FALSE, 
                                missing_as_ne = FALSE, 
                                aval_fun, 
                                set_values_to, 
                                subject_keys = get_admiral_option("subject_keys") 
  )

Function Arguments

• dataset: The primary dataset containing tumor response assessments. It should include PARAMCD, ADT, and AVALC as well as subject identifiers.
• dataset_adsl: The ADSL dataset containing baseline subject-level information.
• filter_source: A condition used to select relevant response records.
• source_pd: (Optional) A date source object specifying the first occurrence of Progressive Disease (PD). If provided, CBOR is only derived from records before or at this date.
• source_datasets: A list linking dataset names to actual data sources.
• reference_date: The key date used for evaluating response timing, usually treatment start date (TRTSDT) or randomization date.
• ref_start_window: Defines how many days must pass after the reference date before an assessment is considered for BOR.
• ref_confirm: The minimum time period required between an initial and confirmatory response assessment.
• max_nr_ne: The maximum number of "Not Evaluable" (NE) assessments allowed between the initial and confirmatory response.
• accept_sd: If TRUE, one Stable Disease (SD) assessment is allowed between PR and its confirmation.
• missing_as_ne: If TRUE, missing assessments are considered "NE" instead of "MISSING."
• aval_fun: A function mapping response categories to numeric values.
• set_values_to: Specifies new values for the confirmed BOR parameter.
• subject_keys: Defines the subject identifiers.

Confirmed BOR Determination Process

• The dataset is filtered to include relevant response assessments (filter_source) and, if applicable, restricted to pre-PD assessments (source_pd).
• A response is considered confirmed if it meets specific criteria:
• Complete Response (CR): A follow-up CR must be observed at least ref_confirm days later with no inconsistent responses in between.
• Partial Response (PR): A follow-up CR or PR must be recorded within ref_confirm days, with at most one allowed SD (if accept_sd = TRUE).
• Stable Disease (SD): Must occur at least ref_start_window days after the reference date.
• NON-CR/NON-PD: Must also occur at least ref_start_window days after the reference date.
• Progressive Disease (PD): Assigned if an assessment indicates PD.
• Not Evaluable (NE): Assigned if responses are NE or if no valid assessment occurs after ref_start_window.
• Missing (MISSING): Assigned if no response data exists, unless missing_as_ne = TRUE, in which case it is set to NE.

Example Usage

The following example demonstrates how to derive confirmed BOR with a new set of values.

library(dplyr)
library(lubridate)
library(admiral)
library(admiralonco)
  
# Construct ADSL dataset
adsl <- tibble::tribble(
    ~USUBJID, ~TRTSDTC,
    "C301", "2022-06-01",
    "C302", "2022-07-15",
    "C303", "2022-08-10",
    "C304", "2022-09-05"
) %>%
  mutate(TRTSDT = ymd(TRTSDTC), STUDYID = "YY789")
  
  # Create ADRS dataset with different response values
  adrs <- tibble::tribble(
    ~USUBJID, ~PARAMCD,~AVALC, ~ADT,
    "C301", "OVR", "PR", ymd("2022-07-01"),
    "C301", "OVR", "CR", ymd("2022-08-05"),
    "C302", "OVR", "SD", ymd("2022-08-20"),
    "C303", "OVR", "PD", ymd("2022-09-15"),
    "C304", "OVR", "NON-CR/NON-PD", ymd("2022-10-10")
  ) %>%
    mutate(STUDYID = "YY789", ANL01FL = "Y")
    
# Define PD date source

pd_date <- date_source(
    dataset_name = "adrs",
    date = ADT,
    filter = PARAMCD == "PD" & ANL01FL == "Y"
)
  
# Compute Confirmed Best Overall Response
derive_param_confirmed_bor(
    dataset = adrs,
    dataset_adsl = adsl,
    filter_source = PARAMCD == "OVR" & ANL01FL == "Y",
                               source_pd = pd_date,
                               source_datasets = list(adrs = adrs),
                               reference_date = TRTSDT,
                               ref_start_window = 30,
                               ref_confirm = 28,
                               max_nr_ne = 1,
                               accept_sd = TRUE,
                               missing_as_ne = FALSE,
                               set_values_to = exprs(PARAMCD = "CBOR", PARAM = "Confirmed Best Overall Response")
  ) %>%
filter(PARAMCD == "CBOR")
  

This function ensures that response assessments meet rigorous confirmation criteria, strengthening the reliability of Best Overall Response classifications in oncology trials.

Deriving Confirmed Response with derive_param_confirmed_resp

The derive_param_confirmed_resp function in admiralonco is designed to add a confirmed response parameter to your dataset. This function ensures that specific tumor response assessments, such as Complete Response (CR) or Partial Response (PR), are confirmed by subsequent assessments, thereby increasing the robustness and reliability of the response data.

Function Overview

In oncology trials, responses are often subject to confirmation through follow-up assessments. The derive_param_confirmed_resp function identifies whether a response, such as CR or PR, is confirmed based on a series of rules. For CR and PR, a confirmatory assessment must occur within a specified time period, and other conditions regarding stable disease (SD) and not evaluable (NE) responses are applied. This function adds the confirmed response information to the dataset, facilitating more accurate analysis of treatment efficacy.

Function Syntax

  derive_param_confirmed_resp( 
    dataset, 
    dataset_adsl, 
    filter_source, 
    source_pd = NULL, 
    source_datasets = NULL, 
    ref_confirm, 
    max_nr_ne = 1, 
    accept_sd = FALSE, 
    aval_fun, 
    set_values_to, 
    subject_keys = get_admiral_option("subject_keys") 
  )

Function Arguments

• dataset: The dataset containing tumor response assessments. It should include at least the following variables: PARAMCD, ADT, and AVALC, along with identifiers specified in subject_keys and the reference date.
• dataset_adsl: The ADSL dataset, which contains baseline subject-level information, including variables that uniquely identify each subject.
• filter_source: A condition used to filter the dataset and select relevant response records that will be considered for deriving the confirmed response.
• source_pd: (Optional) A date source object specifying the first occurrence of Progressive Disease (PD). If specified, the dataset will be restricted to observations before or at this date.
• source_datasets: A named list of datasets that links the dataset name from source_pd to the actual dataset.
• ref_confirm: The minimum time period (in days) between the initial response assessment and the confirmatory assessment.
• max_nr_ne: The maximum number of "Not Evaluable" (NE) assessments allowed between the initial response and the confirmatory assessment.
• accept_sd: If TRUE, one Stable Disease (SD) assessment is allowed between PR and its confirmatory assessment. Otherwise, no SD assessments are allowed.
• aval_fun: A function to convert the response category (AVALC) into numeric values. This argument is now deprecated, and set_values_to should be used instead.
• set_values_to: A list of values that will be set for the new parameter, such as PARAMCD and PARAM, using exprs().
• subject_keys: Defines the subject identifiers. This should be a list of variables created using exprs() to uniquely identify each subject.

Confirmed Response Determination Process

• The function first filters the dataset based on the filter_source condition and, if applicable, restricts the data to pre-PD assessments (using the source_pd argument).
• A subject is considered a confirmed responder if there is at least one observation in the filtered dataset meeting the following criteria:
• Complete Response (CR): A follow-up CR must be recorded at least ref_confirm days after the initial CR, with no inconsistent assessments in between (e.g., SD or PD).
• Partial Response (PR): A follow-up CR or PR must be recorded within ref_confirm days, with at most one allowed SD (if accept_sd = TRUE) and at most max_nr_ne NE assessments in the confirmation period.
• Not Evaluable (NE): If no valid follow-up assessments are available, or if there are too many NE assessments between the original and confirmatory responses, the response is classified as NE.
• The new confirmed response variable is then added to the dataset, and all the required parameters are updated for the confirmed responders, including the AVAL variable which is computed using aval_fun.

Example Usage

The following example demonstrates how to use derive_param_confirmed_resp with a new set of values, based on sample data. We will define an ADSL dataset and an ADRS dataset with various tumor response categories.

library(dplyr)
library(lubridate)
library(admiral)
library(admiralonco)

# Construct ADSL dataset
adsl <- tibble::tribble(
~USUBJID, ~TRTSDTC,
"C301", "2022-06-01",
"C302", "2022-07-15",
"C303", "2022-08-10",
"C304", "2022-09-05"
) %>%
mutate(TRTSDT = ymd(TRTSDTC), STUDYID = "YY789")

# Create ADRS dataset with different response values
adrs <- tibble::tribble(

~USUBJID, ~PARAMCD, ~AVALC, ~ADT,
"C301", "OVR", "PR", ymd("2022-07-01"),
"C301", "OVR", "CR", ymd("2022-08-05"),
"C302", "OVR", "SD", ymd("2022-08-20"),
"C303", "OVR", "PD", ymd("2022-09-15"),
"C304", "OVR", "NON-CR/NON-PD", ymd("2022-10-10")
) %>%
mutate(STUDYID = "YY789", ANL01FL = "Y")

# Define PD date source
pd_date <- date_source(
dataset_name = "adrs",
date = ADT,
filter = PARAMCD == "PD" & ANL01FL == "Y"
)

# Compute Confirmed Response
derive_param_confirmed_resp(
dataset = adrs,
dataset_adsl = adsl,
filter_source = PARAMCD == "OVR" & ANL01FL == "Y",
source_pd = pd_date,
source_datasets = list(adrs = adrs),
ref_confirm = 28,
max_nr_ne = 1,
accept_sd = TRUE,
set_values_to = exprs(PARAMCD = "CRSP", PARAM = "Confirmed Response by Investigator")
) %>%
filter(PARAMCD == "CRSP")

This function evaluates each response in the dataset and classifies the response as confirmed or not based on the rules. The result is a more accurate response parameter for further analysis in oncology trials.

Deriving Confirmed Response with derive_param_confirmed_resp

The derive_param_confirmed_resp function in admiralonco is used to derive the confirmed tumor response parameter for oncology datasets. The function helps to determine whether a subject's response, such as Complete Response (CR) or Partial Response (PR), is confirmed based on follow-up assessments. A confirmed response requires that certain conditions are met, such as the assessment being validated by subsequent data points, and within a specified time window.

Function Overview

In oncology clinical trials, it is important to validate a tumor response (e.g., CR or PR) by follow-up assessments to ensure the response is accurate. This function does so by checking if the initial response is confirmed by subsequent assessments within a defined time frame. For CR and PR, a confirmatory assessment must occur within a certain number of days after the initial response. Additionally, certain rules regarding Stable Disease (SD) and Not Evaluable (NE) assessments are applied. The function ultimately adds a confirmed response variable to the dataset, helping to better evaluate treatment efficacy in clinical trials.

Function Syntax

derive_param_confirmed_resp( 
dataset, 
dataset_adsl, 
filter_source, 
source_pd = NULL, 
source_datasets = NULL, 
ref_confirm, 
max_nr_ne = 1, 
accept_sd = FALSE, 
aval_fun, 
set_values_to, 
subject_keys = get_admiral_option("subject_keys") 
)

Function Arguments

• dataset: The input dataset containing tumor response assessments. The dataset should include the necessary variables, such as PARAMCD, ADT, and AVALC, as well as unique subject identifiers defined by subject_keys. This dataset will be filtered based on the provided criteria.
• dataset_adsl: The ADSL dataset, containing subject-level baseline information. This dataset should include the unique subject identifiers and treatment dates for each subject.
• filter_source: A condition used to filter the dataset, selecting only the relevant records (e.g., tumor response assessments) that will be considered for the confirmed response calculation.
• source_pd: (Optional) A date source object that defines the first occurrence of Progressive Disease (PD). If provided, the function will restrict the dataset to observations that occur before or at the date specified in source_pd.
• source_datasets: A list of datasets that links the dataset names (such as source_pd) to the actual datasets used in the analysis.
• ref_confirm: The minimum number of days that must elapse between the initial response assessment and the confirmatory assessment. For example, if ref_confirm = 28, a confirmatory assessment must occur at least 28 days after the initial response to be considered valid.
• max_nr_ne: The maximum number of "Not Evaluable" (NE) assessments allowed between the initial response and the confirmatory assessment. If the number of NE assessments exceeds this threshold, the response will not be considered confirmed.
• accept_sd: A logical argument. If TRUE, one Stable Disease (SD) assessment is allowed between PR and its confirmatory assessment. If FALSE, no SD assessments are allowed during the confirmation period.
• aval_fun: A function used to convert the response category (AVALC) into numeric values. This function computes the response's numeric representation (e.g., CR = 0, PR = 1, SD = 2).
• set_values_to: A list of values that will be set for the new parameters added to the dataset. These parameters are specified using exprs(), and they include variables such as PARAMCD and PARAM, which define the confirmed response.
• subject_keys: Defines the unique subject identifiers for the dataset. This is a list of variables created using exprs() that ensures each subject is uniquely identified.

Confirmed Response Determination Process

The derive_param_confirmed_resp function determines whether a subject is a confirmed responder by checking the following conditions for each relevant response in the dataset:

• The input dataset is restricted to observations that match the filter_source condition. If specified, the dataset is further filtered to include only assessments before or at the date defined by source_pd.
• A subject is considered a confirmed responder if at least one observation in the filtered dataset satisfies the following conditions:
• Complete Response (CR):
• There is an initial response with AVALC == "CR".
• A confirmatory assessment must occur at least ref_confirm days after the initial CR assessment.
• All assessments between the initial response and the confirmatory assessment must be either "CR" or "NE" (Not Evaluable).
• The number of "NE" assessments between the initial response and the confirmatory assessment must not exceed max_nr_ne.
• Partial Response (PR):
• There is an initial response with AVALC == "PR".
• A confirmatory assessment must occur at least ref_confirm days after the initial PR assessment, and the confirmatory response can be either CR or PR.
• All assessments between the initial response and the confirmatory assessment must be "CR", "PR", "SD" (Stable Disease), or "NE" (Not Evaluable).
• No "PR" assessment should occur after a "CR" assessment in the confirmation period.
• The number of "NE" assessments between the initial response and the confirmatory assessment must not exceed max_nr_ne.
• If the accept_sd argument is set to TRUE, one "SD" assessment is allowed in the confirmation period. If accept_sd is FALSE, no SD assessments are allowed.
• If a subject is considered a confirmed responder, AVALC is set to "Y" for that subject, and ADT is set to the date of the first assessment where the response criteria are fulfilled.
• For all other subjects, AVALC is set to "N" and ADT is set to NA.
• The AVAL variable is then added to the dataset, with its value determined by applying the aval_fun function to AVALC.
• The parameters specified by the set_values_to argument are added to the new records, which include the confirmed response information (e.g., PARAMCD, PARAM).
• New observations with the confirmed response information are then added to the original dataset.

Example Usage

The following example demonstrates how to use derive_param_confirmed_resp with real data. The example uses a fictional ADSL and ADRS dataset, which contains tumor response categories like CR, PR, and SD.

library(dplyr)
library(lubridate)
library(admiral)
library(admiralonco)

# Construct ADSL dataset
adsl <- tibble::tribble(
~USUBJID, ~TRTSDTC,
"C301", "2022-06-01",
"C302", "2022-07-15",
"C303", "2022-08-10",
"C304", "2022-09-05"
) %>%
  mutate(TRTSDT = ymd(TRTSDTC), STUDYID = "YY789")

# Create ADRS dataset with different response values
adrs <- tibble::tribble(

~USUBJID, ~PARAMCD, ~AVALC, ~ADT,
"C301", "OVR", "PR", ymd("2022-07-01"),
"C301", "OVR", "CR", ymd("2022-08-05"),
"C302", "OVR", "SD", ymd("2022-08-20"),
"C303", "OVR", "PD", ymd("2022-09-15"),
"C304", "OVR", "NON-CR/NON-PD", ymd("2022-10-10")
) %>%
mutate(STUDYID = "YY789", ANL01FL = "Y")

# Define PD date source
pd_date <- date_source(
dataset_name = "adrs",
date = ADT,
filter = PARAMCD == "PD" & ANL01FL == "Y"
)

# Compute Confirmed Response
derive_param_confirmed_resp(
dataset = adrs,
dataset_adsl = adsl,
filter_source = PARAMCD == "OVR" & ANL01FL == "Y",
source_pd = pd_date,
source_datasets = list(adrs = adrs),
ref_confirm = 28,
max_nr_ne = 1,
accept_sd = TRUE,
set_values_to = exprs(PARAMCD = "CRSP", PARAM = "Confirmed Response by Investigator")
) %>%

  filter(PARAMCD == "CRSP")

This example demonstrates how to compute the confirmed response by filtering the dataset, setting the relevant conditions, and applying the derive_param_confirmed_resp function. The result includes a confirmed response for subjects who meet the defined criteria.

derive_param_response(
  dataset,
  dataset_adsl,
  filter_source,
  source_pd = NULL,
  source_datasets = NULL,
  set_values_to,
  aval_fun,
  subject_keys = get_admiral_option("subject_keys")
)

# Modified data
library(dplyr)
library(admiral)
library(lubridate)
library(tibble)

adsl <- tribble(
  ~USUBJID,
  "101",
  "102",
  "103",
  "104"
) %>%
  mutate(STUDYID = "YY9876")

adrs <- tribble(
  ~USUBJID, ~PARAMCD, ~ADTC,         ~AVALC, ~ANL01FL,
  "101",     "OVR",    "2021-01-01",  "PR",   "Y",
  "101",     "OVR",    "2021-02-01",  "CR",   "Y",
  "101",     "OVR",    "2021-03-01",  "CR",   "Y",
  "102",     "OVR",    "2021-06-10",  "SD",   "Y",
  "102",     "OVR",    "2021-07-15",  "PD",   "Y",
  "103",     "OVR",    "2021-08-12",  "PR",   "Y",
  "103",     "OVR",    "2021-09-20",  "PD",   "Y",
  "104",     "OVR",    "2021-10-01",  "SD",   "Y"
) %>%
  mutate(
    STUDYID = "YY9876",
    ADT = ymd(ADTC),
    ANL01FL = "Y"
  ) %>%
  select(-ADTC)

# Define the end of the assessment period for responses (before PD):
pd <- date_source(
  dataset_name = "adrs",
  date = ADT,
  filter = PARAMCD == "OVR" & AVALC == "Y"
)

# Derive the response parameter
derive_param_response(
  dataset = adrs,
  dataset_adsl = adsl,
  filter_source = PARAMCD == "OVR" & AVALC %in% c("CR", "PR") & ANL01FL == "Y",
  source_pd = pd,
  source_datasets = list(adrs = adrs),
  set_values_to = exprs(
    AVAL = yn_to_numeric(AVALC),
    PARAMCD = "RSP",
    PARAM = "Response by investigator"
  ),
  subject_keys = get_admiral_option("subject_keys")
) %>%
  arrange(USUBJID, PARAMCD, ADT)
  

filter_pd( 
  dataset, 
  filter, 
  source_pd, 
  source_datasets, 
  subject_keys = get_admiral_option("subject_keys")
)

library(dplyr) 
library(lubridate) 
library(admiral) 
library(admiralonco) 

adrs <- tibble::tribble( 

  ~STUDYID, ~USUBJID, ~PARAMCD, ~AVALC, ~ADT, ~ANL01FL, 
  "CDISCPILOT01", "01-701-1015", "OVR", "CR", "2016-01-25", "Y", 
  "CDISCPILOT01", "01-701-1015", "OVR", "SD", "2016-02-22", NA_character_, 
  "CDISCPILOT01", "01-701-1015", "OVR", "PD", "2016-02-22", "Y", 
  "CDISCPILOT01", "01-701-1015", "BOR", "CR", "2016-01-25", "Y", 
  "CDISCPILOT01", "01-701-1034", "OVR", "SD", "2015-12-07", "Y", 
  "CDISCPILOT01", "01-701-1034", "OVR", "PD", "2016-04-25", "Y", 
  "CDISCPILOT01", "01-701-1034", "OVR", "PD", "2016-06-25", "Y", 
  "CDISCPILOT01", "01-701-1034", "BOR", "SD", "2015-12-07", "Y", 
  "CDISCPILOT01", "01-701-1035", "OVR", "SD", "2016-04-25", "Y", 
  "CDISCPILOT01", "01-701-1035", "OVR", "PR", "2016-06-25", "Y", 
  "CDISCPILOT01", "01-701-1035", "BOR", "PR", "2016-06-25", "Y" 
) %>% mutate( 
  ADT = as_date(ADT) 
)

adevent <- tibble::tribble( 

  ~STUDYID, ~USUBJID, ~PARAMCD, ~AVALC, ~ADT, 
  "CDISCPILOT01", "01-701-1015", "PD", "Y", "2016-02-22", 
  "CDISCPILOT01", "01-701-1034", "PD", "Y", "2016-04-25" 
) %>% mutate( 
  ADT = as_date(ADT) 
)

pd <- date_source( 

  dataset_name = "adevent", 
  date = ADT, 
  filter = PARAMCD == "PD" 
)

filter_pd( 
  dataset = adrs, 
  filter = PARAMCD == "OVR" & ANL01FL == "Y", 
  source_pd = pd, 
  source_datasets = list(adevent = adevent) 
)

adsl <- tibble::tribble( 

  ~STUDYID, ~USUBJID, ~PDDT,
  "CDISCPILOT01", "01-701-1015", "2016-02-22", 
  "CDISCPILOT01", "01-701-1034", "2016-04-25", 
  "CDISCPILOT01", "01-701-1035", "" 
) %>% mutate( 
  PDDT = as_date(PDDT) 
)

pd <- date_source( 

  dataset_name = "adsl", 
  date = PDDT 
)

filter_pd( 
  dataset = adrs, 
  filter = PARAMCD == "OVR" & ANL01FL == "Y", 
  source_pd = pd, 
  source_datasets = list(adsl = adsl) 
)

adrs <- tibble::tribble( 
  ~STUDYID, ~USUBJID, ~PARAMCD, ~AVALC, ~ADT, ~ANL01FL, 
  "CDISCPILOT01", "01-701-1015", "OVR", "CR", "2016-01-25", "Y", 
  "CDISCPILOT01", "01-701-1015", "OVR", "SD", "2016-02-22", NA_character_, 
  "CDISCPILOT01", "01-701-1015", "OVR", "PD", "2016-02-22", "Y", 
  "CDISCPILOT01", "01-701-1034", "OVR", "SD", "2015-12-07", "Y", 
  "CDISCPILOT01", "01-701-1034", "OVR", "PD", "2016-04-25", "Y", 
  "CDISCPILOT01", "01-701-1034", "OVR", "PD", "2016-06-25", "Y", 
  "CDISCPILOT01", "01-701-1035", "OVR", "SD", "2016-04-25", "Y", 
  "CDISCPILOT01", "01-701-1035", "OVR", "PR", "2016-06-25", "Y", 
  "CDISCPILOT01", "01-701-1035", "BOR", "PR", "2016-06-25", "Y", 
  "CDISCPILOT01", "01-701-1015", "PD", "Y", "2016-02-22", "Y", 
  "CDISCPILOT01", "01-701-1034", "PD", "Y", "2016-04-25", "Y" 
) %>% mutate( 
  ADT = as_date(ADT) 
)

pd <- date_source( 

  dataset_name = "adrs",
  date = ADT, 
  filter = PARAMCD == "PD" 
)

filter_pd( 
  dataset = adrs, 
  filter = PARAMCD == "OVR" & ANL01FL == "Y", 
  source_pd = pd, 
  source_datasets = list(adrs = adrs)
)

get_crpr_dataset()

library(tibble)
library(dplyr)
library(lubridate)
library(admiralonco)
library(rlang)

adrs <- tribble(
  ~USUBJID, ~ADTC,        ~AVALC,
  "1",      "2020-01-01", "PR",
  "1",      "2020-02-01", "CR",
  "1",      "2020-02-16", "NE",
  "1",      "2020-03-01", "CR",
  "2",      "2020-02-06", "PR",
  "2",      "2020-02-16", "CR",
  "2",      "2020-03-30", "PR",
) %>%
  mutate(
    ADT = ymd(ADTC),
    STUDYID = "XX1234"
  )

signal_crpr(adrs, order = exprs(ADT))

get_crpr_dataset()

rsp_y

no_data_n

cb_y

bor_cr

bor_pr

bor_sd

bor_non_crpd

bor_pd

bor_ne

no_data_missing

crsp_y_cr

crsp_y_pr

cbor_cr

cbor_pr

# This shows the definition of all pre-defined `event` objects that ship
# with {admiralonco}
exports <- sort(getNamespaceExports("admiralonco"))
for (obj_name in exports) {
  obj <- getExportedValue("admiralonco", obj_name)
  if (inherits(obj, "event_def")) {
    cat("\n", obj_name, ":\n", sep = "")
    print(obj, indent = 2)
  }
} 

signal_crpr(
  dataset,
  order,
  msg = "Dataset contains CR records followed by PR.",
  subject_keys = get_admiral_option("subject_keys"),
  check_type = "warning"
)

library(tibble)
library(dplyr)
library(lubridate)
library(admiralonco)
library(rlang)

adrs <- tribble(
  ~USUBJID, ~ADTC,        ~AVALC,
  "1",      "2020-01-01", "PR",
  "1",      "2020-02-01", "CR",
  "1",      "2020-02-16", "NE",
  "1",      "2020-03-01", "CR",
  "2",      "2020-02-06", "PR",
  "2",      "2020-02-16", "CR",
  "2",      "2020-03-30", "PR",
) %>%
  mutate(
    ADT = ymd(ADTC),
    STUDYID = "XX1234"
  )

signal_crpr(adrs, order = exprs(ADT))