Closes #2126 unify_joined: update derive_vars_joined(), derive_var_joined_exist_flag(), filter_joined()

NEWS.md

@@ -12,6 +12,21 @@
 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)
 
+- The "joined" functions (`derive_vars_joined()`, `derive_var_joined_exist_flag()`,
+`filter_joined()`, and `event_joined()`) were unified: (#2126)
+    - The `dataset_add` and `filter_add` arguments were added to
+    `derive_var_joined_exist_flag()` and `filter_joined()`.
+    - The `filter` argument was renamed to `filter_join` in
+    `derive_var_joined_exist_flag()` and `filter_joined()`.
+    - The `tmp_obs_nr_var`, the `join_type`, the `first_cond_lower`, and the
+    `first_cond_upper` arguments were added to `derive_vars_joined()`.
+    - In `derive_var_joined_exist_flag()`, `filter_joined()`, and `event_joined()`
+    the `first_cond` argument was renamed to `first_cond_upper` and the
+    `first_cond_lower` argument was added.
+    - In all "joined" functions the `filter_add` argument is applied to the
+    additional dataset grouped by `by_vars` and the `filter_join` argument is
+    applied to the joined dataset grouped by the observations from the input
+    dataset. I.e., summary functions like `all()` or `any()` can be used.
 
 ## Breaking Changes
 
@@ -28,6 +43,13 @@ were enhanced such that more than one summary variable can be derived, e.g.,
 
 - The default value for the `false_value` argument in `derive_extreme_records()` was changed to `NA_character_` (#2125)
 
+- In `filter_joined()` and `derive_var_joined_exist_flag()` (#2126)
+    - the `first_cond` argument was deprecated in favor of `first_cond_upper` and
+    - the `filter` argument was deprecated in favor of `filter_join`.
+
+- In `event_joined()` the `first_cond` argument was deprecated in favor of
+`first_cond_upper`. (#2126)
+
 - 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_event.R

@@ -404,12 +404,14 @@ derive_extreme_event <- function(dataset,
       } else {
         data_events <- filter_joined(
           data_source,
+          dataset_add = data_source,
           by_vars = by_vars,
           join_vars = event$join_vars,
           join_type = event$join_type,
-          first_cond = !!event$first_cond,
+          first_cond_lower = !!event$first_cond_lower,
+          first_cond_upper = !!event$first_cond_upper,
           order = event_order,
-          filter = !!event$condition
+          filter_join = !!event$condition
         )
       }
       if (is.null(event$keep_source_vars)) {
@@ -467,6 +469,8 @@ derive_extreme_event <- function(dataset,
 #'   `derive_extreme_event()`. If the argument is not specified, the input
 #'   dataset (`dataset`) of `derive_extreme_event()` is used.
 #'
+#'   *Permitted Values*: a character scalar
+#'
 #' @param condition An unquoted condition for selecting the observations, which
 #'   will contribute to the extreme event. If the condition contains summary
 #'   functions like `all()`, they are evaluated for each by group separately.
@@ -489,6 +493,8 @@ derive_extreme_event <- function(dataset,
 #'   PARAM  = "Worst Sleeping Problems")`. The values can be a symbol, a
 #'   character string, a numeric value, `NA` or an expression.
 #'
+#'   *Permitted Values*: a named list of expressions, e.g., created by `exprs()`
+#'
 #' @param keep_source_vars Variables to keep from the source dataset
 #'
 #'   The specified variables are kept for the selected observations. The
@@ -504,6 +510,8 @@ derive_extreme_event <- function(dataset,
 #'   The description does not affect the derivations where the event is used. It
 #'   is intended for documentation only.
 #'
+#'   *Permitted Values*: a character scalar
+#'
 #' @keywords source_specifications
 #' @family source_specifications
 #'
@@ -559,9 +567,22 @@ event <- function(dataset_name = NULL,
 #'   `derive_extreme_event()`. If the argument is not specified, the input
 #'   dataset (`dataset`) of `derive_extreme_event()` is used.
 #'
+#'   *Permitted Values*: a character scalar
+#'
 #' @param condition An unquoted condition for selecting the observations, which
 #'   will contribute to the extreme event.
 #'
+#'   The condition is applied to the joined dataset for selecting the confirmed
+#'   observations. The condition can include summary functions. The joined
+#'   dataset is grouped by the original observations. I.e., the summary function
+#'   are applied to all observations up to the confirmation observation. For
+#'   example in the oncology setting when using this function for confirmed best
+#'   overall response,  `condition = AVALC == "CR" & all(AVALC.join %in% c("CR",
+#'   "NE")) & count_vals(var = AVALC.join, val = "NE") <= 1` selects
+#'   observations with response "CR" and for all observations up to the
+#'   confirmation observation the response is "CR" or "NE" and there is at most
+#'   one "NE".
+#'
 #'   *Permitted Values*: an unquoted condition
 #'
 #' @param join_vars Variables to keep from joined dataset
@@ -570,11 +591,13 @@ event <- function(dataset_name = NULL,
 #'   this parameter. The specified variables are added to the joined dataset
 #'   with suffix ".join". For example to select all observations with `AVALC ==
 #'   "Y"` and `AVALC == "Y"` for at least one subsequent visit `join_vars =
-#'   exprs(AVALC, AVISITN)` and `filter = AVALC == "Y" & AVALC.join == "Y" &
+#'   exprs(AVALC, AVISITN)` and `condition = AVALC == "Y" & AVALC.join == "Y" &
 #'   AVISITN < AVISITN.join` could be specified.
 #'
 #'   The `*.join` variables are not included in the output dataset.
 #'
+#'   *Permitted Values*: a named list of expressions, e.g., created by `exprs()`
+#'
 #' @param join_type Observations to keep after joining
 #'
 #'   The argument determines which of the joined observations are kept with
@@ -586,11 +609,45 @@ event <- function(dataset_name = NULL,
 #'
 #' @param first_cond Condition for selecting range of data
 #'
+#'   `r lifecycle::badge("deprecated")`
+#'
+#'   This argument is *deprecated*, please use `first_cond_upper` instead.
+#'
 #'   If this argument is specified, the other observations are restricted up to
 #'   the first observation where the specified condition is fulfilled. If the
 #'   condition is not fulfilled for any of the subsequent observations, all
 #'   observations are removed.
 #'
+#'   *Permitted Values*: an unquoted condition
+#'
+#' @param first_cond_lower Condition for selecting range of data (before)
+#'
+#'   If this argument is specified, the other observations are restricted from
+#'   the first observation before the current observation where the specified
+#'   condition is fulfilled up to the current observation. If the condition is
+#'   not fulfilled for any of the other observations, no observations are
+#'   considered, i.e., the observation is not flagged.
+#'
+#'   This parameter should be specified if `condition` contains summary
+#'   functions which should not apply to all observations but only from a
+#'   certain observation before the current observation up to the current
+#'   observation.
+#'
+#'   *Permitted Values*: an unquoted condition
+#'
+#' @param first_cond_upper Condition for selecting range of data (after)
+#'
+#'   If this argument is specified, the other observations are restricted up to
+#'   the first observation where the specified condition is fulfilled. If the
+#'   condition is not fulfilled for any of the other observations, no
+#'   observations are considered, i.e., the observation is not flagged.
+#'
+#'   This parameter should be specified if `condition` contains summary
+#'   functions which should not apply to all observations but only up to the
+#'   confirmation assessment.
+#'
+#'   *Permitted Values*: an unquoted condition
+#'
 #' @param order If specified, the specified variables or expressions are used to
 #'   select the first observation.
 #'
@@ -613,9 +670,22 @@ event_joined <- function(dataset_name = NULL,
                          join_vars,
                          join_type,
                          first_cond = NULL,
+                         first_cond_lower = NULL,
+                         first_cond_upper = NULL,
                          set_values_to = NULL,
                          keep_source_vars = NULL,
                          description = NULL) {
+  if (!missing(first_cond)) {
+    deprecate_warn(
+      "1.0.0",
+      "event_joined(first_cond=)",
+      "event_joined(first_cond_upper=)"
+    )
+    first_cond_upper <- assert_filter_cond(enexpr(first_cond), optional = TRUE)
+  } else {
+    first_cond_upper <- assert_filter_cond(enexpr(first_cond_upper), optional = TRUE)
+  }
+
   out <- list(
     description = assert_character_scalar(description, optional = TRUE),
     dataset_name = assert_character_scalar(dataset_name, optional = TRUE),
@@ -627,7 +697,8 @@ event_joined <- function(dataset_name = NULL,
       values = c("before", "after", "all"),
       case_sensitive = FALSE
     ),
-    first_cond = assert_filter_cond(enexpr(first_cond), optional = TRUE),
+    first_cond_lower = assert_filter_cond(enexpr(first_cond_lower), optional = TRUE),
+    first_cond_upper = first_cond_upper,
     set_values_to = assert_expr_list(
       set_values_to,
       named = TRUE,