#2139 chore: Make dataset_add mandatory for derive_extreme_records()

NEWS.md

@@ -15,6 +15,8 @@ were enhanced such that more than one summary variable can be derived, e.g.,
 
 ## Breaking Changes
 
+- `derive_extreme_records()` the `dataset_add` argument is now mandatory. (#2139)
+
 - In `derive_summary_records()` and `get_summary_records()` the arguments
 `analysis_var` and `summary_fun` were deprecated in favor of `set_values_to`.
 (#1792)

R/derive_extreme_records.R

@@ -1,46 +1,36 @@
 #' Add the First or Last Observation for Each By Group as New Records
 #'
 #' Add the first or last observation for each by group as new observations. The
-#' new observations can be selected from the input dataset or an additional
-#' dataset. This function can be used for adding the maximum or minimum value
-#' as a separate visit. All variables of the selected observation are kept. This
-#' distinguishes `derive_extreme_records()` from `derive_summary_records()`,
+#' new observations can be selected from the source dataset. This function can
+#' be used for adding the maximum or minimum value as a separate visit.
+#' All variables of the selected observation are kept. This distinguishes
+#' `derive_extreme_records()` from `derive_summary_records()`,
 #' where only the by variables are populated for the new records.
 #'
 #' @param dataset `r roxygen_param_dataset()`
 #'
-#'   If `dataset_add` is not specified, the new records are selected from the
-#'   input dataset. In this case the variables specified by `by_vars` and
-#'   `order` are expected.
-#'
 #' @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 dataset_add Additional dataset
-#'
-#'   Observations from the specified dataset are added as new records to the
-#'   input dataset (`dataset`).
+#' @param dataset_add Source dataset
 #'
-#'   All observations in the specified dataset fulfilling the condition
-#'   specified by `filter_source` are considered. If `mode` and `order` are
-#'   specified, the first or last observation within each by group, defined by
-#'   `by_vars`, is selected.
+#'   The source dataset, which determines the by groups returned in the input dataset,
+#'   based on the groups that exist in this dataset after being subset by `filter_add`.
 #'
-#'   If the argument is not specified, the input dataset (`dataset`) is used.
-#'
-#'   The variables specified by the `by_vars` and `order` argument (if
-#'   applicable) are expected.
+#'   The variables specified in the `by_vars` and `filter_add` parameters are expected
+#'   in this dataset. If `mode` and `order` are specified, the first or last observation
+#'   within each by group, defined by `by_vars`, is selected.
 #'
 #' @param by_vars Grouping variables
 #'
 #'   If `dataset_ref` is specified, this argument must be specified.
 #'
 #'   *Permitted Values*: list of variables created by `exprs()`
 #'
-#' @param filter_add Filter for additional dataset (`dataset_add`)
+#' @param filter_add Filter for source dataset (`dataset_add`)
 #'
 #'   Only observations in `dataset_add` fulfilling the specified condition are
 #'   considered.
@@ -56,7 +46,7 @@
 #' @param check_type Check uniqueness?
 #'
 #'   If `"warning"` or `"error"` is specified, the specified message is issued
-#'   if the observations of the (restricted) additional dataset are not unique
+#'   if the observations of the (restricted) source dataset are not unique
 #'   with respect to the by variables and the order.
 #'
 #'   *Permitted Values*: `"none"`, `"warning"`, `"error"`
@@ -65,7 +55,7 @@
 #'
 #'   The specified variable is added to the output dataset.
 #'
-#'   For by groups with at least one observation in the additional dataset
+#'   For by groups with at least one observation in the source dataset
 #'   (`dataset_add`) `exist_flag` is set to the value specified by the
 #'   `true_value` argument.
 #'
@@ -76,12 +66,12 @@
 #'
 #' @param true_value True value
 #'
-#'   For new observations selected from the additional dataset (`dataset_add`),
+#'   For new observations selected from the source dataset (`dataset_add`),
 #'   `exist_flag` is set to the specified value.
 #'
 #' @param false_value False value
 #'
-#'   For new observations not selected from the additional dataset
+#'   For new observations not selected from the source dataset
 #'   (`dataset_add`), `exist_flag` is set to the specified value.
 #'
 #' @param keep_source_vars Variables to be kept in the new records
@@ -104,7 +94,7 @@
 #' @inheritParams derive_summary_records
 #'
 #' @details
-#'   1. The additional dataset (`dataset_add`) is restricted as specified by the
+#'   1. The source dataset (`dataset_add`) is restricted as specified by the
 #'   `filter_add` argument.
 #'   1. For each group (with respect to the variables specified for the
 #'   `by_vars` argument) the first or last observation (with respect to the
@@ -284,8 +274,7 @@ derive_extreme_records <- function(dataset = NULL,
   )
   assert_data_frame(
     dataset_add,
-    required_vars = expr_c(by_vars, extract_vars(order)),
-    optional = TRUE
+    required_vars = expr_c(by_vars, extract_vars(order))
   )
   assert_data_frame(
     dataset_ref,
@@ -307,18 +296,8 @@ derive_extreme_records <- function(dataset = NULL,
   exist_flag <- assert_symbol(enexpr(exist_flag), optional = TRUE)
   filter_add <- assert_filter_cond(enexpr(filter_add), optional = TRUE)
   assert_varval_list(set_values_to)
-  if (is.null(dataset) && is.null(dataset_add)) {
-    abort(paste(
-      "Neither `dataset` nor `dataset_add` is specified.",
-      "At least one of them must be specified.",
-      sep = "\n"
-    ))
-  }
 
   # Create new observations
-  if (is.null(dataset_add)) {
-    dataset_add <- dataset
-  }
   new_add_obs <- filter_if(dataset_add, filter_add)
 
   if (!is.null(order)) {

inst/templates/ad_adlb.R

@@ -380,6 +380,7 @@ adlb <- adlb %>%
 adlb <- adlb %>%
   # get MINIMUM value
   derive_extreme_records(
+    dataset_add = adlb,
     by_vars = exprs(STUDYID, USUBJID, PARAMCD, BASETYPE),
     order = exprs(AVAL, ADT, AVISITN),
     mode = "first",
@@ -393,6 +394,7 @@ adlb <- adlb %>%
   ) %>%
   # get MAXIMUM value
   derive_extreme_records(
+    dataset_add = adlb,
     by_vars = exprs(STUDYID, USUBJID, PARAMCD, BASETYPE),
     order = exprs(desc(AVAL), ADT, AVISITN),
     mode = "first",
@@ -406,6 +408,7 @@ adlb <- adlb %>%
   ) %>%
   # get LOV value
   derive_extreme_records(
+    dataset_add = adlb,
     by_vars = exprs(STUDYID, USUBJID, PARAMCD, BASETYPE),
     order = exprs(ADT, AVISITN),
     mode = "last",

inst/templates/ad_advs.R

@@ -250,6 +250,7 @@ advs <- advs %>%
   # Assign TRTA, TRTP
   # Create End of Treatment Record
   derive_extreme_records(
+    dataset_add = advs,
     by_vars = exprs(STUDYID, USUBJID, PARAMCD, ATPTN),
     order = exprs(ADT, AVISITN, AVAL),
     mode = "last",

tests/testthat/test-derive_extreme_records.R

@@ -23,6 +23,7 @@ test_that("derive_extreme_records Test 1: add last observation for each group",
 
   actual_output <- derive_extreme_records(
     input,
+    dataset_add = input,
     order = exprs(AVISITN, LBSEQ),
     by_vars = exprs(USUBJID),
     mode = "last",
@@ -299,17 +300,13 @@ test_that("derive_extreme_records Test 5: latest evaluable tumor assessment date
   )
 })
 
-## Test 6: error if no input data ----
-test_that("derive_extreme_records Test 6: error if no input data", {
+## Test 6: error if no dataset_add ----
+test_that("derive_extreme_records Test 6: error if no dataset_add", {
   expect_error(
     derive_extreme_records(
       set_values_to = exprs(PARAMCD = "HELLO")
     ),
-    regexp = paste(
-      "Neither `dataset` nor `dataset_add` is specified.",
-      "At least one of them must be specified.",
-      sep = "\n"
-    ),
+    regexp = "`dataset_add` must be a data frame but is `NULL`",
     fixed = TRUE
   )
 })
@@ -339,6 +336,7 @@ test_that("derive_extreme_records Test 7: keep vars in `keep_source_vars` in the
 
   actual_output <- derive_extreme_records(
     input,
+    dataset_add = input,
     order = exprs(AVISITN, LBSEQ),
     by_vars = exprs(USUBJID),
     mode = "last",
@@ -377,6 +375,7 @@ test_that("derive_extreme_records Test 8: keep all vars in the new records when
 
   actual_output <- derive_extreme_records(
     input,
+    dataset_add = input,
     order = exprs(AVISITN, LBSEQ),
     by_vars = exprs(USUBJID),
     mode = "last",
@@ -391,8 +390,8 @@ test_that("derive_extreme_records Test 8: keep all vars in the new records when
   )
 })
 
-## Test 10: order vars from dataset_add ----
-test_that("derive_extreme_records Test 10: order vars from dataset_add", {
+## Test 9: order vars from dataset_add ----
+test_that("derive_extreme_records Test 9: order vars from dataset_add", {
   bds <- tibble::tribble(
     ~USUBJID, ~PARAMCD, ~AVALC,
     "1",      "PARAM",  "1"

vignettes/bds_finding.Rmd

@@ -927,6 +927,7 @@ assign a unique `AVISITN` value.
 ```{r eval=TRUE}
 advs_ex1 <- advs %>%
   derive_extreme_records(
+    dataset_add = advs,
     by_vars = exprs(STUDYID, USUBJID, PARAMCD),
     order = exprs(ADT, AVISITN, ATPTN, AVAL),
     mode = "last",
@@ -956,6 +957,7 @@ and assign a unique `AVISITN` value.
 ```{r eval=TRUE}
 advs_ex1 <- advs %>%
   derive_extreme_records(
+    dataset_add = advs,
     by_vars = exprs(STUDYID, USUBJID, PARAMCD),
     order = exprs(AVAL, ADT, AVISITN, ATPTN),
     mode = "first",