## Add a First Event Parameter

### Description

Add a new parameter for the first event occurring in a dataset. AVALC and AVAL indicate if an event occurred and ADT is set to the date of the first event. For example, the function can derive a parameter for the first disease progression.

### Usage

derive_param_first_event(
dataset,
dataset_source,
filter_source,
date_var,
subject_keys = vars(STUDYID, USUBJID),
set_values_to,
check_type = "warning"
)


### Arguments

 dataset Input dataset The PARAMCD variable is expected. dataset_adsl ADSL input dataset The variables specified for subject_keys are expected. For each observation of the specified dataset a new observation is added to the input dataset. dataset_source Source dataset All observations in the specified dataset fulfilling the condition specified by filter_source are considered as event. The variables specified by the subject_keys and date_var parameter are expected. filter_source Source filter All observations in dataset_source fulfilling the specified condition are considered as event. For subjects with at least one event AVALC is set to "Y", AVAL to 1, and ADT to the first date where the condition is fulfilled. For all other subjects AVALC is set to "N", AVAL to 0, and ADT to NA. date_var Date variable Date variable in the source dataset (dataset_source). The variable is used to sort the source dataset. ADT is set to the specified variable for events. 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 = "PD", PARAM = "Disease Progression") is expected. The values must be symbols, character strings, numeric values, or NA. check_type Check uniqueness? If "warning" or "error" is specified, a message is issued if the observations of the input dataset restricted to the source parameter (source_param) are not unique with respect to the subject keys (subject_key parameter) and ADT. Default: "warning" Permitted Values: "none", "warning", "error"

### Details

1. The input dataset is restricted to observations fulfilling filter_source.

2. For each subject (with respect to the variables specified for the subject_keys parameter) the first observation (with respect to date_var) where the event condition (filter_source parameter) is fulfilled is selected.

3. For each observation in dataset_adsl a new observation is created. For subjects with event AVALC is set to "Y", AVAL to 1, and ADT to the first date where the event condition is fulfilled. For all other subjects AVALC is set to "N", AVAL to 0, and ADT to NA. For subjects with event all variables from dataset_source are kept. For subjects without event all variables which are in both dataset_adsl and dataset_source are kept.

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 and when an event occurred

### 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_exist_flag(), derive_param_exposure(), 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 the first disease progression (PD)
~USUBJID, ~DTHDT,
"1",      ymd("2022-05-13"),
"2",      ymd(""),
"3",      ymd("")
) %>%
mutate(STUDYID = "XX1234")

"1",      "2020-01-02", "PR",
"1",      "2020-02-01", "CR",
"1",      "2020-03-01", "CR",
"1",      "2020-04-01", "SD",
"2",      "2021-06-15", "SD",
"2",      "2021-07-16", "PD",
"2",      "2021-09-14", "PD"
) %>%
mutate(
STUDYID = "XX1234",
PARAMCD = "OVR",
PARAM = "Overall Response",
ANL01FL = "Y"
) %>%

derive_param_first_event(
filter_source = PARAMCD == "OVR" & AVALC == "PD",
set_values_to = vars(
PARAMCD = "PD",
PARAM = "Disease Progression",
ANL01FL = "Y"
)
)

# derive parameter indicating death
derive_param_first_event(