Soft-deprecate validation_split()

DESCRIPTION

@@ -26,6 +26,7 @@ Imports:
     furrr,
     generics,
     glue,
+    lifecycle,
     methods,
     pillar,
     purrr (>= 1.0.0),

NAMESPACE

@@ -419,6 +419,7 @@ importFrom(dplyr,summarize)
 importFrom(dplyr,ungroup)
 importFrom(furrr,future_map)
 importFrom(generics,tidy)
+importFrom(lifecycle,deprecated)
 importFrom(methods,formalArgs)
 importFrom(pillar,type_sum)
 importFrom(purrr,list_rbind)

NEWS.md

@@ -4,6 +4,8 @@
 
 * The new `initial_validation_split()`, along with variants `initial_validation_time_split()` and `group_initial_validation_split()`, generates a three-way split of the data into training, validation, and test sets. With the new `validation_set()`, this can be turned into an `rset` object for tuning (#403, #446).
 
+* `validation_split()`, `validation_time_split()`, and `group_validation_split()` have been soft-deprecated in favor of the new functions implementing a 3-way split (`initial_validation_split()`, `initial_validation_time_split()`, and `group_initial_validation_split()`) (#449).
+
 * Functions which don't use the ellipsis `...` now enforce empty dots (#429).
 
 * `make_splits()` gained an example in the documentation (@AngelFelizR, #432).

R/rsample-package.R

@@ -2,6 +2,7 @@
 "_PACKAGE"
 
 ## usethis namespace: start
+#' @importFrom lifecycle deprecated
 ## usethis namespace: end
 NULL
 

R/validation_split.R

@@ -1,5 +1,15 @@
 #' Create a Validation Set
 #'
+#' @description
+#' `r lifecycle::badge('deprecated')`
+#'
+#' This function is deprecated because it's part of an approach to constructing
+#' a training, validation, and testing set by doing a sequence of two binary
+#' splits: testing / not-testing (with [initial_split()] or one of its variants)
+#' and then not-testing split into training/validation with `validation_split()`.
+#' Instead, now use [initial_validation_split()] or one if its variants to
+#' construct the three sets via one 3-way split.
+#'
 #' `validation_split()` takes a single random sample (without replacement) of
 #'  the original data set to be used for analysis. All other data points are
 #'  added to the assessment set (to be used as the validation set).
@@ -27,6 +37,7 @@
 #' @seealso [initial_validation_split()], [group_initial_validation_split()],
 #' [validation_set()]
 #'
+#' @keywords internal
 #' @examplesIf rlang::is_installed("modeldata")
 #' cars_split <- initial_split(mtcars)
 #' cars_not_testing <- training(cars_split)
@@ -39,9 +50,14 @@
 #' # Alternative
 #' cars_split_3 <- initial_validation_split(mtcars)
 #' validation_set(cars_split_3)
-#' @export
 validation_split <- function(data, prop = 3 / 4,
                              strata = NULL, breaks = 4, pool = 0.1, ...) {
+  lifecycle::deprecate_soft(
+    "1.2.0",
+    "validation_split()",
+    "initial_validation_split()"
+  )
+
   check_dots_empty()
 
   if (!missing(strata)) {
@@ -90,6 +106,12 @@ validation_split <- function(data, prop = 3 / 4,
 #' @inheritParams initial_time_split
 #' @export
 validation_time_split <- function(data, prop = 3 / 4, lag = 0, ...) {
+  lifecycle::deprecate_soft(
+    "1.2.0",
+    "validation_time_split()",
+    "initial_validation_time_split()"
+  )
+
   check_dots_empty()
 
   if (!is.numeric(prop) | prop >= 1 | prop <= 0) {
@@ -124,6 +146,11 @@ validation_time_split <- function(data, prop = 3 / 4, lag = 0, ...) {
 #' @inheritParams group_initial_split
 #' @export
 group_validation_split <- function(data, group, prop = 3 / 4, ..., strata = NULL, pool = 0.1) {
+  lifecycle::deprecate_soft(
+    "1.2.0",
+    "group_validation_split()",
+    "group_initial_validation_split()"
+  )
 
   check_dots_empty()
 
@@ -165,4 +192,3 @@ group_validation_split <- function(data, group, prop = 3 / 4, ..., strata = NULL
     subclass = c("group_validation_split", "validation_split", "group_rset", "rset")
   )
 }
-

_pkgdown.yml

@@ -41,7 +41,6 @@ reference:
       - vfold_cv
       - loo_cv
       - mc_cv
-      - validation_split
       - validation_set
       - group_bootstraps
       - group_mc_cv