Add an Existence Flag Parameter

Add a new parameter indicating that a certain event exists in a dataset. AVALC and AVAL indicate if an event occurred or not. For example, the function can derive a parameter indicating if there is measurable disease at baseline.

Usage

derive_param_exist_flag(
  dataset = NULL,
  dataset_adsl,
  dataset_add,
  condition,
  true_value = "Y",
  false_value = NA_character_,
  missing_value = NA_character_,
  filter_add = NULL,
  aval_fun = yn_to_numeric,
  subject_keys = get_admiral_option("subject_keys"),
  set_values_to
)

Arguments

dataset

Input dataset

The variables specified for subject_keys and the PARAMCD variable are expected.

dataset_adsl

ADSL input dataset

The variables specified for subject_keys are expected. For each subject (as defined by subject_keys) from the specified dataset (dataset_adsl), the existence flag is calculated and added as a new observation to the input datasets (dataset)

dataset_add

Additional dataset

The variables specified by the subject_keys parameter are expected.

This dataset is used to check if an event occurred or not. Any observation in the dataset fulfilling the event condition (condition) is considered as an event.

condition

Event condition

The condition is evaluated at the additional dataset (dataset_add).

For all subjects where it evaluates as TRUE at least once AVALC is set to the true value (true_value) for the new observations.

For all subjects where it evaluates as FALSE or NA for all observations AVALC is set to the false value (false_value).

For all subjects not present in the additional dataset AVALC is set to the missing value (missing_value).

true_value

True value

For all subjects with at least one observations in the additional dataset (dataset_add) fulfilling the event condition (condition), AVALC is set to the specified value (true_value).

Default: "Y"

Permitted Value: A character scalar

false_value

False value

For all subjects with at least one observations in the additional dataset (dataset_add) but none of them is fulfilling the event condition (condition), AVALC is set to the specified value (false_value).

Default: NA_character_

Permitted Value: A character scalar

missing_value

Values used for missing information

For all subjects without an observation in the additional dataset (dataset_add), AVALC is set to the specified value (missing_value).

Default: NA_character_

Permitted Value: A character scalar

filter_add

Filter for additional data

Only observations fulfilling the specified condition are taken into account for flagging. If the parameter is not specified, all observations are considered.

Permitted Values: a condition

aval_fun

Function to map character analysis value (AVALC) to numeric analysis value (AVAL)

The (first) argument of the function must expect a character vector and the function must return a numeric vector.

Default: yn_to_numeric (see yn_to_numeric() for details)

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 = "MDIS", PARAM = "Measurable Disease at Baseline") is expected. The values must be symbols, character strings, numeric values, or NA.

Value

The input dataset with a new parameter indicating if an event occurred (AVALC, AVAL, and the variables specified by subject_keys

and set_value_to are populated for the new parameter)

Details

1. The additional dataset (dataset_add) is restricted to the observations matching the filter_add condition.

2. For each subject in dataset_adsl a new observation is created.

   • The AVALC variable is added and set to the true value (true_value) if for the subject at least one observation exists in the (restricted) additional dataset where the condition evaluates to TRUE.

   • It is set to the false value (false_value) if for the subject at least one observation exists and for all observations the condition evaluates to FALSE or NA.

   • Otherwise, it is set to the missing value (missing_value), i.e., for those subject not in dataset_add.

3. The AVAL variable is added and set to aval_fun(AVALC).

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_exposure(), derive_param_extreme_event(), 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 measurable disease at baseline
adsl <- tribble(
  ~USUBJID,
  "1",
  "2",
  "3"
) %>%
  mutate(STUDYID = "XX1234")

tu <- tribble(
  ~USUBJID, ~VISIT,      ~TUSTRESC,
  "1",      "SCREENING", "TARGET",
  "1",      "WEEK 1",    "TARGET",
  "1",      "WEEK 5",    "TARGET",
  "1",      "WEEK 9",    "NON-TARGET",
  "2",      "SCREENING", "NON-TARGET",
  "2",      "SCREENING", "NON-TARGET"
) %>%
  mutate(
    STUDYID = "XX1234",
    TUTESTCD = "TUMIDENT"
  )

derive_param_exist_flag(
  dataset_adsl = adsl,
  dataset_add = tu,
  filter_add = TUTESTCD == "TUMIDENT" & VISIT == "SCREENING",
  condition = TUSTRESC == "TARGET",
  false_value = "N",
  missing_value = "N",
  set_values_to = exprs(
    PARAMCD = "MDIS",
    PARAM = "Measurable Disease at Baseline"
  )
)
#> # A tibble: 3 x 6
#>   USUBJID STUDYID AVALC  AVAL PARAMCD PARAM                         
#>   <chr>   <chr>   <chr> <dbl> <chr>   <chr>                         
#> 1 1       XX1234  Y         1 MDIS    Measurable Disease at Baseline
#> 2 2       XX1234  N         0 MDIS    Measurable Disease at Baseline
#> 3 3       XX1234  N         0 MDIS    Measurable Disease at Baseline