pharmaverse · zdz2101 · Oct 13, 2023 · Sep 27, 2023 · Sep 27, 2023 · Sep 27, 2023
diff --git a/NEWS.md b/NEWS.md
@@ -4,6 +4,8 @@
 
 ## Updates of Existing Functions
 
+- `derive_extreme_records()`, `derive_var_extreme_flag()`,`derive_vars_joined()` and `derive_vars_merged()` were enhanced with the arguments `true_value` and `false_value` to align with preexisting functions that had similar functionality (#2125)
+
 - `restrict_derivation()` now allows `{dplyr}` functions like `mutate` in the `derivation argument (#2143)
 
 - `derive_summary_records()`, `derive_var_merged_summary()`, and `get_summary_records()`
@@ -22,6 +24,10 @@ were enhanced such that more than one summary variable can be derived, e.g.,
 
 - admiral now only supports R >= 4.0.0 
 
+- For the function `derive_vars_merged()`, the argument `match_flag` was renamed to `exist_flag` (#2125)
+
+- The default value for the `false_value` argument in `derive_extreme_records()` was changed to `NA_character_` (#2125)
+
 - The following functions, which were deprecated in previous `{admiral}` versions, have been removed: (#2098)
   - `derive_param_extreme_event()`
   - `derive_vars_last_dose()`

diff --git a/R/derive_extreme_records.R b/R/derive_extreme_records.R
@@ -263,7 +263,7 @@ derive_extreme_records <- function(dataset = NULL,
                                    check_type = "warning",
                                    exist_flag = NULL,
                                    true_value = "Y",
-                                   false_value = "N",
+                                   false_value = NA_character_,
                                    keep_source_vars = exprs(everything()),
                                    set_values_to) {
   # Check input arguments

diff --git a/R/derive_joined.R b/R/derive_joined.R
@@ -329,6 +329,9 @@ derive_vars_joined <- function(dataset,
                                filter_add = NULL,
                                filter_join = NULL,
                                mode = NULL,
+                               exist_flag = NULL,
+                               true_value = "Y",
+                               false_value = NA_character_,
                                missing_values = NULL,
                                check_type = "warning") {
   assert_vars(by_vars, optional = TRUE)
@@ -423,6 +426,9 @@ derive_vars_joined <- function(dataset,
       new_vars = add_suffix_to_vars(new_vars, vars = common_vars, suffix = ".join"),
       missing_values = missing_values,
       check_type = check_type,
+      exist_flag = !!enexpr(exist_flag),
+      true_value = true_value,
+      false_value = false_value,
       duplicate_msg = paste(
         paste(
           "After applying `filter_join` the joined dataset contains more",

diff --git a/R/derive_merged.R b/R/derive_merged.R
@@ -81,13 +81,38 @@
 #'
 #' @param match_flag Match flag
 #'
+#'  `r lifecycle::badge("deprecated")` Please use `exist_flag` instead.
+#'
 #'   If the argument is specified (e.g., `match_flag = FLAG`), the specified
 #'   variable (e.g., `FLAG`) is added to the input dataset. This variable will
 #'   be `TRUE` for all selected records from `dataset_add` which are merged into
 #'   the input dataset, and `NA` otherwise.
 #'
 #'   *Permitted Values*: Variable name
 #'
+#' @param exist_flag Exist flag
+#'
+#'   If the argument is specified (e.g., `exist_flag = FLAG`), the specified
+#'   variable (e.g., `FLAG`) is added to the input dataset. This variable will
+#'   be the value provided in `true_value` for all selected records from `dataset_add`
+#'   which are merged into the input dataset, and the value provided in `false_value` otherwise.
+#'
+#'   *Permitted Values*: Variable name
+#'
+#' @param true_value True value
+#'
+#'   The value for the specified variable `exist_flag`, applicable to
+#'   the first or last observation (depending on the mode) of each by group.
+#'
+#'   Permitted Values: An atomic scalar
+#'
+#' @param false_value False value
+#'
+#'   The value for the specified variable `exist_flag`, NOT applicable to
+#'   the first or last observation (depending on the mode) of each by group.
+#'
+#'   Permitted Values: An atomic scalar
+#'
 #' @param missing_values Values for non-matching observations
 #'
 #'   For observations of the input dataset (`dataset`) which do not have a
@@ -198,7 +223,7 @@
 #'   mode = "last",
 #'   new_vars = exprs(LASTWGT = VSSTRESN, LASTWGTU = VSSTRESU),
 #'   filter_add = VSTESTCD == "WEIGHT",
-#'   match_flag = vsdatafl
+#'   exist_flag = vsdatafl
 #' ) %>%
 #'   select(STUDYID, USUBJID, AGE, AGEU, LASTWGT, LASTWGTU, vsdatafl)
 #'
@@ -282,7 +307,10 @@ derive_vars_merged <- function(dataset,
                                new_vars = NULL,
                                filter_add = NULL,
                                mode = NULL,
-                               match_flag = NULL,
+                               match_flag,
+                               exist_flag = NULL,
+                               true_value = "Y",
+                               false_value = NA_character_,
                                missing_values = NULL,
                                check_type = "warning",
                                duplicate_msg = NULL) {
@@ -301,7 +329,17 @@ derive_vars_merged <- function(dataset,
       extract_vars(new_vars)
     )
   )
-  match_flag <- assert_symbol(enexpr(match_flag), optional = TRUE)
+  if (!is_missing(enexpr(match_flag))) {
+    deprecate_warn(
+      "1.0.0",
+      "derive_vars_merged(match_flag =)",
+      "derive_vars_merged(exist_flag =)"
+    )
+    exist_flag <- assert_symbol(enexpr(match_flag), optional = TRUE)
+  }
+  exist_flag <- assert_symbol(enexpr(exist_flag), optional = TRUE)
+  assert_atomic_vector(true_value, optional = TRUE)
+  assert_atomic_vector(false_value, optional = TRUE)
   assert_expr_list(missing_values, named = TRUE, optional = TRUE)
   if (!is.null(missing_values)) {
     invalid_vars <- setdiff(
@@ -347,18 +385,18 @@ derive_vars_merged <- function(dataset,
       select(!!!by_vars_right, !!!replace_values_by_names(new_vars))
   }
 
-  if (!is.null(missing_values)) {
+  if (!is.null(missing_values) || !is.null(exist_flag)) {
     match_flag_var <- get_new_tmp_var(add_data, prefix = "tmp_match_flag")
   } else {
-    match_flag_var <- match_flag
+    match_flag_var <- NULL
   }
-
   if (!is.null(match_flag_var)) {
     add_data <- mutate(
       add_data,
       !!match_flag_var := TRUE
     )
   }
+
   # check if there are any variables in both datasets which are not by vars
   # in this case an error is issued to avoid renaming of varibles by left_join()
   common_vars <-
@@ -382,18 +420,24 @@ derive_vars_merged <- function(dataset,
   }
   dataset <- left_join(dataset, add_data, by = vars2chr(by_vars))
 
-  if (!is.null(missing_values)) {
+  if (!is.null(match_flag_var)) {
     update_missings <- map2(
       syms(names(missing_values)),
       missing_values,
       ~ expr(if_else(is.na(!!match_flag_var), !!.y, !!.x))
     )
     names(update_missings) <- names(missing_values)
     dataset <- dataset %>%
-      mutate(!!!update_missings) %>%
-      remove_tmp_vars()
+      mutate(!!!update_missings)
   }
-  dataset
+
+  if (!is.null(exist_flag)) {
+    dataset <- dataset %>%
+      mutate(!!exist_flag := ifelse(is.na(!!match_flag_var), false_value, true_value))
+  }
+
+  dataset %>%
+    remove_tmp_vars()
 }
 
 #' Merge an Existence Flag
@@ -651,6 +695,8 @@ derive_vars_merged_lookup <- function(dataset,
   assert_logical_scalar(print_not_mapped)
   filter_add <- assert_filter_cond(enexpr(filter_add), optional = TRUE)
 
+  tmp_lookup_flag <- get_new_tmp_var(dataset_add, prefix = "tmp_lookup_flag")
+
   res <- derive_vars_merged(
     dataset,
     dataset_add,
@@ -659,14 +705,14 @@ derive_vars_merged_lookup <- function(dataset,
     new_vars = new_vars,
     mode = mode,
     filter_add = !!filter_add,
-    match_flag = temp_match_flag,
+    exist_flag = !!tmp_lookup_flag,
     check_type = check_type,
     duplicate_msg = duplicate_msg
   )
 
   if (print_not_mapped) {
     temp_not_mapped <- res %>%
-      filter(is.na(temp_match_flag)) %>%
+      filter(is.na(!!tmp_lookup_flag)) %>%
       distinct(!!!by_vars_left)
 
     if (nrow(temp_not_mapped) > 0) {
@@ -688,7 +734,7 @@ derive_vars_merged_lookup <- function(dataset,
     }
   }
 
-  res %>% select(-temp_match_flag)
+  res %>% remove_tmp_vars()
 }
 
 #' Get list of records not mapped from the lookup table.

diff --git a/R/derive_var_extreme_flag.R b/R/derive_var_extreme_flag.R
@@ -14,8 +14,8 @@
 #'
 #' @param new_var Variable to add
 #'
-#'   The specified variable is added to the output dataset. It is set to `"Y"`
-#'   for the first or last observation (depending on the mode) of each by group.
+#'   The specified variable is added to the output dataset. It is set to the value
+#'   set in `true_value` for the first or last observation (depending on the mode) of each by group.
 #'
 #'   Permitted Values: list of name-value pairs
 #'
@@ -25,6 +25,20 @@
 #'
 #'   Permitted Values: `"first"`, `"last"`
 #'
+#' @param true_value True value
+#'
+#'   The value for the specified variable `new_var`, applicable to
+#'   the first or last observation (depending on the mode) of each by group.
+#'
+#'   Permitted Values: An atomic scalar
+#'
+#' @param false_value False value
+#'
+#'   The value for the specified variable `new_var`, NOT applicable to
+#'   the first or last observation (depending on the mode) of each by group.
+#'
+#'   Permitted Values: An atomic scalar
+#'
 #' @param flag_all Flag setting
 #'
 #'   A logical value where if set to `TRUE`, all records are flagged
@@ -232,13 +246,17 @@ derive_var_extreme_flag <- function(dataset,
                                     order,
                                     new_var,
                                     mode,
+                                    true_value = "Y",
+                                    false_value = NA_character_,
                                     flag_all = FALSE,
                                     check_type = "warning") {
   new_var <- assert_symbol(enexpr(new_var))
   assert_vars(by_vars)
   assert_expr_list(order)
   assert_data_frame(dataset, required_vars = exprs(!!!by_vars, !!!extract_vars(order)))
   mode <- assert_character_scalar(mode, values = c("first", "last"), case_sensitive = FALSE)
+  assert_atomic_vector(true_value, optional = TRUE)
+  assert_atomic_vector(false_value, optional = TRUE)
   flag_all <- assert_logical_scalar(flag_all)
   check_type <- assert_character_scalar(
     check_type,
@@ -263,11 +281,11 @@ derive_var_extreme_flag <- function(dataset,
 
   if (mode == "first") {
     data <- data %>%
-      mutate(!!new_var := if_else(!!tmp_obs_nr == 1, "Y", NA_character_))
+      mutate(!!new_var := if_else(!!tmp_obs_nr == 1, true_value, false_value))
   } else {
     data <- data %>%
       group_by(!!!by_vars) %>%
-      mutate(!!new_var := if_else(!!tmp_obs_nr == n(), "Y", NA_character_)) %>%
+      mutate(!!new_var := if_else(!!tmp_obs_nr == n(), true_value, false_value)) %>%
       ungroup()
   }
 

diff --git a/R/globals.R b/R/globals.R
@@ -104,7 +104,6 @@ globalVariables(c(
   "temp_DT",
   "temp_from_var",
   "temp_to_var",
-  "temp_match_flag",
   "temp_dose_freq",
   "temp_new_dose_no",
   "temp_num_of_doses",

diff --git a/man/derive_extreme_records.Rd b/man/derive_extreme_records.Rd
diff --git a/man/derive_var_extreme_flag.Rd b/man/derive_var_extreme_flag.Rd
diff --git a/man/derive_vars_joined.Rd b/man/derive_vars_joined.Rd