## Derive Last Dose with User-Defined Groupings

### Description

Add a variable for user-defined dose grouping of the last dose to the input dataset.

### Usage

derive_var_last_dose_grp(
dataset,
dataset_ex,
filter_ex = NULL,
by_vars = vars(STUDYID, USUBJID),
dose_id = vars(),
dose_date,
analysis_date,
single_dose_condition = (EXDOSFRQ == "ONCE"),
new_var,
grp_brks,
grp_lbls,
include_lowest = TRUE,
right = TRUE,
dose_var = EXDOSE,
traceability_vars = NULL
)


### Arguments

 dataset Input dataset. The variables specified by the by_vars and analysis_date parameters are expected. dataset_ex Input EX dataset. The variables specified by the by_vars, dose_date, new_vars parameters, and source variables from traceability_vars parameter are expected. filter_ex Filtering condition applied to EX dataset. For example, it can be used to filter for valid dose. Defaults to NULL. by_vars Variables to join by (created by dplyr::vars). dose_id Variables to identify unique dose (created by dplyr::vars). Defaults to empty vars(). dose_date The EX dose date variable. A date or date-time object is expected. analysis_date The analysis date variable. A date or date-time object is expected. single_dose_condition The condition for checking if dataset_ex is single dose. An error is issued if the condition is not true. Defaults to (EXDOSFRQ == "ONCE"). new_var The output variable defined by the user. grp_brks User supplied breaks to apply to groups. Refer to breaks parameter in cut() for details. grp_lbls User supplied labels to apply to groups. Refer to labels parameter in cut() for details. include_lowest logical, indicating if a value equal to the lowest (or highest, for right = FALSE) ‘breaks’ value should be included. Refer to include.lowest parameter in cut() for details. right Logical, indicating if the intervals should be closed on the right (and open on the left) or vice versa. Refer to right parameter in cut() for details. dose_var The source dose amount variable. Defaults to EXDOSE. traceability_vars A named list returned by vars() listing the traceability variables, e.g. vars(LDOSEDOM = "EX", LDOSESEQ = EXSEQ). The left-hand side (names of the list elements) gives the names of the traceability variables in the returned dataset. The right-hand side (values of the list elements) gives the values of the traceability variables in the returned dataset. These can be either strings or symbols referring to existing variables.

### Details

Last dose is the dose with maximum dose_date that is lower to or equal to the analysis_date per by_vars for each observation in dataset. The last dose group is then derived by user-defined grouping, which groups dose_var as specified in grp_brks, and returns grp_lbls as the values for new_var.

If dose information is aggregated (i.e. is a dosing frequency other than "ONCE" over a period defined by a start and end date) the function create_single_dose_dataset() can be used to generate single doses from aggregate dose information and satisfy single_dose_condition.

### Value

Input dataset with additional column new_var.

### Author(s)

Ben Straub

derive_vars_last_dose(), cut(), create_single_dose_dataset()

General Derivation Functions for all ADaMs that returns variable appended to dataset: derive_var_confirmation_flag(), derive_var_extreme_flag(), derive_var_last_dose_amt(), derive_var_last_dose_date(), derive_var_merged_cat(), derive_var_merged_character(), derive_var_merged_exist_flag(), derive_var_obs_number(), derive_var_worst_flag(), derive_vars_last_dose(), derive_vars_merged_lookup(), derive_vars_merged(), derive_vars_transposed(), get_summary_records()

### Examples

library(dplyr, warn.conflicts = FALSE)
data(ex_single)

ex_single <- derive_vars_dtm(
dtc = EXSTDTC,
new_vars_prefix = "EXST",
flag_imputation = "none"
)

derive_vars_dtm(
dtc = AESTDTC,
new_vars_prefix = "AST",
highest_imputation = "M"
)

derive_var_last_dose_grp(
dataset_ex = ex_single,
filter_ex = (EXDOSE > 0 | (EXDOSE == 0 & grepl("PLACEBO", EXTRT))) &
!is.na(EXSTDTM),
by_vars = vars(STUDYID, USUBJID),
dose_date = EXSTDTM,
new_var = LDGRP,
grp_brks = c(0, 20, 40, 60),
grp_lbls = c("Low", "Medium", "High"),
include_lowest = TRUE,
right = TRUE,
dose_var = EXDOSE,
analysis_date = ASTDTM,
traceability_vars = vars(LDOSEDOM = "EX", LDOSESEQ = EXSEQ, LDOSEVAR = "EXENDTC")
) %>%
select(USUBJID, LDGRP, LDOSEDOM, LDOSESEQ, LDOSEVAR)