From 66ac3ea59f3b0933a3cd9c3dbc5d5174c528419c Mon Sep 17 00:00:00 2001 From: Adam Howes Date: Wed, 11 Dec 2024 13:40:06 +0000 Subject: [PATCH] Language clarification in `extract_diagnostics` (#109) * Language clarification in `extract_diagnostics` Clarified: * "These diagnostics are then flagged if they exceed specific thresholds" makes it sound like the returned dataframe flags each __individually__ (which it doesn't, hence suggest change of language) * "Exceed specific thresholds": sometimes it's if the value is below a threshold hence I suggest reword to "outside acceptable range" Possible refactors / improvements of this function could be:
1. Return a flag for each diagnostic rather than for all of them jointly. Would it ever be useful to know in particular which diagnostic was violated (straight away, I know it could be recovered with some digging) 2. Allowing setting of the thresholds. As a user I imagine this might be useful, like if certain conditions mean that diagnostics are over or under flagging. I can see here it's a bit annoying to do and would probably have to be like a user input list of named values. * Redocument --- R/extract_diagnostics.R | 10 +++++----- man/Exclusions.Rd | 2 +- man/extract_diagnostics.Rd | 10 +++++----- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/R/extract_diagnostics.R b/R/extract_diagnostics.R index f0bd4595..6c90525d 100644 --- a/R/extract_diagnostics.R +++ b/R/extract_diagnostics.R @@ -4,8 +4,8 @@ #' model and provided data. It checks for low case counts and computes #' diagnostics from the fitted model, including the mean acceptance #' statistic, divergent transitions, maximum tree depth, and Rhat values. -#' These diagnostics are then flagged if they exceed specific thresholds, -#' and the results are returned as a data frame. +#' Additionally, a combined flag is computed indicating if any diagnostics +#' are outside an acceptable range. The results are returned as a data frame. #' #' @param fit The model fit object from `EpiNow2` #' @param data A data frame containing the input data used in the model fit. @@ -42,9 +42,9 @@ #' counts in the data. See \code{low_case_count_diagnostic()} for more #' information on this diagnostic. #' \item \code{epinow2_diagnostic_flag}: A combined flag that indicates if -#' any diagnostic thresholds are exceeded. The diagnostic thresholds -#' (1) mean_accept_stat < 0.1, (2) p_divergent > 0.0075, (3) -#' p_max_treedepth > 0.05, and (4) p_high_rhat > 0.0075. +#' any diagnostic metrics are outside an accepted range, as determined +#' by the thresholds: (1) mean_accept_stat < 0.1, (2) p_divergent > +#' 0.0075, (3) p_max_treedepth > 0.05, and (4) p_high_rhat > 0.0075. #' } #' @export extract_diagnostics <- function(fit, diff --git a/man/Exclusions.Rd b/man/Exclusions.Rd index d58cc132..2b9e2e2e 100644 --- a/man/Exclusions.Rd +++ b/man/Exclusions.Rd @@ -9,7 +9,7 @@ Exclusions(path = character(0), blob_storage_container = character(0)) \arguments{ \item{path}{A string specifying the path to a CSV file containing exclusion data. It should include at least the columns: \code{reference_date}, -\code{report_date}, ' \code{state_abb}, \code{disease}.} +\code{report_date}, \code{state_abb}, \code{disease}.} \item{blob_storage_container}{Optional. The name of the blob storage container to get it from. If NULL, will look locally.} diff --git a/man/extract_diagnostics.Rd b/man/extract_diagnostics.Rd index 5eb2e006..9ec84fb5 100644 --- a/man/extract_diagnostics.Rd +++ b/man/extract_diagnostics.Rd @@ -33,8 +33,8 @@ This function extracts various diagnostic metrics from a fitted \code{EpiNow2} model and provided data. It checks for low case counts and computes diagnostics from the fitted model, including the mean acceptance statistic, divergent transitions, maximum tree depth, and Rhat values. -These diagnostics are then flagged if they exceed specific thresholds, -and the results are returned as a data frame. +Additionally, a combined flag is computed indicating if any diagnostics +are outside an acceptable range. The results are returned as a data frame. } \details{ The following diagnostics are calculated: @@ -55,8 +55,8 @@ greater than 1.05, indicating potential convergence issues. counts in the data. See \code{low_case_count_diagnostic()} for more information on this diagnostic. \item \code{epinow2_diagnostic_flag}: A combined flag that indicates if -any diagnostic thresholds are exceeded. The diagnostic thresholds -(1) mean_accept_stat < 0.1, (2) p_divergent > 0.0075, (3) -p_max_treedepth > 0.05, and (4) p_high_rhat > 0.0075. +any diagnostic metrics are outside an accepted range, as determined +by the thresholds: (1) mean_accept_stat < 0.1, (2) p_divergent > +0.0075, (3) p_max_treedepth > 0.05, and (4) p_high_rhat > 0.0075. } }