Closes #2142 Supersede get_summary_records() and enhance derive_summary_records()

DESCRIPTION

@@ -38,8 +38,9 @@ LazyData: true
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.2.3
 Depends: R (>= 4.0)
+Remotes: pharmaverse/admiraldev 
 Imports:
-    admiraldev (>= 0.4.0),
+    admiraldev (>= 0.5.0.9000),
     dplyr (>= 0.8.4),
     hms (>= 0.5.3),
     lifecycle (>= 0.1.0),

NEWS.md

@@ -12,6 +12,8 @@
 were enhanced such that more than one summary variable can be derived, e.g.,
 `AVAL` as the sum and `ADT` as the maximum of the contributing records. (#1792)
 
+- `derive_summary_records()` was enhanced with the following optional arguments: `dataset_add`, `dataset_ref`, `missing_values`. These arguments respectively, generate summary variables from additional datasets, retain/add specific records that and impute user-defined missing values. (#2142)
+
 
 ## Breaking Changes
 

R/derive_summary_records.R

@@ -11,7 +11,19 @@
 #' retain those common values in the newly derived records. Otherwise new value
 #' will be set to `NA`.
 #'
-#' @param dataset  `r roxygen_param_dataset(expected_vars = c("by_vars", "analysis_var"))`
+#' @param dataset  `r roxygen_param_dataset(expected_vars = c("by_vars"))`
+#'
+#' @param dataset_add Additional dataset
+#'
+#'    The variables specified for `by_vars` are expected.
+#'   Observations from the specified dataset are going to be used to calculate and added
+#'   as new records to the input dataset (`dataset`).
+#'
+#' @param dataset_ref Reference dataset
+#'
+#'   The variables specified for `by_vars` are expected. For each
+#'   observation of the specified dataset a new observation is added to the
+#'   input dataset.
 #'
 #' @param by_vars Variables to consider for generation of groupwise summary
 #'   records. Providing the names of variables in [exprs()] will create a
@@ -29,6 +41,34 @@
 #'   + `filter = (dplyr::n() > 2)` will filter n count of `by_vars` greater
 #'   than 2.
 #'
+#' @param set_values_to Variables to be set
+#'
+#'   The specified variables are set to the specified values for the new
+#'   observations.
+#'
+#'   Set a list of variables to some specified value for the new records
+#'   + LHS refer to a variable.
+#'   + RHS refers to the values to set to the variable. This can be a string, a
+#'   symbol, a numeric value, an expression or NA. If summary functions are
+#'   used, the values are summarized by the variables specified for `by_vars`.
+#'
+#'   For example:
+#'   ```
+#'     set_values_to = exprs(
+#'       AVAL = sum(AVAL),
+#'       DTYPE = "AVERAGE",
+#'     )
+#'   ```
+#'
+#' @param missing_values Values for missing summary values
+#'
+#'   For observations of the input dataset (`dataset`) or (`dataset_add`) which do not have an
+#'   complete mapping defined by the summarization defined in `set_values_to`.  Only variables
+#'   specified for `set_values_to` can be specified for `missing_values`.
+#'
+#'   *Permitted Values*: named list of expressions, e.g.,
+#'   `exprs(AVAL = -9999)`
+#'
 #' @inheritParams get_summary_records
 #'
 #' @return A data frame with derived records appended to original dataset.
@@ -125,18 +165,33 @@
 #' ) %>%
 #'   arrange(USUBJID, AVISIT)
 derive_summary_records <- function(dataset,
+                                   dataset_add = NULL,
+                                   dataset_ref = NULL,
                                    by_vars,
                                    filter = NULL,
                                    analysis_var,
                                    summary_fun,
-                                   set_values_to) {
+                                   set_values_to = NULL,
+                                   missing_values = NULL) {
   assert_vars(by_vars)
   filter <- assert_filter_cond(enexpr(filter), optional = TRUE)
   assert_data_frame(
     dataset,
-    required_vars = by_vars
+    required_vars = expr_c(by_vars)
+  )
+  assert_data_frame(
+    dataset_add,
+    required_vars = expr_c(by_vars),
+    optional = TRUE
+  )
+  assert_data_frame(
+    dataset_ref,
+    required_vars = by_vars,
+    optional = TRUE
   )
+
   assert_varval_list(set_values_to)
+  assert_expr_list(missing_values, named = TRUE, optional = TRUE)
 
   if (!missing(analysis_var) || !missing(summary_fun)) {
     deprecate_warn(
@@ -149,14 +204,47 @@ derive_summary_records <- function(dataset,
     set_values_to <- exprs(!!analysis_var := {{ summary_fun }}(!!analysis_var), !!!set_values_to)
   }
 
-  # Summarise the analysis value and bind to the original dataset
-  bind_rows(
-    dataset,
-    get_summary_records(
-      dataset,
-      by_vars = by_vars,
-      filter = !!filter,
-      set_values_to = set_values_to
+  if (is.null(dataset_add)) {
+    dataset_add <- dataset
+  }
+
+  summary_records <- dataset_add %>%
+    group_by(!!!by_vars) %>%
+    filter_if(filter) %>%
+    summarise(!!!set_values_to) %>%
+    ungroup()
+
+  if (!is.null(missing_values)) {
+    update_missings <- map2(
+      syms(names(missing_values)),
+      missing_values,
+      ~ expr(if_else(is.na(!!.x), !!.y, !!.x))
     )
+    names(update_missings) <- names(missing_values)
+    summary_records <- summary_records %>%
+      mutate(!!!update_missings)
+  }
+
+  df_return <- bind_rows(
+    dataset,
+    summary_records
   )
+
+  if (!is.null(dataset_ref)) {
+    add_vars <- colnames(dataset_add)
+    ref_vars <- colnames(dataset_ref)
+
+    new_ref_obs <- anti_join(
+      select(dataset_ref, intersect(add_vars, ref_vars)),
+      select(summary_records, !!!by_vars),
+      by = map_chr(by_vars, as_name)
+    )
+
+    df_return <- bind_rows(
+      df_return,
+      new_ref_obs
+    )
+  }
+
+  return(df_return)
 }

R/get_summary_records.R

@@ -1,6 +1,13 @@
 #' Create Summary Records
 #'
 #' @description
+#'
+#' `r lifecycle::badge("superseded")`
+#'
+#' Development on `get_summary_records()` is complete, and for new code we recommend
+#' switching to using the `dataset_add` argument in `derive_summary_records()`,
+#' which is easier to use, has more features, and still under active development.
+#'
 #' It is not uncommon to have an analysis need whereby one needs to derive an
 #' analysis value (`AVAL`) from multiple records. The ADaM basic dataset
 #' structure variable `DTYPE` is available to indicate when a new derived
@@ -64,9 +71,9 @@
 #'
 #' @return A data frame of derived records.
 #'
-#' @family der_gen
+#' @family superseded
 #'
-#' @keywords der_gen
+#' @keywords internal
 #'
 #' @seealso [derive_summary_records()], [derive_var_merged_summary()]
 #'
@@ -154,7 +161,7 @@ get_summary_records <- function(dataset,
                                 filter = NULL,
                                 analysis_var,
                                 summary_fun,
-                                set_values_to) {
+                                set_values_to = NULL) {
   assert_vars(by_vars)
   filter <- assert_filter_cond(enexpr(filter), optional = TRUE)
   assert_data_frame(