remove .time_as_binary_event() (#980)

* remove `.time_as_binary_event()`

until we have a better understanding of the use cases to inform how we deal with not-well-defined evaluation times

* update NEWS

Author: hfrick

NAMESPACE

@@ -165,7 +165,6 @@ export(.model_param_name_key)
 export(.obs)
 export(.organize_glmnet_pred)
 export(.preds)
-export(.time_as_binary_event)
 export(.x)
 export(.y)
 export(C5.0_train)

NEWS.md

@@ -6,7 +6,7 @@
 
 * For BART models with the `dbarts` engine, `predict()` can now also return the standard error for confidence and prediction intervals (#976).
 
-* A few censored regression helper functions were exported: `.extract_surv_status()`, `.extract_surv_time()`, and `.time_as_binary_event()` (#973).
+* A few censored regression helper functions were exported: `.extract_surv_status()` and `.extract_surv_time()` (#973, #980).
 
 * Fixed bug where prediction on rank dificient `lm()` models produced `.pred_res` instead of `.pred`. (#985)
 

R/standalone-survival.R

@@ -1,7 +1,7 @@
 # ---
 # repo: tidymodels/parsnip
 # file: standalone-survival.R
-# last-updated: 2023-05-18
+# last-updated: 2023-06-14
 # license: https://unlicense.org
 # ---
 
@@ -14,6 +14,9 @@
 #
 # 2023-05-18
 # * added time to factor conversion
+#
+# 2023-06-14
+# * removed time to factor conversion
 
 # @param surv A [survival::Surv()] object
 # @details
@@ -22,15 +25,11 @@
 #
 # `.extract_status()` will return the data as 0/1 even if the original object
 # used the legacy encoding of 1/2. See [survival::Surv()].
-#
-# `.time_as_binary_event()` takes a Surv object and converts it to a binary
-# outcome (if possible).
 
 # @return
 # - `.extract_surv_status()` returns a vector.
 # - `.extract_surv_time()` returns a vector when the type is `"right"` or `"left"`
 #    and a tibble otherwise.
-# - `.time_as_binary_event()` returns a two-level factor.
 # - Functions starting with `.is_` or `.check_` return logicals although the
 #   latter will fail when `FALSE`.
 
@@ -91,25 +90,4 @@
   }
   res
 }
-
-.time_as_binary_event <- function(surv, eval_time) {
-  eval_time <- eval_time[!is.na(eval_time)]
-  eval_time <- eval_time[eval_time >= 0 & is.finite(eval_time)]
-  eval_time <- unique(eval_time)
-  if (length(eval_time) != 1 || !is.numeric(eval_time)) {
-    stop("'eval_time' should be a single, complete, finite numeric value.")
-  }
-
-  event_time <- .extract_surv_time(surv)
-  status <- .extract_surv_status(surv)
-  is_event_before_t <- event_time <= eval_time & status == 1
-  # Three possible contributions to the statistic from Graf 1999
-  # Censoring time before eval_time, no contribution (Graf category 3)
-  binary_res <- rep(NA_character_, length(event_time))
-  # A real event prior to eval_time (Graf category 1)
-  binary_res <- ifelse(is_event_before_t, "event", binary_res)
-  # Observed time greater than eval_time (Graf category 2)
-  binary_res <- ifelse(event_time > eval_time, "non-event", binary_res)
-  factor(binary_res, levels = c("event", "non-event"))
-}
 # nocov end

R/survival-helpers.R

@@ -24,28 +24,3 @@ assign(".extract_surv_time", surv_ns[[".extract_surv_time"]])
 #' @return A numeric vector.
 #' @export
 assign(".extract_surv_status", surv_ns[[".extract_surv_status"]])
-
-#' Convert survival objects to binary factors
-#'
-#' For a given evaluation time, convert a [survival::Surv()] object to a binary
-#' factor with levels `"event"` and `"non-event"`.
-#'
-#' @name .time_as_binary_event
-#' @param surv A single [survival::Surv()] object.
-#' @param eval_time A single numeric value for the evaluation time.
-#' @return A two level factor.
-#' @details
-#' The following three cases can occur:
-#'  - **Events**: Evaluation time is greater than or equal to the event time
-#' ("it has already happened").
-#'  - **Non-events**: Evaluation time is less than the observed time, censored
-#'  or not ("nothing has happened yet").
-#'  - **Ambiguous outcomes**: Evaluation time is greater than or equal to the
-#'  observed censored time ("we don't know if anything might have happened by now").
-#'  A missing value is returned for these observations.
-#'
-#' @references  Graf, E., Schmoor, C., Sauerbrei, W., and Schumacher, M. (1999).
-#' "Assessment and Comparison of Prognostic Classification Schemes for Survival Data."
-#' _Statistics in Medicine_, 18, 2529-2545.
-#' @export
-assign(".time_as_binary_event", surv_ns[[".time_as_binary_event"]])

_pkgdown.yml

@@ -107,4 +107,3 @@ reference:
       - .extract_surv_status
       - .extract_surv_time
       - .model_param_name_key
-      - .time_as_binary_event