Closes #2639 param_tte_ties: break ties and document it

NAMESPACE

@@ -284,6 +284,7 @@ importFrom(rlang,sym)
 importFrom(rlang,syms)
 importFrom(rlang,type_of)
 importFrom(rlang,warn)
+importFrom(rlang,zap)
 importFrom(stats,setNames)
 importFrom(stringr,str_c)
 importFrom(stringr,str_count)

NEWS.md

@@ -111,6 +111,11 @@ default. To enable it the new admiral option `save_memory` has to be set to
 
 - `derive_var_joined_exist_flag()` documentation updated with extra examples. (#2523)
 
+- In the `derive_param_tte()` documentation is was clarified which
+event/censoring is selected if there is more than one at the same date (for
+events the first one specified in `event_conditions` and for censoring the last
+one in `censor_conditions`). (#2639)
+
 ## Various
 
 <details>

R/admiral-package.R

@@ -21,7 +21,7 @@
 #'   current_env .data enexpr enexprs eval_bare eval_tidy expr expr_interp exec
 #'   expr_label exprs f_lhs f_rhs  inform is_call is_expression is_missing
 #'   is_named list2 new_environment new_formula parse_expr parse_exprs set_names
-#'   sym syms type_of warn
+#'   sym syms type_of warn zap
 #' @importFrom stats setNames
 #' @importFrom stringr str_c str_count str_detect str_extract str_glue
 #'             str_length str_locate str_locate_all str_match str_remove

R/derive_param_tte.R

@@ -76,7 +76,7 @@
 #'
 #'   \enumerate{ \item For each event source dataset the observations as
 #'   specified by the `filter` element are selected. Then for each patient the
-#'   first observation (with respect to `date`) is selected.
+#'   first observation (with respect to `date` and `order`) is selected.
 #'
 #'   \item The `ADT` variable is set to the variable specified by the
 #'   \code{date} element. If the date variable is a datetime variable, only
@@ -90,14 +90,16 @@
 #'   \item The selected observations of all event source datasets are combined into a
 #'   single dataset.
 #'
-#'   \item For each patient the first observation (with respect to the `ADT`
-#'   variable) from the single dataset is selected. }
+#'   \item For each patient the first observation (with respect to the
+#'   `ADT`/`ADTM` variable) from the single dataset is selected. If there is
+#'   more than one event with the same date, the first event with respect to the
+#'   order of events in `event_conditions` is selected.}
 #'
 #'   **Deriving the censoring observations:**
 #'
 #'   \enumerate{ \item For each censoring source dataset the observations as
 #'   specified by the `filter` element are selected. Then for each patient the
-#'   last observation (with respect to `date`) is selected.
+#'   last observation (with respect to `date` and `order`) is selected.
 #'
 #'   \item The `ADT` variable is set to the variable specified by the
 #'   \code{date} element. If the date variable is a datetime variable, only
@@ -111,8 +113,10 @@
 #'   \item The selected observations of all censoring source datasets are
 #'   combined into a single dataset.
 #'
-#'   \item For each patient the last observation (with respect to the `ADT`
-#'   variable) from the single dataset is selected. }
+#'   \item For each patient the last observation (with respect to the
+#'   `ADT`/`ADTM` variable) from the single dataset is selected.  If there is
+#'   more than one censoring with the same date, the last censoring with respect
+#'   to the order of censorings in `censor_conditions` is selected.}
 #'
 #'   For each subject (as defined by the `subject_keys` parameter) an
 #'   observation is selected. If an event is available, the event observation is
@@ -498,7 +502,7 @@ derive_param_tte <- function(dataset = NULL,
     by_vars = expr_c(subject_keys, by_vars),
     order = exprs(!!tmp_event),
     mode = "last",
-    check_type = check_type
+    check_type = "none"
   ) %>%
     inner_join(
       adsl,
@@ -726,6 +730,7 @@ filter_date_sources <- function(sources,
       !!!sources[[i]]$set_values_to,
       CNSR = sources[[i]]$censor,
       !!!date_derv,
+      tmp_source_nr = i,
       .keep = "none"
     )
   }
@@ -736,10 +741,11 @@ filter_date_sources <- function(sources,
     filter(!is.na(!!date_var)) %>%
     filter_extreme(
       by_vars = expr_c(subject_keys, by_vars),
-      order = exprs(!!date_var),
+      order = exprs(!!date_var, tmp_source_nr),
       mode = mode,
-      check_type = check_type
-    )
+      check_type = "none"
+    ) %>%
+    select(-tmp_source_nr)
 }
 
 #' Add By Groups to All Datasets if Necessary

R/globals.R

@@ -71,6 +71,7 @@ globalVariables(c(
   "time_differential_dt",
   "tmp_obs_nr_filter_relative",
   "tmp_obs_nr_match_filter_relative",
+  "tmp_source_nr",
   "PREFIX",
   "PREFIX_CD",
   "PREFIX_NAM",

inst/WORDLIST

@@ -36,8 +36,8 @@ Alanine
 Alkalosis
 Analyte
 Ania
-Aspartate
 Asha
+Aspartate
 BDS
 BILI
 BLQ
@@ -291,7 +291,6 @@ eGFR
 eg
 egfr
 evaluable
-exponentiate
 exprs
 fil
 findable
@@ -312,7 +311,6 @@ msec
 nd
 occds
 onwards
-param
 parttime
 pharmaverse
 pharmaverseadam

tests/testthat/test-derive_param_tte.R

@@ -170,14 +170,16 @@ test_that("derive_param_tte Test 2: new parameter with analysis datetime is deri
   )
 })
 
-## Test 3: no new observations for subjects not in ADSL ----
-test_that("derive_param_tte Test 3: no new observations for subjects not in ADSL", {
+## Test 3: no records for subjects not in ADSL, multiple events/cens ----
+test_that("derive_param_tte Test 3: no records for subjects not in ADSL, multiple events/cens", {
+  # For subject 01 both events are at the same date, for subject 04 both censorings
+  # are at the same date
   adsl <- tibble::tribble(
     ~USUBJID, ~DTHFL, ~DTHDT,            ~RSPDT,
-    "01",     "Y",    ymd("2021-06-12"), ymd("2021-03-04"),
+    "01",     "Y",    ymd("2021-05-05"), ymd("2021-03-04"),
     "02",     "N",    NA,                NA,
     "03",     "Y",    ymd("2021-08-21"), NA,
-    "04",     "N",    NA,                ymd("2021-04-14"),
+    "04",     "N",    NA,                ymd("2021-05-15"),
     "05",     "N",    NA,                NA
   ) %>%
     mutate(STUDYID = "AB42")
@@ -189,7 +191,7 @@ test_that("derive_param_tte Test 3: no new observations for subjects not in ADSL
     "01",     "PD",   ymd("2021-05-05"), 3,
     "02",     "PD",   ymd("2021-02-03"), 1,
     "04",     "SD",   ymd("2021-02-13"), 1,
-    "04",     "PR",   ymd("2021-04-14"), 2,
+    "04",     "SD",   ymd("2021-04-14"), 2,
     "04",     "CR",   ymd("2021-05-15"), 3
   ) %>%
     mutate(STUDYID = "AB42", PARAMCD = "OVR")
@@ -259,7 +261,7 @@ test_that("derive_param_tte Test 3: no new observations for subjects not in ADSL
     dataset_adsl = filter(adsl, !is.na(RSPDT)),
     start_date = RSPDT,
     event_conditions = list(pd, death),
-    censor_conditions = list(lastvisit, first_response),
+    censor_conditions = list(first_response, lastvisit),
     source_datasets = list(adsl = adsl, adrs = adrs),
     set_values_to = exprs(
       PARAMCD = "DURRSP",