Merge pull request #880 from Gilead-BioStats/release-v1.3.1

Release v1.3.1

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: gsm
 Title: Gilead Statistical Monitoring
-Version: 1.3.0
+Version: 1.3.1
 Authors@R: c(
     person("George", "Wu", email="george.wu@gilead.com", role = c("aut", "cre")),
     person("Jeremy", "Wildfire", email="jwildfire@gmail.com", role = c("aut")),

NAMESPACE

@@ -23,6 +23,7 @@ export(Flag)
 export(Flag_Fisher)
 export(Flag_NormalApprox)
 export(Flag_Poisson)
+export(Flag_QTL)
 export(Get_Enrolled)
 export(IE_Assess)
 export(IE_Map_Raw)
@@ -64,6 +65,7 @@ importFrom(DiagrammeR,create_node_df)
 importFrom(DiagrammeR,render_graph)
 importFrom(broom,augment)
 importFrom(broom,glance)
+importFrom(cli,cli_alert)
 importFrom(cli,cli_alert_danger)
 importFrom(cli,cli_alert_info)
 importFrom(cli,cli_alert_success)

NEWS.md

@@ -1,3 +1,7 @@
+# gsm v1.3.1
+
+This minor release adds a data frame to the output/data model of `Make_Snapshot()` that includes parameters and values for QTL analyses. 
+
 # gsm v1.3.0
 
 This release introduces new and refined statistical methods for qualified assessments. 

R/AE_Assess.R

@@ -17,9 +17,6 @@
 #'   - `"NormalApprox"` (default)
 #'   - `"poisson"`
 #'   - `"identity"`
-#' @param strType `character` Statistical outcome type. Valid values:
-#'   - `"binary"`
-#'   - `"rate"` (default)
 #' @param lMapping Column metadata with structure `domain$key`, where `key` contains the name
 #'   of the column. Default: package-defined Adverse Event Assessment mapping.
 #' @param strGroup `character` Grouping variable. `"Site"` (the default) uses the column named in `mapping$strSiteCol`.
@@ -70,7 +67,6 @@ AE_Assess <- function(
   dfInput,
   vThreshold = NULL,
   strMethod = "NormalApprox",
-  strType = "rate",
   lMapping = yaml::read_yaml(system.file("mappings", "AE_Assess.yaml", package = "gsm")),
   strGroup = "Site",
   bQuiet = TRUE
@@ -135,14 +131,14 @@ AE_Assess <- function(
     if (strMethod == "NormalApprox") {
       lData$dfAnalyzed <- gsm::Analyze_NormalApprox(
         dfTransformed = lData$dfTransformed,
-        strType = strType,
+        strType = "rate",
         bQuiet = bQuiet
       )
 
       lData$dfBounds <- gsm::Analyze_NormalApprox_PredictBounds(
         dfTransformed = lData$dfTransformed,
         vThreshold = vThreshold,
-        strType = strType,
+        strType = "rate",
         bQuiet = bQuiet
       )
     } else if (strMethod == "poisson") {

R/Analyze_NormalApprox_PredictBounds.R

@@ -52,21 +52,38 @@
 #' dfAnalyzed <- Analyze_NormalApprox(dfTransformed, strType = "rate")
 #' dfBounds <- Analyze_NormalApprox_PredictBounds(dfTransformed, c(-3, -2, 2, 3), strType = "rate")
 #'
+#' @importFrom cli cli_alert
 #' @import dplyr
 #' @importFrom tidyr expand_grid
 #'
 #' @export
 
 Analyze_NormalApprox_PredictBounds <- function(
-  dfTransformed,
-  vThreshold = c(-3, -2, 2, 3),
-  nStep = 1,
-  strType = "binary",
-  bQuiet = TRUE
+    dfTransformed,
+    vThreshold = c(-3, -2, 2, 3),
+    strType = "binary",
+    nStep = NULL,
+    bQuiet = TRUE
 ) {
   if (is.null(vThreshold)) {
     vThreshold <- c(-3, -2, 2, 3)
-    cli::cli_alert("vThreshold was not provided. Setting default threshold to c(-3, -2, 2, 3)")
+    if (bQuiet == FALSE)
+      cli::cli_alert("vThreshold was not provided. Setting default threshold to {vThreshold}")
+  }
+
+  # Set [ nStep ] to the range of the denominator divided by 250.
+  if (is.null(nStep)) {
+    nMinDenominator <- min(dfTransformed$Denominator)
+    nMaxDenominator <- max(dfTransformed$Denominator)
+    nRange <- nMaxDenominator - nMinDenominator
+
+    if (!is.null(nRange) & !is.na(nRange) & nRange != 0)
+        nStep <- nRange/250
+    else
+        nStep <- 1
+
+    if (bQuiet == FALSE)
+      cli::cli_alert("nStep was not provided. Setting default step to {nStep}")
   }
 
   # add a 0 threhsold to calcultate estimate without an offset
@@ -81,6 +98,7 @@ Analyze_NormalApprox_PredictBounds <- function(
 
   if (strType == "binary") {
     dfBounds <- tidyr::expand_grid(Threshold = vThreshold, Denominator = vRange) %>%
+      filter(.data$Denominator > 0) %>%
       mutate(
         LogDenominator = log(.data$Denominator),
         # Calculate expected event percentage at sample size.
@@ -102,6 +120,7 @@ Analyze_NormalApprox_PredictBounds <- function(
       )
   } else if (strType == "rate") {
     dfBounds <- tidyr::expand_grid(Threshold = vThreshold, Denominator = vRange) %>%
+      filter(.data$Denominator > 0) %>%
       mutate(
         LogDenominator = log(.data$Denominator),
         # Calculate expected rate at given exposure.

R/Analyze_Poisson_PredictBounds.R

@@ -39,6 +39,7 @@
 #'
 #' dfBounds <- Analyze_Poisson_PredictBounds(dfTransformed, c(-5, 5))
 #'
+#' @importFrom cli cli_alert
 #' @importFrom lamW lambertWm1 lambertW0
 #' @importFrom stats glm offset poisson qchisq
 #' @importFrom tibble tibble
@@ -47,14 +48,16 @@
 #' @export
 
 Analyze_Poisson_PredictBounds <- function(
-  dfTransformed,
-  vThreshold = c(-5, 5),
-  nStep = 1,
-  bQuiet = TRUE
+    dfTransformed,
+    vThreshold = c(-5, 5),
+    nStep = NULL,
+    bQuiet = TRUE
 ) {
   if (is.null(vThreshold)) {
     vThreshold <- c(-5, 5)
-    cli::cli_alert("vThreshold was not provided. Setting default threshold to c(-5, 5)")
+
+    if (bQuiet == FALSE)
+      cli::cli_alert("vThreshold was not provided. Setting default threshold to c(-5, 5)")
   }
 
   # add a 0 threhsold to calcultate estimate without an offset
@@ -65,6 +68,21 @@ Analyze_Poisson_PredictBounds <- function(
     dfTransformed$Denominator
   )
 
+  # Set [ nStep ] to the range of the log denominator divided by 250.
+  if (is.null(nStep)) {
+    nMinLogDenominator <- min(dfTransformed$LogDenominator)
+    nMaxLogDenominator <- max(dfTransformed$LogDenominator)
+    nRange <- nMaxLogDenominator - nMinLogDenominator
+
+    if (!is.null(nRange) & !is.na(nRange) & nRange != 0)
+        nStep <- nRange/250
+    else
+        nStep <- .05
+
+    if (bQuiet == FALSE)
+      cli::cli_alert("nStep was not provided. Setting default step to {nStep}")
+  }
+
   # Fit GLM of number of events at each site predicted by total exposure.
   cModel <- glm(
     Numerator ~ stats::offset(LogDenominator),

R/Analyze_QTL.R

@@ -36,7 +36,7 @@
 #' )
 #'
 #' dfAnalyzed <- Analyze_QTL(dfTransformed, strOutcome = "binary")
-#' dfFlagged <- Flag(dfAnalyzed, strColumn = "LowCI", vThreshold = c(NA, 0.2))
+#' dfFlagged <- Flag_QTL(dfAnalyzed, vThreshold = 0.2)
 #'
 #'
 #'
@@ -48,7 +48,7 @@
 #' )
 #'
 #' dfAnalyzed <- Analyze_QTL(dfTransformed, strOutcome = "rate")
-#' dfFlagged <- Flag(dfAnalyzed, vThreshold = c(NA, 0.01))
+#' dfFlagged <- Flag_QTL(dfAnalyzed, vThreshold = 0.01)
 #'
 #' @import dplyr
 #' @importFrom stats binom.test poisson.test

R/Disp_Assess.R

@@ -16,9 +16,6 @@
 #'   - `"NormalApprox"` (default)
 #'   - `"fisher"`
 #'   - `"identity"`
-#' @param strType `character` Statistical outcome type. Valid values:
-#'   - `"binary"` (default)
-#'   - `"rate"`
 #' @param lMapping `list` Column metadata with structure `domain$key`, where `key` contains the name
 #'   of the column. Default: package-defined Disposition Assessment mapping.
 #' @param strGroup `character` Grouping variable. `"Site"` (the default) uses the column named in `mapping$strSiteCol`. Other valid options using the default mapping are `"Study"` and `"CustomGroup"`.
@@ -62,7 +59,6 @@ Disp_Assess <- function(
   dfInput,
   vThreshold = NULL,
   strMethod = "NormalApprox",
-  strType = "binary",
   lMapping = yaml::read_yaml(system.file("mappings", "Disp_Assess.yaml", package = "gsm")),
   strGroup = "Site",
   nConfLevel = NULL,
@@ -94,7 +90,7 @@ Disp_Assess <- function(
       NormalApprox = c(-3, -2, 2, 3),
       fisher = c(0.01, 0.05),
       identity = c(3.491, 5.172),
-      qtl = c(0, 0.2)
+      qtl = c(0.2)
     )
   }
 
@@ -131,14 +127,14 @@ Disp_Assess <- function(
     if (strMethod == "NormalApprox") {
       lData$dfAnalyzed <- gsm::Analyze_NormalApprox(
         dfTransformed = lData$dfTransformed,
-        strType = strType,
+        strType = "binary",
         bQuiet = bQuiet
       )
 
       lData$dfBounds <- gsm::Analyze_NormalApprox_PredictBounds(
         dfTransformed = lData$dfTransformed,
         vThreshold = vThreshold,
-        strType = strType,
+        strType = "binary",
         bQuiet = bQuiet
       )
     } else if (strMethod == "fisher") {
@@ -160,14 +156,14 @@ Disp_Assess <- function(
     } else if (strMethod == "identity") {
       lData$dfFlagged <- gsm::Flag(lData$dfAnalyzed, vThreshold = vThreshold, strValueColumn = strValueColumnVal)
     } else if (strMethod == "qtl") {
-      lData$dfFlagged <- gsm::Flag(lData$dfAnalyzed, vThreshold = vThreshold)
+      lData$dfFlagged <- gsm::Flag_QTL(lData$dfAnalyzed, vThreshold = vThreshold)
     }
 
     flag_function_name <- switch(strMethod,
       NormalApprox = "Flag_NormalApprox",
       identity = "Flag",
       fisher = "Flag_Fisher",
-      qtl = "Flag"
+      qtl = "Flag_QTL"
     )
 
     if (!bQuiet) cli::cli_alert_success("{.fn {flag_function_name}} returned output with {nrow(lData$dfFlagged)} rows.")

R/Flag_QTL.R

@@ -0,0 +1,57 @@
+#' Flag QTL
+#'
+#' @details
+#' This function flags a study-level QTL metric by comparing the mean and lower confidence bound for the metric to a single threhsold.
+#'
+#' @section Data Specification:
+#' \code{Flag_NormalApprox} is designed to support the input data (`dfAnalyzed`) from \code{Analyze_QTL} function.
+#' At a minimum, the input data must have numeric `Score` and `LowCI` columns that will be compared to the specified threshold (`vThreshold`) to
+#' calculate a new `Flag` column.
+#'
+#' @param dfAnalyzed data.frame where flags should be added.
+#' @param vThreshold Numeric value representing the threshold. NA and NaN values in strColumn are given NA flag values.
+#'
+#' @return `data.frame` with "Flag" column added
+#'
+#' @examples
+#' dfInput <- Disp_Map_Raw()
+#' dfTransformed <- Transform_Rate(
+#'   dfInput,
+#'   strGroupCol = "StudyID",
+#'   strNumeratorCol = "Count",
+#'   strDenominatorCol = "Total"
+#' )
+#' dfAnalyzed <- Analyze_QTL(dfTransformed)
+#' dfFlagged <- Flag_QTL(dfAnalyzed, vThreshold = 0.02)
+#'
+#' @import dplyr
+#'
+#' @export
+
+Flag_QTL <- function(
+  dfAnalyzed,
+  vThreshold = NULL
+) {
+  stopifnot(
+    "dfAnalyzed is not a data frame" = is.data.frame(dfAnalyzed),
+    "Required columns not found" = all(c("Estimate", "LowCI") %in% names(dfAnalyzed)),
+    "vThreshold is not numeric" = is.numeric(vThreshold),
+    "vThreshold must be length of 1" = length(vThreshold) == 1,
+    "vThreshold cannot be NULL" = !is.null(vThreshold)
+  )
+
+  # Flag values outside the specified threshold.
+  dfFlagged <- dfAnalyzed %>%
+    mutate(
+      Flag = case_when(
+        (.data$LowCI > vThreshold) ~ 2,
+        (.data$Estimate > vThreshold) ~ 1,
+        TRUE ~ 0
+      )
+    )
+
+  dfFlagged <- dfFlagged %>%
+    arrange(match(.data$Flag, c(2, 1, 0)))
+
+  return(dfFlagged)
+}

R/LB_Assess.R

@@ -16,9 +16,6 @@
 #'   - `"NormalApprox"` (default)
 #'   - `"fisher"`
 #'   - `"identity"`
-#' @param strType `character` Statistical outcome type. Valid values:
-#'   - `"binary"` (default)
-#'   - `"rate"`
 #' @param lMapping `list` Column metadata with structure `domain$key`, where `key` contains the name
 #'   of the column. Default: package-defined Labs Assessment mapping.
 #' @param strGroup `character` Grouping variable. `"Site"` (the default) uses the column named in `mapping$strSiteCol`. Other valid options using the default mapping are `"Study"` and `"CustomGroup"`.
@@ -61,7 +58,6 @@ LB_Assess <- function(
   dfInput,
   vThreshold = NULL,
   strMethod = "NormalApprox",
-  strType = "binary",
   lMapping = yaml::read_yaml(system.file("mappings", "LB_Assess.yaml", package = "gsm")),
   strGroup = "Site",
   bQuiet = TRUE
@@ -127,14 +123,14 @@ LB_Assess <- function(
     if (strMethod == "NormalApprox") {
       lData$dfAnalyzed <- gsm::Analyze_NormalApprox(
         dfTransformed = lData$dfTransformed,
-        strType = strType,
+        strType = "binary",
         bQuiet = bQuiet
       )
 
       lData$dfBounds <- gsm::Analyze_NormalApprox_PredictBounds(
         dfTransformed = lData$dfTransformed,
         vThreshold = vThreshold,
-        strType = strType,
+        strType = "binary",
         bQuiet = bQuiet
       )
     } else if (strMethod == "fisher") {