## Add an Existence Flag Parameter

### Description

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 measureable disease at baseline.

### Usage

derive_param_exist_flag(
dataset = NULL,
condition,
true_value = "Y",
false_value = NA_character_,
missing_value = NA_character_,
aval_fun = yn_to_numeric,
subject_keys = vars(STUDYID, USUBJID),
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 vars() is expected. set_values_to Variables to set A named list returned by vars() defining the variables to be set for the new parameter, e.g. vars(PARAMCD = "MDIS", PARAM = "Measurable Disease at Baseline") is expected. The values must be symbols, character strings, numeric values, or NA.

### 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.

### 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)

### Author(s)

Stefan Bundfuss

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

### Examples

library(dplyr)
library(lubridate)

# Derive a new parameter for measurable disease at baseline
~USUBJID,
"1",
"2",
"3"
) %>%
mutate(STUDYID = "XX1234")

tu <- tibble::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(