[R] Add parameters constructor (#11072)

---------

Co-authored-by: Michael Mayer <[email protected]>

R-package/NAMESPACE

@@ -21,7 +21,7 @@ S3method(variable.names,xgb.Booster)
 export("xgb.attr<-")
 export("xgb.attributes<-")
 export("xgb.config<-")
-export("xgb.parameters<-")
+export("xgb.model.parameters<-")
 export(getinfo)
 export(setinfo)
 export(xgb.Callback)
@@ -61,6 +61,7 @@ export(xgb.is.same.Booster)
 export(xgb.load)
 export(xgb.load.raw)
 export(xgb.model.dt.tree)
+export(xgb.params)
 export(xgb.plot.deepness)
 export(xgb.plot.importance)
 export(xgb.plot.multi.trees)

R-package/R/callbacks.R

@@ -204,7 +204,7 @@
 #' dm <- xgb.DMatrix(x, label = y, nthread = 1)
 #' model <- xgb.train(
 #'   data = dm,
-#'   params = list(objective = "reg:squarederror", nthread = 1),
+#'   params = xgb.params(objective = "reg:squarederror", nthread = 1),
 #'   nrounds = 5,
 #'   callbacks = list(ssq_callback),
 #'   keep_extra_attributes = TRUE
@@ -563,7 +563,7 @@ xgb.cb.reset.parameters <- function(new_params) {
       }
     },
     f_before_iter = function(env, model, data, evals, iteration) {
-      pars <- lapply(env$new_params, function(p) {
+      params <- lapply(env$new_params, function(p) {
         if (is.function(p)) {
           return(p(iteration, env$end_iteration))
         } else {
@@ -572,10 +572,10 @@ xgb.cb.reset.parameters <- function(new_params) {
       })
 
       if (inherits(model, "xgb.Booster")) {
-        xgb.parameters(model) <- pars
+        xgb.model.parameters(model) <- params
       } else {
         for (fd in model) {
-          xgb.parameters(fd$bst) <- pars
+          xgb.model.parameters(fd$bst) <- params
         }
       }
       return(FALSE)

R-package/R/xgb.Booster.R

@@ -20,20 +20,20 @@ xgb.Booster <- function(params, cachelist, modelfile) {
       .Call(XGBoosterLoadModel_R, xgb.get.handle(bst), enc2utf8(modelfile[1]))
       niter <- xgb.get.num.boosted.rounds(bst)
       if (length(params) > 0) {
-        xgb.parameters(bst) <- params
+        xgb.model.parameters(bst) <- params
       }
       return(list(bst = bst, niter = niter))
     } else if (is.raw(modelfile)) {
       ## A memory buffer
       bst <- xgb.load.raw(modelfile)
       niter <- xgb.get.num.boosted.rounds(bst)
-      xgb.parameters(bst) <- params
+      xgb.model.parameters(bst) <- params
       return(list(bst = bst, niter = niter))
     } else if (inherits(modelfile, "xgb.Booster")) {
       ## A booster object
       bst <- .Call(XGDuplicate_R, modelfile)
       niter <- xgb.get.num.boosted.rounds(bst)
-      xgb.parameters(bst) <- params
+      xgb.model.parameters(bst) <- params
       return(list(bst = bst, niter = niter))
     } else {
       stop("modelfile must be either character filename, or raw booster dump, or xgb.Booster object")
@@ -42,7 +42,7 @@ xgb.Booster <- function(params, cachelist, modelfile) {
   ## Create new model
   bst <- .Call(XGBoosterCreate_R, cachelist)
   if (length(params) > 0) {
-    xgb.parameters(bst) <- params
+    xgb.model.parameters(bst) <- params
   }
   return(list(bst = bst, niter = 0L))
 }
@@ -196,7 +196,7 @@ xgb.get.handle <- function(object) {
 #' of the most important features first. See below about the format of the returned results.
 #'
 #' The `predict()` method uses as many threads as defined in `xgb.Booster` object (all by default).
-#' If you want to change their number, assign a new number to `nthread` using [xgb.parameters<-()].
+#' If you want to change their number, assign a new number to `nthread` using [xgb.model.parameters<-()].
 #' Note that converting a matrix to [xgb.DMatrix()] uses multiple threads too.
 #'
 #' @return
@@ -631,7 +631,7 @@ validate.features <- function(bst, newdata) {
 #' and its serialization is handled externally.
 #' Also, setting an attribute that has the same name as one of XGBoost's parameters wouldn't
 #' change the value of that parameter for a model.
-#' Use [xgb.parameters<-()] to set or change model parameters.
+#' Use [xgb.model.parameters<-()] to set or change model parameters.
 #'
 #' The `xgb.attributes<-` setter either updates the existing or adds one or several attributes,
 #' but it doesn't delete the other existing attributes.
@@ -828,11 +828,11 @@ xgb.config <- function(object) {
 #'   objective = "binary:logistic"
 #' )
 #'
-#' xgb.parameters(bst) <- list(eta = 0.1)
+#' xgb.model.parameters(bst) <- list(eta = 0.1)
 #'
-#' @rdname xgb.parameters
+#' @rdname xgb.model.parameters
 #' @export
-`xgb.parameters<-` <- function(object, value) {
+`xgb.model.parameters<-` <- function(object, value) {
   if (length(value) == 0) return(object)
   p <- as.list(value)
   if (is.null(names(p)) || any(nchar(names(p)) == 0)) {
@@ -897,7 +897,7 @@ setinfo.xgb.Booster <- function(object, name, info) {
 #' @param model,x A fitted `xgb.Booster` model.
 #' @return The number of rounds saved in the model as an integer.
 #' @details Note that setting booster parameters related to training
-#' continuation / updates through [xgb.parameters<-()] will reset the
+#' continuation / updates through [xgb.model.parameters<-()] will reset the
 #' number of rounds to zero.
 #' @export
 #' @rdname xgb.get.num.boosted.rounds
@@ -936,7 +936,7 @@ length.xgb.Booster <- function(x) {
 #' x <- as.matrix(mtcars[, -1])
 #'
 #' dm <- xgb.DMatrix(x, label = y, nthread = 1)
-#' model <- xgb.train(data = dm, params = list(nthread = 1), nrounds = 5)
+#' model <- xgb.train(data = dm, params = xgb.params(nthread = 1), nrounds = 5)
 #' model_slice <- xgb.slice.Booster(model, 1, 3)
 #' # Prediction for first three rounds
 #' predict(model, x, predleaf = TRUE)[, 1:3]
@@ -1163,7 +1163,7 @@ coef.xgb.Booster <- function(object, ...) {
 #'
 #' model <- xgb.train(
 #'   data = dm,
-#'   params = list(nthread = 1),
+#'   params = xgb.params(nthread = 1),
 #'   nround = 3
 #' )
 #'
@@ -1225,7 +1225,7 @@ xgb.copy.Booster <- function(model) {
 #' x <- as.matrix(mtcars[, -1])
 #'
 #' model <- xgb.train(
-#'   params = list(nthread = 1),
+#'   params = xgb.params(nthread = 1),
 #'   data = xgb.DMatrix(x, label = y, nthread = 1),
 #'   nround = 3
 #' )

R-package/R/xgb.DMatrix.R

@@ -1136,7 +1136,7 @@ setinfo.xgb.DMatrix <- function(object, name, info) {
 #' # DMatrix is not quantized right away, but will be once a hist model is generated
 #' model <- xgb.train(
 #'   data = dm,
-#'   params = list(tree_method = "hist", max_bin = 8, nthread = 1),
+#'   params = xgb.params(tree_method = "hist", max_bin = 8, nthread = 1),
 #'   nrounds = 3
 #' )
 #'

R-package/R/xgb.cv.R

@@ -2,24 +2,7 @@
 #'
 #' The cross validation function of xgboost.
 #'
-#' @param params The list of parameters. The complete list of parameters is available in the
-#'   [online documentation](http://xgboost.readthedocs.io/en/latest/parameter.html).
-#'   Below is a shorter summary:
-#'   - `objective`: Objective function, common ones are
-#'      - `reg:squarederror`: Regression with squared loss.
-#'      - `binary:logistic`: Logistic regression for classification.
-#'
-#'     See [xgb.train()] for complete list of objectives.
-#'   - `eta`: Step size of each boosting step
-#'   - `max_depth`: Maximum depth of the tree
-#'   - `nthread`: Number of threads used in training. If not set, all threads are used
-#'
-#'   See [xgb.train()] for further details.
-#'   See also demo for walkthrough example in R.
-#'
-#'   Note that, while `params` accepts a `seed` entry and will use such parameter for model training if
-#'   supplied, this seed is not used for creation of train-test splits, which instead rely on R's own RNG
-#'   system - thus, for reproducible results, one needs to call the [set.seed()] function beforehand.
+#' @inheritParams xgb.train
 #' @param data An `xgb.DMatrix` object, with corresponding fields like `label` or bounds as required
 #'   for model training by the objective.
 #'
@@ -84,8 +67,6 @@
 #'   See [xgb.Callback()]. Some of the callbacks are automatically created depending on the
 #'   parameters' values. User can provide either existing or their own callback methods in order
 #'   to customize the training process.
-#' @param ... Other parameters to pass to `params`.
-#'
 #' @details
 #' The original sample is randomly partitioned into `nfold` equal size subsamples.
 #'
@@ -133,13 +114,14 @@
 #'   nfold = 5,
 #'   metrics = list("rmse","auc"),
 #'   max_depth = 3,
-#'   eta = 1,objective = "binary:logistic"
+#'   eta = 1,
+#'   objective = "binary:logistic"
 #' )
 #' print(cv)
 #' print(cv, verbose = TRUE)
 #'
 #' @export
-xgb.cv <- function(params = list(), data, nrounds, nfold,
+xgb.cv <- function(params = xgb.params(), data, nrounds, nfold,
                    prediction = FALSE, showsd = TRUE, metrics = list(),
                    obj = NULL, feval = NULL, stratified = "auto", folds = NULL, train_folds = NULL,
                    verbose = TRUE, print_every_n = 1L,