## Add the First or Last Observation for Each By Group as New Records

### Description

Add the first or last observation for each by group as new observations. It can be used for example for adding the maximum or minimum value as a separate visit. All variables of the selected observation are kept. This distinguish derive_extreme_records() from derive_summary_records(), where only the by variables are populated for the new records.

### Usage

derive_extreme_records(
dataset,
by_vars = NULL,
order,
mode,
check_type = "warning",
filter = NULL,
set_values_to
)


### Arguments

 dataset Input dataset The variables specified by the order and the by_vars parameter are expected. by_vars Grouping variables Default: NULL Permitted Values: list of variables created by vars() order Sort order Within each by group the observations are ordered by the specified order. Permitted Values: list of variables or ⁠desc()⁠ function calls created by vars(), e.g., vars(ADT, desc(AVAL)) mode Selection mode (first or last) If "first" is specified, the first observation of each by group is added to the input dataset. If "last" is specified, the last observation of each by group is added to the input dataset. Permitted Values: "first", "last" check_type Check uniqueness? If "warning" or "error" is specified, the specified message is issued if the observations of the input dataset are not unique with respect to the by variables and the order. Default: "warning" Permitted Values: "none", "warning", "error" filter Filter for observations to consider Only observations fulfilling the specified condition are taken into account for selecting the first or last observation. If the parameter is not specified, all observations are considered. Default: NULL Permitted Values: a condition set_values_to Variables to be set The specified variables are set to the specified values for the new observations. A list of variable name-value pairs is expected. LHS refers to a variable. RHS refers to the values to set to the variable. This can be a string, a symbol, a numeric value or NA, e.g., vars(PARAMCD = "TDOSE", PARCAT1 = "OVERALL"). More general expression are not allowed.

### Details

1. The input dataset is restricted as specified by the filter parameter.

2. For each group (with respect to the variables specified for the by_vars parameter) the first or last observation (with respect to the order specified for the order parameter and the mode specified for the mode parameter) is selected.

3. The variables specified by the set_values_to parameter are added to the selected observations.

4. The observations are added to input dataset.

### Value

The input dataset with the first or last observation of each by group added as new observations.

### Author(s)

Stefan Bundfuss

BDS-Findings Functions for adding Parameters/Records: default_qtc_paramcd(), derive_param_bmi(), derive_param_bsa(), derive_param_computed(), derive_param_doseint(), derive_param_exist_flag(), 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

adlb <- tibble::tribble(
~USUBJID, ~AVISITN, ~AVAL, ~LBSEQ,
"1",      1,          113,      1,
"1",      2,          113,      2,
"1",      3,          117,      3,
"2",      1,          101,      1,
"2",      2,          101,      2,
"2",      3,           95,      3
)

# Add a new record for each USUBJID storing the minimum value (first AVAL).
# If multiple records meet the minimum criterion, take the first value by
# AVISITN. Set AVISITN = 97 and DTYPE = MINIMUM for these new records.
derive_extreme_records(
by_vars = vars(USUBJID),
order = vars(AVAL, AVISITN),
mode = "first",
filter = !is.na(AVAL),
set_values_to = vars(
AVISITN = 97,
DTYPE = "MINIMUM"
)
)

# Add a new record for each USUBJID storing the maximum value (last AVAL).
# If multiple records meet the maximum criterion, take the first value by
# AVISITN. Set AVISITN = 98 and DTYPE = MAXIMUM for these new records.
derive_extreme_records(
by_vars = vars(USUBJID),
order = vars(desc(AVAL), AVISITN),
mode = "first",
filter = !is.na(AVAL),
set_values_to = vars(
AVISITN = 98,
DTYPE = "MAXIMUM"
)
)

# Add a new record for each USUBJID storing for the last value.
# Set AVISITN = 99 and DTYPE = LOV for these new records.
derive_extreme_records(