[R] Check invalid input for the cv function. (dmlc#11264)

- rename the es parameter.
- check qdm input.

Author: trivialfis

R-package/R/callbacks.R

@@ -613,17 +613,19 @@ xgb.cb.reset.parameters <- function(new_params) {
 #'   `metric_name = 'dtest-auc'` or `metric_name = 'dtest_auc'`.
 #'   All dash '-' characters in metric names are considered equivalent to '_'.
 #' @param verbose Whether to print the early stopping information.
-#' @param keep_all_iter Whether to keep all of the boosting rounds that were produced
-#'   in the resulting object. If passing `FALSE`, will only keep the boosting rounds
-#'   up to the detected best iteration, discarding the ones that come after.
+#'
+#' @param save_best Whether training should return the best model or the last model. If
+#'   set to `TRUE`, it will only keep the boosting rounds up to the detected best
+#'   iteration, discarding the ones that come after. This parameter is not supported by
+#'   the `xgb.cv` function and the `gblinear` booster yet.
 #' @return An `xgb.Callback` object, which can be passed to [xgb.train()] or [xgb.cv()].
 #' @export
 xgb.cb.early.stop <- function(
   stopping_rounds,
   maximize = FALSE,
   metric_name = NULL,
   verbose = TRUE,
-  keep_all_iter = TRUE
+  save_best = FALSE
 ) {
   if (!is.null(metric_name)) {
     stopifnot(is.character(metric_name))
@@ -639,14 +641,17 @@ xgb.cb.early.stop <- function(
         maximize = maximize,
         metric_name = metric_name,
         verbose = verbose,
-        keep_all_iter = keep_all_iter,
+        save_best = save_best,
         stopped_by_max_rounds = FALSE
       )
     ),
     f_before_training = function(env, model, data, evals, begin_iteration, end_iteration) {
       if (inherits(model, "xgb.Booster") && !length(evals)) {
         stop("For early stopping, 'evals' must have at least one element")
       }
+      if (!inherits(model, "xgb.Booster") && save_best) {
+        stop("'save_best' must be set to FALSE when using early stopping in 'xgb.cv'.")
+      }
       env$begin_iteration <- begin_iteration
       return(NULL)
     },
@@ -731,7 +736,7 @@ xgb.cb.early.stop <- function(
       return(FALSE)
     },
     f_after_training = function(env, model, data, evals, iteration, final_feval, prev_cb_res) {
-      if (inherits(model, "xgb.Booster") && !env$keep_all_iter && env$best_iteration < iteration) {
+      if (inherits(model, "xgb.Booster") && env$save_best && env$best_iteration < iteration) {
         # Note: it loses the attributes after being sliced,
         # so they have to be re-assigned afterwards.
         prev_attr <- xgb.attributes(model)

R-package/R/xgb.cv.R

@@ -113,9 +113,13 @@ xgb.cv <- function(params = xgb.params(), data, nrounds, nfold,
   check.deprecation(deprecated_cv_params, match.call(), ...)
 
   stopifnot(inherits(data, "xgb.DMatrix"))
+
   if (inherits(data, "xgb.DMatrix") && .Call(XGCheckNullPtr_R, data)) {
     stop("'data' is an invalid 'xgb.DMatrix' object. Must be constructed again.")
   }
+  if (inherits(data, "xgb.QuantileDMatrix")) {
+    stop("'xgb.QuantileDMatrix' is not supported as input to 'xgb.cv'.")
+  }
 
   params <- check.booster.params(params)
   # TODO: should we deprecate the redundant 'metrics' parameter?
@@ -171,7 +175,8 @@ xgb.cv <- function(params = xgb.params(), data, nrounds, nfold,
       xgb.cb.early.stop(
         early_stopping_rounds,
         maximize = maximize,
-        verbose = verbose
+        verbose = verbose,
+        save_best = FALSE
       ),
       as_first_elt = TRUE
     )

R-package/man/xgb.cb.early.stop.Rd

@@ -402,6 +402,40 @@ test_that("xgb.cv works", {
   expect_false(is.null(cv$call))
 })
 
+test_that("xgb.cv invalid inputs", {
+  data("mtcars")
+  y <- mtcars$mpg
+  x_df <- mtcars[, -1]
+
+  expect_error(
+    cv <- xgb.cv(
+      data = xgb.QuantileDMatrix(x_df, label = y),
+      nfold = 5,
+      nrounds = 2,
+      params = xgb.params(
+        max_depth = 2,
+        nthread = n_threads
+      )
+    ),
+    regexp = ".*QuantileDMatrix.*"
+  )
+  expect_error(
+    cv <- xgb.cv(
+      data = xgb.DMatrix(x_df, label = y),
+      nfold = 5,
+      nrounds = 2,
+      params = xgb.params(
+        max_depth = 2,
+        nthread = n_threads,
+      ),
+      callbacks = list(
+        xgb.cb.early.stop(stopping_rounds = 3, save_best = TRUE)
+      )
+    ),
+    regexp = ".*save_best.*"
+  )
+})
+
 test_that("xgb.cv works with stratified folds", {
   dtrain <- xgb.DMatrix(train$data, label = train$label, nthread = n_threads)
   set.seed(314159)

R-package/tests/testthat/test_basic.R

@@ -325,9 +325,11 @@ class EarlyStopping(TrainingCallback):
     maximize :
         Whether to maximize evaluation metric.  None means auto (discouraged).
     save_best :
-        Whether training should return the best model or the last model. This is only
-        supported with tree methods. Also, the `cv` function doesn't return a model, the
-        parameter is not applicable.
+        Whether training should return the best model or the last model. If set to
+        `True`, it will only keep the boosting rounds up to the detected best iteration,
+        discarding the ones that come after. This is only supported with tree methods
+        (not `gblinear`). Also, the `cv` function doesn't return a model, the parameter
+        is not applicable.
     min_delta :
 
         .. versionadded:: 1.5.0