Closes #2139 Make derive_extreme_records() consistent

NEWS.md

@@ -19,6 +19,8 @@ for the event number, which can be used in `order`. (#2140)
 
 ## 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,18 +1,14 @@
 #' 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 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()`,
 #' 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
@@ -21,18 +17,12 @@
 #'
 #' @param dataset_add Additional dataset
 #'
-#'   Observations from the specified dataset are added as new records to the
-#'   input dataset (`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.
-#'
-#'   If the argument is not specified, the input dataset (`dataset`) is used.
+#'   The additional 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`.
 #'
-#'   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
 #'
@@ -149,6 +139,7 @@
 #' # Specify the variables that need to be kept in the new records.
 #' derive_extreme_records(
 #'   adlb,
+#'   dataset_add = adlb,
 #'   by_vars = exprs(USUBJID),
 #'   order = exprs(AVAL, AVISITN),
 #'   mode = "first",
@@ -165,6 +156,7 @@
 #' # AVISITN. Set AVISITN = 98 and DTYPE = MAXIMUM for these new records.
 #' derive_extreme_records(
 #'   adlb,
+#'   dataset_add = adlb,
 #'   by_vars = exprs(USUBJID),
 #'   order = exprs(desc(AVAL), AVISITN),
 #'   mode = "first",
@@ -179,6 +171,7 @@
 #' # Set AVISITN = 99 and DTYPE = LOV for these new records.
 #' derive_extreme_records(
 #'   adlb,
+#'   dataset_add = adlb,
 #'   by_vars = exprs(USUBJID),
 #'   order = exprs(AVISITN),
 #'   mode = "last",
@@ -254,7 +247,7 @@
 #'   )
 #' )
 derive_extreme_records <- function(dataset = NULL,
-                                   dataset_add = NULL,
+                                   dataset_add,
                                    dataset_ref = NULL,
                                    by_vars = NULL,
                                    order = NULL,
@@ -271,21 +264,13 @@ derive_extreme_records <- function(dataset = NULL,
   assert_expr_list(order, optional = TRUE)
   assert_expr_list(keep_source_vars, optional = TRUE)
 
-  if (is.null(dataset_add)) {
-    expected_vars <- expr_c(by_vars, extract_vars(order))
-  } else {
-    expected_vars <- by_vars
-  }
-
   assert_data_frame(
     dataset,
-    required_vars = expected_vars,
     optional = TRUE
   )
   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 +292,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,11 +380,11 @@ 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",
-    # "AVISITN < 9997" to evaluate only real visits
-    filter_add = (!is.na(AVAL) & ONTRTFL == "Y" & AVISITN < 9997),
+    filter_add = (!is.na(AVAL) & ONTRTFL == "Y"),
     set_values_to = exprs(
       AVISITN = 9997,
       AVISIT = "POST-BASELINE MINIMUM",
@@ -393,11 +393,11 @@ 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",
-    # "AVISITN < 9997" to evaluate only real visits
-    filter_add = (!is.na(AVAL) & ONTRTFL == "Y" & AVISITN < 9997),
+    filter_add = (!is.na(AVAL) & ONTRTFL == "Y"),
     set_values_to = exprs(
       AVISITN = 9998,
       AVISIT = "POST-BASELINE MAXIMUM",
@@ -406,11 +406,11 @@ adlb <- adlb %>%
   ) %>%
   # get LOV value
   derive_extreme_records(
+    dataset_add = adlb,
     by_vars = exprs(STUDYID, USUBJID, PARAMCD, BASETYPE),
     order = exprs(ADT, AVISITN),
     mode = "last",
-    # "AVISITN < 9997" to evaluate only real visits
-    filter_add = (ONTRTFL == "Y" & AVISITN < 9997),
+    filter_add = (ONTRTFL == "Y"),
     set_values_to = exprs(
       AVISITN = 9999,
       AVISIT = "POST-BASELINE 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 = "argument \"dataset_add\" is missing, with no default",
     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",