Add message if user doesn't change extrapolation_factor default

Author: jgabry

R/ppc-censoring.R

@@ -24,11 +24,12 @@
 #' @section Plot Descriptions:
 #' \describe{
 #'   \item{`ppc_km_overlay()`}{
-#'    Empirical CCDF estimates of each dataset (row) in `yrep` are overlaid,
-#'    with the Kaplan-Meier estimate (Kaplan and Meier, 1958) for `y` itself on
-#'    top (and in a darker shade). This is a PPC suitable for right-censored
-#'    `y`. Note that the replicated data from `yrep` is assumed to be
-#'    uncensored.
+#'   Empirical CCDF estimates of each dataset (row) in `yrep` are overlaid, with
+#'   the Kaplan-Meier estimate (Kaplan and Meier, 1958) for `y` itself on top
+#'   (and in a darker shade). This is a PPC suitable for right-censored `y`.
+#'   Note that the replicated data from `yrep` is assumed to be uncensored. Left
+#'   truncation (delayed entry) times for `y` can be specified using
+#'   `left_truncation_y`.
 #'   }
 #'   \item{`ppc_km_overlay_grouped()`}{
 #'    The same as `ppc_km_overlay()`, but with separate facets by `group`.
@@ -40,32 +41,33 @@
 #' @template reference-km
 #'
 #' @examples
+#' \donttest{
 #' color_scheme_set("brightblue")
-#' y <- example_y_data()
+#'
 #' # For illustrative purposes, (right-)censor values y > 110:
+#' y <- example_y_data()
 #' status_y <- as.numeric(y <= 110)
 #' y <- pmin(y, 110)
+#'
 #' # In reality, the replicated data (yrep) would be obtained from a
 #' # model which takes the censoring of y properly into account. Here,
 #' # for illustrative purposes, we simply use example_yrep_draws():
 #' yrep <- example_yrep_draws()
 #' dim(yrep)
-#' \donttest{
+#'
+#' # Overlay 25 curves
 #' ppc_km_overlay(y, yrep[1:25, ], status_y = status_y)
-#' }
+#'
 #' # With extrapolation_factor = 1 (no extrapolation)
-#' \donttest{
 #' ppc_km_overlay(y, yrep[1:25, ], status_y = status_y, extrapolation_factor = 1)
-#' }
+#'
 #' # With extrapolation_factor = Inf (show all posterior predictive draws)
-#' \donttest{
 #' ppc_km_overlay(y, yrep[1:25, ], status_y = status_y, extrapolation_factor = Inf)
-#' }
+#'
 #' # With separate facets by group:
 #' group <- example_group_data()
-#' \donttest{
 #' ppc_km_overlay_grouped(y, yrep[1:25, ], group = group, status_y = status_y)
-#' }
+#'
 #' # With left-truncation (delayed entry) times:
 #' min_vals <- pmin(y, apply(yrep, 2, min))
 #' left_truncation_y <- rep(0, length(y))
@@ -74,7 +76,6 @@
 #'   runif(sum(condition), min = 0.6, max = 0.99) * y[condition],
 #'   min_vals[condition] - 0.001
 #' )
-#' \donttest{
 #' ppc_km_overlay(y, yrep[1:25, ], status_y = status_y,
 #'               left_truncation_y = left_truncation_y)
 #' }
@@ -102,9 +103,9 @@ ppc_km_overlay <- function(
   ...,
   status_y,
   left_truncation_y = NULL,
+  extrapolation_factor = 1.2,
   size = 0.25,
-  alpha = 0.7,
-  extrapolation_factor = 1.2
+  alpha = 0.7
 ) {
   check_ignored_arguments(..., ok_args = "add_group")
   add_group <- list(...)$add_group
@@ -113,17 +114,23 @@ ppc_km_overlay <- function(
   suggested_package("ggfortify")
 
   if (!is.numeric(status_y) || length(status_y) != length(y) || !all(status_y %in% c(0, 1))) {
-    stop("`status_y` must be a numeric vector of 0s and 1s the same length as `y`.")
+    stop("`status_y` must be a numeric vector of 0s and 1s the same length as `y`.", call. = FALSE)
   }
 
   if (!is.null(left_truncation_y)) {
     if (!is.numeric(left_truncation_y) || length(left_truncation_y) != length(y)) {
-      stop("`left_truncation_y` must be a numeric vector of the same length as `y`.")
+      stop("`left_truncation_y` must be a numeric vector of the same length as `y`.", call. = FALSE)
     }
   }
 
   if (extrapolation_factor < 1) {
-    stop("`extrapolation_factor` must be greater than or equal to 1.")
+    stop("`extrapolation_factor` must be greater than or equal to 1.", call. = FALSE)
+  }
+  if (extrapolation_factor == 1.2) {
+    message(
+      "Note: `extrapolation_factor` now defaults to 1.2 (20%).\n",
+      "To display all posterior predictive draws, set `extrapolation_factor = Inf`."
+    )
   }
 
   data <- ppc_data(y, yrep, group = status_y)
@@ -218,9 +225,9 @@ ppc_km_overlay_grouped <- function(
   ...,
   status_y,
   left_truncation_y = NULL,
+  extrapolation_factor = 1.2,
   size = 0.25,
-  alpha = 0.7,
-  extrapolation_factor = 1.2
+  alpha = 0.7
 ) {
   check_ignored_arguments(...)
 

man/PPC-censoring.Rd

@@ -69,6 +69,14 @@ test_that("ppc_km_overlay errors if bad extrapolation_factor value", {
   )
 })
 
+test_that("ppc_km_overlay messages if extrapolation_factor left at default value", {
+  skip_if_not_installed("ggfortify")
+  expect_message(
+    ppc_km_overlay(y, yrep, status_y = status_y),
+    "To display all posterior predictive draws, set `extrapolation_factor = Inf`.",
+  )
+})
+
 # Visual tests -----------------------------------------------------------------
 
 test_that("ppc_km_overlay renders correctly", {