#2468 derive_vars_crit_flag: update templates and vignettes

NEWS.md

@@ -489,7 +489,7 @@ dates updated (#2028)
 
 ## Various
 
-- The list of package authors/contributors has been reformatted so that those who are actively maintaining the code base are now marked as *authors*, whereas those who made a significant contribution in the past are now down as *contributors*. All other acknowledgements have been moved to README section (#1941).
+- The list of package authors/contributors has been reformatted so that those who are actively maintaining the code base are now marked as *authors*, whereas those who made a significant contribution in the past are now down as *contributors*. All other acknowledgments have been moved to README section (#1941).
 
 - `derive_vars_joined()` had two bugs with regards to duplicates messaging and when `new_vars` was set to `NULL` that have now been addressed (#1966). 
 

R/user_helpers.R

@@ -1,19 +1,19 @@
 #' Open an ADaM Template Script
 #'
-#' @param adam_name An ADaM dataset name. You can use any of the available dataset name
-#' `r list_all_templates()`, and the dataset name is case-insensitive. The default dataset
-#' name is ADSL.
+#' @param adam_name An ADaM dataset name. You can use any of the available
+#'   dataset names
+#'   `r map_chr(list_all_templates(), ~ paste0("\\code{\"", .x, "\"}"))`.
+#'   The dataset name is case-insensitive. The default dataset name is `"ADSL"`.
 #' @param save_path Path to save the script.
 #' @param package The R package in which to look for templates. By default `"admiral"`.
 #' @param overwrite Whether to overwrite an existing file named `save_path`.
 #' @param open Whether to open the script right away.
 #'
 #' @return No return values, called for side effects
 #'
-#' @details Running without any arguments such as `use_ad_template()` auto-generates adsl.R in
+#' @details Running without any arguments such as `use_ad_template()` auto-generates `adsl.R` in
 #' the current path. Use `list_all_templates()` to discover which templates are available.
 #'
-#'
 #' @family utils_examples
 #' @keywords utils_examples
 #'

inst/WORDLIST

@@ -4,7 +4,6 @@ ADEG
 ADEX
 ADJAE
 ADLB
-ADLBHY
 ADMH
 ADNCA
 ADPC
@@ -37,7 +36,6 @@ Alanine
 Alkalosis
 Analyte
 Ania
-Asha
 Aspartate
 BDS
 BILI
@@ -61,7 +59,6 @@ CTCAEV
 CTCAEv
 CVD
 Carlucci
-Chakma
 Cheatsheet
 Chemistries
 Chol
@@ -96,7 +93,6 @@ Fibrinogen
 Findability
 Framingham
 Franciszek
-Francois
 Fridericia
 Fridericia's
 Fujimoto
@@ -240,14 +236,12 @@ ULN
 USUBJID
 USUBJIDs
 Upadhyay
-VAD
 Vignesh
 WBC
 Walkowiak
 Wenyi
 XXXXXXXX
 Yohann
-acknowledgements
 admiralci
 admiraldev
 admiralonco

inst/templates/ad_adlbhy.R

@@ -22,24 +22,24 @@ adlb <- admiral_adlb
 
 adlb_annotated <- adlb %>%
   filter(PARAMCD %in% c("AST", "ALT", "BILI") & is.na(DTYPE)) %>%
-  mutate(CRIT1 = case_when(
-    PARAMCD == "AST" ~ "AST >=3xULN",
-    PARAMCD == "ALT" ~ "ALT >=3xULN",
-    PARAMCD == "BILI" ~ "BILI >=2xULN"
-  )) %>%
   # Assign flags for contribution to potential Hy's Law event
-  call_derivation(
-    .,
-    derivation = derive_var_merged_exist_flag,
-    dataset_add = .,
-    by_vars = exprs(USUBJID, LBSEQ, PARAMCD, ADT),
-    variable_params = list(
-      params(
-        new_var = CRIT1FL,
-        condition = (
-          (AVAL / ANRHI >= 3 & PARAMCD %in% c("AST", "ALT")) |
-            (AVAL / ANRHI >= 2 & PARAMCD == "BILI")
-        )
+  slice_derivation(
+    derive_vars_crit_flag,
+    args = params(
+      values_yn = TRUE
+    ),
+    derivation_slice(
+      filter = PARAMCD %in% c("AST", "ALT"),
+      args = params(
+        condition = AVAL / ANRHI >= 3,
+        description = paste(PARAMCD, ">=3xULN")
+      )
+    ),
+    derivation_slice(
+      filter = PARAMCD == "BILI",
+      args = params(
+        condition = AVAL / ANRHI >= 2,
+        description = "BILI >= 2xULN"
       )
     )
   ) %>%
@@ -52,14 +52,14 @@ altast_records <- adlb_annotated %>%
 bili_records <- adlb_annotated %>%
   filter(PARAMCD %in% c("BILI"))
 
-# Use a join and filter to accomplish time-window search
+# Flag elevated AST/ALT values with a BILI elevation within 14 days
 hylaw_records <- derive_vars_joined(
   dataset = altast_records,
   dataset_add = bili_records,
   by_vars = exprs(STUDYID, USUBJID),
   order = exprs(ADY),
   join_type = "all",
-  filter_join = ADT.join - ADT <= 14 & CRIT1FL == "Y" & CRIT1FL.join == "Y",
+  filter_join = 0 <= ADT.join - ADT & ADT.join - ADT <= 14 & CRIT1FL == "Y" & CRIT1FL.join == "Y",
   new_vars = exprs(BILI_LBSEQ = LBSEQ, BILI_DT = ADT, BILI_CRITFL = CRIT1FL),
   mode = "first"
 )

vignettes/hys_law.Rmd

@@ -45,11 +45,11 @@ library(dplyr, warn.conflicts = FALSE)
 
 We assume that an `ADLB` dataset is available [^1].
 
-[^1]: In the walk through below we will use the ADLB dataset created from the call `use_ad_template("adlb")`. Due to the size of the dataset, we only included the following USUBJIDs: 
+[^1]: In the walk through below we will use the `ADLB` dataset created from the call `use_ad_template("adlb")`. Due to the size of the dataset, we only included the following `USUBJID`s: 
 
     * `01-701-1015`, `01-701-1023`, `01-701-1028`, `01-701-1033`, `01-701-1034`, `01-701-1047`, `01-701-1097`, `01-705-1186`, `01-705-1292`, `01-705-1310`, `01-708-1286`.
 
-First we read in the ADLB parameters required for the Hy's Law parameters:
+First we read in the `ADLB` parameters required for the Hy's Law parameters:
 
 ```{r, eval = TRUE}
 data(admiral_adlb)
@@ -65,32 +65,42 @@ head(adlb) %>%
 
 ## Flagging Elevated Values (`CRITy`, `CRITyFL`) {#columns}
 
-A standard convention of ADLBHY datasets, are various `CRITy` and `CRITyFL` columns to describe the conditions necessary to reach that particular criterion of Hy's Law and the actual flag itself to indicate whether or not the condition was reached.
+A standard convention of `ADLBHY` datasets, are various `CRITy` and `CRITyFL` columns to describe the conditions necessary to reach that particular criterion of Hy's Law and the actual flag itself to indicate whether or not the condition was reached.
 
 Using `mutate()`, `call_derivation()` and `derive_var_merged_exist_flag()`, we can create these columns that indicate the the 3-fold or greater than upper limit of normal of ALT/AST and the 2-fold or greater than upper limit of normal of BILI.
 
 To increase visibility and for simplicity, we will retain only columns that are relevant to a Hy's Law analysis for now. 
 
 ```{r}
 adlb_annotated <- adlb %>%
-  mutate(
-    CRIT1 = case_when(
-      PARAMCD == "AST" ~ "AST >=3xULN",
-      PARAMCD == "ALT" ~ "ALT >=3xULN",
-      PARAMCD == "BILI" ~ "BILI >=2xULN"
+  slice_derivation(
+    derive_vars_crit_flag,
+    args = params(
+      values_yn = TRUE
     ),
-    CRIT1FL = if_else(
-      (AVAL / ANRHI >= 3 & PARAMCD %in% c("AST", "ALT")) |
-        (AVAL / ANRHI >= 2 & PARAMCD == "BILI"),
-      "Y",
-      NA_character_
+    derivation_slice(
+      filter = PARAMCD %in% c("AST", "ALT"),
+      args = params(
+        condition = AVAL / ANRHI >= 3,
+        description = paste(PARAMCD, ">=3xULN")
+      )
+    ),
+    derivation_slice(
+      filter = PARAMCD == "BILI",
+      args = params(
+        condition = AVAL / ANRHI >= 2,
+        description = "BILI >= 2xULN"
+      )
     )
   ) %>%
   select(STUDYID, USUBJID, TRT01A, PARAMCD, LBSEQ, ADT, AVISIT, ADY, AVAL, ANRHI, CRIT1, CRIT1FL)
 ```
 
 ```{r, echo = FALSE}
-dataset_vignette(adlb_annotated)
+dataset_vignette(
+  adlb_annotated,
+  display_vars = exprs(USUBJID, PARAMCD, AVISIT, AVAL, ANRHI, CRIT1, CRIT1FL)
+)
 ```
 
 
@@ -125,7 +135,7 @@ hylaw_records <- derive_vars_joined(
 ```{r, echo = FALSE}
 hylaw_records %>%
   arrange(desc(BILI_CRITFL), desc(CRIT1FL)) %>%
-  dataset_vignette()
+  dataset_vignette(display_vars = exprs(USUBJID, PARAMCD, AVISIT, ADT, CRIT1FL, BILI_DT, BILI_CRITFL))
 ```
 
 
@@ -166,7 +176,8 @@ hylaw_params <- derive_param_exist_flag(
 ```{r, echo = FALSE}
 hylaw_params %>%
   arrange(desc(AVAL)) %>%
-  dataset_vignette()
+  relocate(AVALC, .before = AVAL) %>% 
+  dataset_vignette(display_vars = exprs(USUBJID, PARAMCD, PARAM, AVALC, AVAL))
 ```
 
 
@@ -180,7 +191,9 @@ adlbhy <- adlb_annotated %>%
 ```
 
 ```{r, echo = FALSE}
-dataset_vignette(adlbhy)
+dataset_vignette(
+  adlbhy %>% relocate(AVALC, .before = AVAL),
+  display_vars = exprs(USUBJID, PARAMCD, AVISIT, AVALC, AVAL, CRIT1, CRIT1FL))
 ```
 
 Here we demonstrated what is the base-case that may be asked of as a trial programmer. The reality is that Hy's Law and assessing potential DILI events can get rather complex quite quickly. Differences in assessment across organizations and specific trials might require modifications, which may include:
@@ -191,11 +204,11 @@ Here we demonstrated what is the base-case that may be asked of as a trial progr
  - different criteria cutoffs that depend on baseline values or characteristics
  - other parameters such as worsening of condition
 
-We hope by demonstrating the flexibility of `admiral` functions and using a general workflow to create the necessary parameters for an ADLBHY, that creating this final dataset becomes simplified and easily scalable. Ideally, this is ready for your organization's standard macros or previous code for TLFs and outputs as well. This is our first attempt at breaking down and summarizing this topic. We welcome feedback and ideas to improve this guide!
+We hope by demonstrating the flexibility of `admiral` functions and using a general workflow to create the necessary parameters for an `ADLBHY`, that creating this final dataset becomes simplified and easily scalable. Ideally, this is ready for your organization's standard macros or previous code for TLFs and outputs as well. This is our first attempt at breaking down and summarizing this topic. We welcome feedback and ideas to improve this guide!
 
 # Example Script 
 
-ADaM   | Sourcing Command
------- | --------------
-ADLBHY | `use_ad_template("ADLBHY")`
+ADaM     | Sourcing Command
+------   | --------------
+`ADLBHY` | `use_ad_template("ADLBHY")`
 

vignettes/lab_grading.Rmd

@@ -89,9 +89,9 @@ both side of the equation, the number of significant digits used to compare is p
 function `derive_var_atoxgr_dir()` via the argument `signif_dig`. Please see documentation of the 
 function for more details and the blog post [How admiral handles floating points](https://pharmaverse.github.io/blog/posts/2023-10-30_floating_point/floating_point.html) for more context.
 
-# Creating the lab grade
+# Creating the Lab Grade
 
-## Mapping ADLB VAD to the TERM variable in the `{admiral}` metadata data set
+## Mapping `ADLB` to the `TERM` variable in the `{admiral}` metadata data set
 
 
 ```{r message=FALSE}
@@ -339,7 +339,7 @@ adlb %>%
 ## Terms graded
 
 Grading is implemented for those lab tests where a lab value is included in the grading definition,
-`{admiral}` does NOT try to read any other data to determine the grade, and only the ADLB VAD is used.
+`{admiral}` does NOT try to read any other data to determine the grade, and only the `ADLB` dataset is used.
 The following CTCAE v4.0 SOC values were identified for grading, these are "Investigations", 
 "Metabolism and nutrition disorders" and "Blood and lymphatic system disorders".
 
@@ -481,7 +481,7 @@ atoxgr_criteria_ctcv4 %>%
 ## Terms graded
 
 Grading is implemented for those lab tests where a lab value is included in the grading definition,
-`{admiral}` does NOT try to read any other data to determine the grade, and only the ADLB VAD is used.
+`{admiral}` does NOT try to read any other data to determine the grade, and only the `ADLB` dataset is used.
 The following CTCAE v5.0 SOC values were identified for grading, these are “Investigations", 
 “Metabolism and nutrition disorders” and “Blood and lymphatic system disorders”.
 
@@ -646,7 +646,7 @@ atoxgr_criteria_ctcv5 %>%
 ## Terms graded
 
 Grading is implemented for those lab tests where a lab value is included in the grading definition,
-`{admiral}` does NOT try to read any other data to determine the grade, and only the ADLB VAD is used.
+`{admiral}` does NOT try to read any other data to determine the grade, and only the `ADLB` dataset is used.
 The following DAIDS SOC values were identified for grading, these are "Chemistries" and 
 "Hematology".