Merge branch 'main' into 2521_remove_lifecycle_deprecation_code_for_g…

…et_summary_records

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: admiral
 Title: ADaM in R Asset Library
-Version: 1.1.1.9029
+Version: 1.1.1.9030
 Authors@R: c(
     person("Ben", "Straub", , "[email protected]", role = c("aut", "cre")),
     person("Stefan", "Bundfuss", role = "aut",

NEWS.md

@@ -13,6 +13,12 @@
 
 ## Updates of Existing Functions
 
+- NCICTCAEv5 grading criteria (`atoxgr_criteria_ctcv5`):
+
+  - fix for `TERM = "INR increased"`, criteria was wrongly using `x ULN`, for first part of criteria for grades 1 to 3. For example, `">2.5 x ULN"` changed to `">2.5"` for grade 3. (#2534).
+  - when looking at abnormal baseline we now use `BNRIND` instead of comparing `BASE` with `ANRHI`,  as `ANRHI` may differ within a subject and lab test due to data from different lab vendors. This effects 5 terms, namely, `Alanine aminotransferase increased`, `Alkaline phosphatase increased`, `Aspartate aminotransferase increased`, `Blood bilirubin increased` and `GGT Increased`. (#249)
+  - `derive_var_atoxgr_dir()`: new argument `abnormal_indicator` to pass in value of `BNRIND` to indicate lab test is abnormal. This is only used for the 5 lab tests described above. (#249)
+
 - The `keep_nas` argument of `derive_param_computed()` was enhanced such that it
 is now possible to specify a list of variables for which `NA`s are acceptable.
 I.e., records are added even if some of the specified variables are `NA`.
@@ -29,10 +35,6 @@ of the input parameters. (#2513)
 some of the requested query variables are already present in the input dataset
 or that the queries dataset contains duplicates. (#2543)
 
-- NCICTCAEv5 grading criteria fixed for `TERM = "INR Increased"`, criteria was
-wrongly using `x ULN`, for first part of criteria for grades 1 to 3. For
-example, `">2.5 x ULN"` changed to `">2.5"` for grade 3. (#2534)
-
 - `derive_vars_atc()` and `create_single_dose_dataset()` `by_vars` argument updated to use `get_admiral_option("subject_keys")` instead of  `USUBJID` or `STUDYID` in `bds_exposure.Rmd`. (#2501)
 
 - test scripts, R, and markdown files for `create_single_dose_dataset` and `occds.Rmd` updated to include a `STUDYID` column because of `get_admiral_option("subject_keys")` update above. (#2501)

R/derive_var_atoxgr.R

@@ -42,6 +42,14 @@
 #'
 #' Permitted Values: "L", "H"
 #'
+#' @param abnormal_indicator Value in `BNRIND` derivation to indicate an abnormal value.
+#' Usually "HIGH" for `criteria_direction` = "H" and "LOW" for `criteria_direction` = "L".
+#'
+#'   This is only required when `meta_criteria = atoxgr_criteria_ctcv5` and `BNRIND` is a required
+#'   variable. Currently for terms `"Alanine aminotransferase increased"`,
+#'   `"Alkaline phosphatase increased"`, `"Aspartate aminotransferase increased"`,
+#'   `"Blood bilirubin increased"` and `"GGT increased"`
+#'
 #' @param get_unit_expr An expression providing the unit of the parameter
 #'
 #'   The result is used to check the units of the input parameters. Compared with
@@ -118,6 +126,7 @@ derive_var_atoxgr_dir <- function(dataset,
                                   tox_description_var,
                                   meta_criteria,
                                   criteria_direction,
+                                  abnormal_indicator = NULL,
                                   get_unit_expr,
                                   signif_dig = get_admiral_option("signif_digits")) {
   new_var <- assert_symbol(enexpr(new_var))
@@ -127,6 +136,9 @@ derive_var_atoxgr_dir <- function(dataset,
   # check input parameter has correct value
   assert_character_scalar(criteria_direction, values = c("L", "H"))
 
+  # check input parameter is character value
+  assert_character_vector(abnormal_indicator, optional = TRUE)
+
   # check input parameter holding significant digits has correct value
   assert_integer_scalar(signif_dig, subset = "positive")
 
@@ -214,6 +226,11 @@ derive_var_atoxgr_dir <- function(dataset,
       # check variables required in criteria exist on data
       assert_data_frame(grade_this_filter, required_vars = exprs(!!!syms(list_of_vars)))
 
+      if ("BNRIND" %in% list_of_vars) {
+        # check input parameter is character value
+        assert_character_vector(abnormal_indicator, optional = FALSE)
+      }
+
       # apply criteria when SI unit matches
       grade_this_filter <- grade_this_filter %>%
         mutate(

tests/testthat/test-derive_var_atoxgr.R

@@ -346,34 +346,34 @@ test_that("derive_var_atoxgr Test 11: CTCAEv4 Alanine aminotransferase increased
 test_that("derive_var_atoxgr Test 12: CTCAEv5 Alanine aminotransferase increased", {
   # V5 and V4 criteria identical when BASELINE normal
   expected_alt_ctcv5_norm <- expected_alt_ctcv4 %>%
-    # set BASE to be normal and create FLAG
+    # set BASE to be normal (not HIGH) and create FLAG
     mutate(
       BASE = ANRHI,
-      FLAG = "NORMAL"
+      BNRIND = "NORMAL"
     )
 
   # create records with baseline abnormal and apply criteria
   expected_alt_ctcv5_abn <- tibble::tribble(
-    ~ATOXDSCH, ~AVAL, ~BASE, ~AVALU, ~ATOXGRH,
-    "Not a term", 80, 40, NA_character_, NA,
-    NA_character_, 60, 40, NA_character_, NA,
-    "Alanine aminotransferase Increased", 801, 40, NA_character_, "4",
-    "Alanine aminotransferase Increased", 800, 40, NA_character_, "3",
-    "Alanine aminotransferase Increased", 201, 40, NA_character_, "3",
-    "Alanine aminotransferase Increased", 200, 40, NA_character_, "2",
-    "Alanine aminotransferase Increased", 121, 40, NA_character_, "2",
-    "Alanine aminotransferase Increased", 120, 40, NA_character_, "1",
-    "Alanine aminotransferase Increased", 60, 40, NA_character_, "1",
-    "Alanine aminotransferase Increased", 59, 40, NA_character_, "0",
+    ~ATOXDSCH,                            ~AVAL, ~BASE,        ~AVALU, ~ATOXGRH,
+    "Not a term",                            80,    40, NA_character_,       NA,
+    NA_character_,                           60,    40, NA_character_,       NA,
+    "Alanine aminotransferase Increased",   801,    40, NA_character_,      "4",
+    "Alanine aminotransferase Increased",   800,    40, NA_character_,      "3",
+    "Alanine aminotransferase Increased",   201,    40, NA_character_,      "3",
+    "Alanine aminotransferase Increased",   200,    40, NA_character_,      "2",
+    "Alanine aminotransferase Increased",   121,    40, NA_character_,      "2",
+    "Alanine aminotransferase Increased",   120,    40, NA_character_,      "1",
+    "Alanine aminotransferase Increased",    60,    40, NA_character_,      "1",
+    "Alanine aminotransferase Increased",    59,    40, NA_character_,      "0",
     # ANRHI missing - cannot grade
-    "Alanine aminotransferase Increased", 100, NA, NA_character_, NA,
+    "Alanine aminotransferase Increased",   100,    NA, NA_character_,       NA,
     # AVAL missing cannot grade
-    "Alanine aminotransferase Increased", NA, 40, NA_character_, NA,
+    "Alanine aminotransferase Increased",    NA,    40, NA_character_,       NA,
   ) %>%
-    # set BASE to be abnormal and create FLAG
+    # set BASE to be HIGH (not normal)
     mutate(
       ANRHI = BASE - 1,
-      FLAG = "ABNORMAL"
+      BNRIND = "HIGH"
     )
 
   # combine records with baseline normal and abnormal
@@ -390,13 +390,14 @@ test_that("derive_var_atoxgr Test 12: CTCAEv5 Alanine aminotransferase increased
     meta_criteria = atoxgr_criteria_ctcv5,
     tox_description_var = ATOXDSCH,
     criteria_direction = "H",
+    abnormal_indicator = "HIGH",
     get_unit_expr = AVALU
   )
 
   expect_dfs_equal(
     base = expected_alt_ctcv5,
     compare = actual_alt,
-    keys = c("ATOXDSCH", "AVAL", "ANRHI", "FLAG", "AVALU")
+    keys = c("ATOXDSCH", "AVAL", "ANRHI", "BNRIND", "AVALU")
   )
 })
 
@@ -461,7 +462,7 @@ test_that("derive_var_atoxgr Test 14: CTCAEv5 Alkaline phosphatase increased", {
     # set BASE to be normal and create FLAG
     mutate(
       BASE = ANRHI,
-      FLAG = "NORMAL"
+      BNRIND = "NORMAL"
     )
 
   # create records with baseline abnormal and apply criteria
@@ -483,10 +484,10 @@ test_that("derive_var_atoxgr Test 14: CTCAEv5 Alkaline phosphatase increased", {
     # AVAL missing cannot grade
     "Alkaline phosphatase increased",  NA,     40,     NA_character_,  NA,
   ) %>%
-    # set BASE to be abnormal and create FLAG
+    # set BASE to be abnormal (HIGH) and create FLAG
     mutate(
       ANRHI = BASE - 1,
-      FLAG = "ABNORMAL"
+      BNRIND = "HIGH"
     )
 
   # combine records with baseline normal and abnormal
@@ -502,13 +503,14 @@ test_that("derive_var_atoxgr Test 14: CTCAEv5 Alkaline phosphatase increased", {
     meta_criteria = atoxgr_criteria_ctcv5,
     tox_description_var = ATOXDSCH,
     criteria_direction = "H",
+    abnormal_indicator = "HIGH",
     get_unit_expr = AVALU
   )
 
   expect_dfs_equal(
     base = expected_alkph_ctcv5,
     compare = actual_alkph,
-    keys = c("ATOXDSCH", "AVAL", "ANRHI", "FLAG", "AVALU")
+    keys = c("ATOXDSCH", "AVAL", "ANRHI", "BNRIND", "AVALU")
   )
 })
 
@@ -572,7 +574,7 @@ test_that("derive_var_atoxgr Test 16: CTCAEv5 Aspartate aminotransferase increas
     # set BASE to be normal and create FLAG
     mutate(
       BASE = ANRHI,
-      FLAG = "NORMAL"
+      BNRIND = "NORMAL"
     )
 
   # create records with baseline abnormal and apply criteria
@@ -593,10 +595,10 @@ test_that("derive_var_atoxgr Test 16: CTCAEv5 Aspartate aminotransferase increas
     # AVAL missing cannot grade
     "Aspartate aminotransferase Increased", NA,     40,     NA_character_,  NA,
   ) %>%
-    # set BASE to be abnormal and create FLAG
+    # set BASE to be abnormal (HIGH or H)  and create FLAG
     mutate(
       ANRHI = BASE - 1,
-      FLAG = "ABNORMAL"
+      BNRIND = if_else(ATOXGRH %in% c("3", "4"), "H", "HIGH")
     )
 
   # combine records with baseline normal and abnormal
@@ -612,13 +614,14 @@ test_that("derive_var_atoxgr Test 16: CTCAEv5 Aspartate aminotransferase increas
     meta_criteria = atoxgr_criteria_ctcv5,
     tox_description_var = ATOXDSCH,
     criteria_direction = "H",
+    abnormal_indicator = c("HIGH", "H"),
     get_unit_expr = AVALU
   )
 
   expect_dfs_equal(
     base = expected_ast_ctcv5,
     compare = actual_ast,
-    keys = c("ATOXDSCH", "AVAL", "ANRHI", "FLAG", "AVALU")
+    keys = c("ATOXDSCH", "AVAL", "ANRHI", "BNRIND", "AVALU")
   )
 })
 
@@ -684,10 +687,10 @@ test_that("derive_var_atoxgr Test 17: CTCAEv4 Blood bilirubin increased", {
 test_that("derive_var_atoxgr Test 18: CTCAEv5  Blood bilirubin increased", {
   # V5 and V4 criteria identical when BASELINE normal
   expected_bili_ctcv5_norm <- expected_bili_ctcv4 %>%
-    # set BASE to be normal and create FLAG
+    # set BASE to be normal (not HIGH) and create FLAG
     mutate(
       BASE = ANRHI,
-      FLAG = "NORMAL"
+      BNRIND = "NORMAL"
     )
 
   # create records with abnormal BASE then add records with normal BASE
@@ -696,7 +699,7 @@ test_that("derive_var_atoxgr Test 18: CTCAEv5  Blood bilirubin increased", {
     mutate(
       BASE = ANRHI,
       ANRHI = ANRHI - 1,
-      FLAG = "ABNORMAL"
+      BNRIND = "HIGH"
     ) %>%
     bind_rows(expected_bili_ctcv5_norm)
 
@@ -709,13 +712,14 @@ test_that("derive_var_atoxgr Test 18: CTCAEv5  Blood bilirubin increased", {
     meta_criteria = atoxgr_criteria_ctcv5,
     tox_description_var = ATOXDSCH,
     criteria_direction = "H",
+    abnormal_indicator = "HIGH",
     get_unit_expr = AVALU
   )
 
   expect_dfs_equal(
     base = expected_bili_ctcv5,
     compare = actual_bili,
-    keys = c("ATOXDSCH", "AVAL", "ANRHI", "FLAG", "AVALU")
+    keys = c("ATOXDSCH", "AVAL", "ANRHI", "BNRIND", "AVALU")
   )
 })
 
@@ -1241,10 +1245,10 @@ test_that("derive_var_atoxgr Test 29: CTCAEv4 GGT increased", {
 test_that("derive_var_atoxgr Test 30: CTCAEv5 GGT increased", {
   # V5 and V4 criteria identical when BASELINE normal
   expected_ggt_ctcv5_norm <- expected_ggt_ctcv4 %>%
-    # set BASE to be normal and create FLAG
+    # set BASE to be normal (not HIGH) and create FLAG
     mutate(
       BASE = ANRHI,
-      FLAG = "NORMAL"
+      BNRIND = "NORMAL"
     )
 
   # create records with baseline abnormal and apply criteria
@@ -1265,10 +1269,11 @@ test_that("derive_var_atoxgr Test 30: CTCAEv5 GGT increased", {
     # AVAL missing cannot grade
     "GGT increased", NA,    0,      NA,     NA_character_, NA,
   ) %>%
-    # set BASE to be abnormal and create FLAG
+    # set BASE to be abnormal (HIGH HIGH) and create FLAG
+    # set abnormal_indicator to "HIGH HIGH" also in function call
     mutate(
       ANRHI = BASE - 1,
-      FLAG = "ABNORMAL"
+      BNRIND = "HIGH HIGH"
     )
 
   # combine records with baseline normal and abnormal
@@ -1284,13 +1289,14 @@ test_that("derive_var_atoxgr Test 30: CTCAEv5 GGT increased", {
     meta_criteria = atoxgr_criteria_ctcv5,
     tox_description_var = ATOXDSCH,
     criteria_direction = "H",
+    abnormal_indicator = "HIGH HIGH",
     get_unit_expr = AVALU
   )
 
   expect_dfs_equal(
     base = expected_ggt_ctcv5,
     compare = actual_ggt,
-    keys = c("ATOXDSCH", "AVAL", "ANRLO", "ANRHI", "FLAG", "AVALU")
+    keys = c("ATOXDSCH", "AVAL", "ANRLO", "ANRHI", "BNRIND", "AVALU")
   )
 })
 

vignettes/lab_grading.Rmd

@@ -558,9 +558,14 @@ atoxgr_criteria_ctcv5 %>%
 
 For terms "Alanine aminotransferase increased", "Alkaline phosphatase increased",
 "Aspartate aminotransferase increased", "Blood bilirubin increased" and "GGT increased" the criteria
-is dependent on the Baseline Value `BASE` being normal or abnormal. For `BASE` to be abnormal we compare
-it with the Upper Limit of Normal (ULN) `ANRHI`, i.e. `BASE > ANRHI`.
-This means if `BASE` is abnormal then the grade is always zero for the baseline observation.
+is dependent on the Baseline Value being normal or abnormal. We use the variable `BNRIND` to determine
+this, and users can pass in the value(s) of `BNRIND` that indicate the baseline is abnormal via the argument
+`abnormal_indicator` in the function `derive_var_atoxgr_dir()`.
+For example, setting `abnormal_indicator = "HIGH"` would mean any observations with `BNRIND = "HIGH"` would
+be deemed to have an abnormal Baseline Value.
+Note: you can pass in multiple values, `abnormal_indicator = c("H", "HIGH")`
+
+For these 5 terms, this means if `BNRIND` is abnormal then the grade is always zero for the baseline observation.
 
 For term "INR Increased" there is the following criteria: