Closes #2125 add true/false_value arguments for appropriate functions

NEWS.md

@@ -4,6 +4,8 @@
 
 ## Updates of Existing Functions
 
+- `derive_var_extreme_flag()` 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,8 @@ 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 following functions, which were deprecated in previous `{admiral}` versions, have been removed: (#2098)
   - `derive_param_extreme_event()`
   - `derive_vars_last_dose()`

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

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)
@@ -416,13 +419,16 @@ derive_vars_joined <- function(dataset,
   }
 
   # merge new variables to the input dataset and rename them
-  data %>%
+  data_final <- data %>%
     derive_vars_merged(
       dataset_add = data_return,
       by_vars = exprs(!!!by_vars_left, !!tmp_obs_nr),
       new_vars = add_suffix_to_vars(new_vars, vars = common_vars, suffix = ".join"),
       missing_values = missing_values,
       check_type = check_type,
+      exist_flag = exist_flag,
+      true_value = true_value,
+      false_value = false_value,
       duplicate_msg = paste(
         paste(
           "After applying `filter_join` the joined dataset contains more",
@@ -436,4 +442,9 @@ derive_vars_joined <- function(dataset,
       )
     ) %>%
     remove_tmp_vars()
+  if (is.null(exist_flag)) {
+    data_final <- data_final %>%
+      select(-starts_with("exist_"))
+  }
+  data_final
 }

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 `TRUE` for all selected records from `dataset_add` which are merged into
+#'   the input dataset, and `NA` 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)
 #'
@@ -283,6 +308,9 @@ derive_vars_merged <- function(dataset,
                                filter_add = NULL,
                                mode = NULL,
                                match_flag = NULL,
+                               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.null(match_flag)) {
+    deprecate_warn(
+      "1.0.0",
+      "derive_vars_merged(old_param = 'match_flag')",
+      "derive_vars_merged(new_param = '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(
@@ -348,15 +386,15 @@ derive_vars_merged <- function(dataset,
   }
 
   if (!is.null(missing_values)) {
-    match_flag_var <- get_new_tmp_var(add_data, prefix = "tmp_match_flag")
+    exist_flag_var <- get_new_tmp_var(add_data, prefix = "tmp_exist_flag")
   } else {
-    match_flag_var <- match_flag
+    exist_flag_var <- exist_flag
   }
 
-  if (!is.null(match_flag_var)) {
+  if (!is.null(exist_flag_var)) {
     add_data <- mutate(
       add_data,
-      !!match_flag_var := TRUE
+      !!exist_flag_var := true_value
     )
   }
   # check if there are any variables in both datasets which are not by vars
@@ -386,14 +424,18 @@ derive_vars_merged <- function(dataset,
     update_missings <- map2(
       syms(names(missing_values)),
       missing_values,
-      ~ expr(if_else(is.na(!!match_flag_var), !!.y, !!.x))
+      ~ expr(if_else(is.na(!!exist_flag_var), !!.y, !!.x))
     )
     names(update_missings) <- names(missing_values)
     dataset <- dataset %>%
-      mutate(!!!update_missings) %>%
-      remove_tmp_vars()
+      mutate(!!!update_missings)
+  }
+  if (!is.null(exist_flag_var)) {
+    dataset <- dataset %>%
+      mutate(!!exist_flag_var := ifelse(is.na(!!exist_flag_var), false_value, !!exist_flag_var))
   }
-  dataset
+  dataset %>%
+    remove_tmp_vars()
 }
 
 #' Merge an Existence Flag
@@ -659,14 +701,14 @@ derive_vars_merged_lookup <- function(dataset,
     new_vars = new_vars,
     mode = mode,
     filter_add = !!filter_add,
-    match_flag = temp_match_flag,
+    exist_flag = temp_exist_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(temp_exist_flag)) %>%
       distinct(!!!by_vars_left)
 
     if (nrow(temp_not_mapped) > 0) {
@@ -688,7 +730,7 @@ derive_vars_merged_lookup <- function(dataset,
     }
   }
 
-  res %>% select(-temp_match_flag)
+  res %>% select(-temp_exist_flag)
 }
 
 #' Get list of records not mapped from the lookup table.

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()
   }
 

R/globals.R

@@ -105,6 +105,7 @@ globalVariables(c(
   "temp_from_var",
   "temp_to_var",
   "temp_match_flag",
+  "temp_exist_flag",
   "temp_dose_freq",
   "temp_new_dose_no",
   "temp_num_of_doses",