Add global configuration (#6414)

* Add management functions for global configuration: XGBSetGlobalConfig(), XGBGetGlobalConfig().
* Add Python interface: set_config(), get_config(), and config_context().
* Add unit tests for Python
* Add R interface: xgb.set.config(), xgb.get.config()
* Add unit tests for R

Co-authored-by: Jiaming Yuan <jm.yuan@outlook.com>

R-package/DESCRIPTION

@@ -53,7 +53,6 @@ Suggests:
     testthat,
     lintr,
     igraph (>= 1.0.1),
-    jsonlite,
     float,
     crayon,
     titanic
@@ -64,5 +63,6 @@ Imports:
     methods,
     data.table (>= 1.9.6),
     magrittr (>= 1.5),
+    jsonlite (>= 1.0),
 RoxygenNote: 7.1.1
 SystemRequirements: GNU make, C++14

R-package/NAMESPACE

@@ -36,6 +36,7 @@ export(xgb.create.features)
 export(xgb.cv)
 export(xgb.dump)
 export(xgb.gblinear.history)
+export(xgb.get.config)
 export(xgb.ggplot.deepness)
 export(xgb.ggplot.importance)
 export(xgb.ggplot.shap.summary)
@@ -52,6 +53,7 @@ export(xgb.plot.tree)
 export(xgb.save)
 export(xgb.save.raw)
 export(xgb.serialize)
+export(xgb.set.config)
 export(xgb.train)
 export(xgb.unserialize)
 export(xgboost)
@@ -78,6 +80,8 @@ importFrom(graphics,lines)
 importFrom(graphics,par)
 importFrom(graphics,points)
 importFrom(graphics,title)
+importFrom(jsonlite,fromJSON)
+importFrom(jsonlite,toJSON)
 importFrom(magrittr,"%>%")
 importFrom(stats,median)
 importFrom(stats,predict)

R-package/R/xgb.config.R

@@ -0,0 +1,38 @@
+#' Global configuration consists of a collection of parameters that can be applied in the global
+#' scope. See \url{https://xgboost.readthedocs.io/en/stable/parameter.html} for the full list of
+#' parameters supported in the global configuration. Use \code{xgb.set.config} to update the
+#' values of one or more global-scope parameters. Use \code{xgb.get.config} to fetch the current
+#' values of all global-scope parameters (listed in
+#' \url{https://xgboost.readthedocs.io/en/stable/parameter.html}).
+#'
+#' @rdname xgbConfig
+#' @title Set and get global configuration
+#' @name xgb.set.config, xgb.get.config
+#' @export xgb.set.config xgb.get.config
+#' @param ... List of parameters to be set, as keyword arguments
+#' @return
+#' \code{xgb.set.config} returns \code{TRUE} to signal success. \code{xgb.get.config} returns
+#' a list containing all global-scope parameters and their values.
+#'
+#' @examples
+#' # Set verbosity level to silent (0)
+#' xgb.set.config(verbosity = 0)
+#' # Now global verbosity level is 0
+#' config <- xgb.get.config()
+#' print(config$verbosity)
+#' # Set verbosity level to warning (1)
+#' xgb.set.config(verbosity = 1)
+#' # Now global verbosity level is 1
+#' config <- xgb.get.config()
+#' print(config$verbosity)
+xgb.set.config <- function(...) {
+  new_config <- list(...)
+  .Call(XGBSetGlobalConfig_R, jsonlite::toJSON(new_config, auto_unbox = TRUE))
+  return(TRUE)
+}
+
+#' @rdname xgbConfig
+xgb.get.config <- function() {
+  config <- .Call(XGBGetGlobalConfig_R)
+  return(jsonlite::fromJSON(config))
+}

R-package/R/xgboost.R

@@ -91,6 +91,8 @@ NULL
 #' @importFrom data.table setkeyv
 #' @importFrom data.table setnames
 #' @importFrom magrittr %>%
+#' @importFrom jsonlite fromJSON
+#' @importFrom jsonlite toJSON
 #' @importFrom utils object.size str tail
 #' @importFrom stats predict
 #' @importFrom stats median

R-package/man/xgbConfig.Rd

@@ -0,0 +1,39 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/xgb.config.R
+\name{xgb.set.config, xgb.get.config}
+\alias{xgb.set.config, xgb.get.config}
+\alias{xgb.set.config}
+\alias{xgb.get.config}
+\title{Set and get global configuration}
+\usage{
+xgb.set.config(...)
+
+xgb.get.config()
+}
+\arguments{
+\item{...}{List of parameters to be set, as keyword arguments}
+}
+\value{
+\code{xgb.set.config} returns \code{TRUE} to signal success. \code{xgb.get.config} returns
+a list containing all global-scope parameters and their values.
+}
+\description{
+Global configuration consists of a collection of parameters that can be applied in the global
+scope. See \url{https://xgboost.readthedocs.io/en/stable/parameter.html} for the full list of
+parameters supported in the global configuration. Use \code{xgb.set.config} to update the
+values of one or more global-scope parameters. Use \code{xgb.get.config} to fetch the current
+values of all global-scope parameters (listed in
+\url{https://xgboost.readthedocs.io/en/stable/parameter.html}).
+}
+\examples{
+# Set verbosity level to silent (0)
+xgb.set.config(verbosity = 0)
+# Now global verbosity level is 0
+config <- xgb.get.config()
+print(config$verbosity)
+# Set verbosity level to warning (1)
+xgb.set.config(verbosity = 1)
+# Now global verbosity level is 1
+config <- xgb.get.config()
+print(config$verbosity)
+}

R-package/src/init.c

@@ -43,6 +43,8 @@ extern SEXP XGDMatrixNumRow_R(SEXP);
 extern SEXP XGDMatrixSaveBinary_R(SEXP, SEXP, SEXP);
 extern SEXP XGDMatrixSetInfo_R(SEXP, SEXP, SEXP);
 extern SEXP XGDMatrixSliceDMatrix_R(SEXP, SEXP);
+extern SEXP XGBSetGlobalConfig_R(SEXP);
+extern SEXP XGBGetGlobalConfig_R();
 
 static const R_CallMethodDef CallEntries[] = {
   {"XGBoosterBoostOneIter_R",     (DL_FUNC) &XGBoosterBoostOneIter_R,     4},
@@ -73,6 +75,8 @@ static const R_CallMethodDef CallEntries[] = {
   {"XGDMatrixSaveBinary_R",       (DL_FUNC) &XGDMatrixSaveBinary_R,       3},
   {"XGDMatrixSetInfo_R",          (DL_FUNC) &XGDMatrixSetInfo_R,          3},
   {"XGDMatrixSliceDMatrix_R",     (DL_FUNC) &XGDMatrixSliceDMatrix_R,     2},
+  {"XGBSetGlobalConfig_R",        (DL_FUNC) &XGBSetGlobalConfig_R,        1},
+  {"XGBGetGlobalConfig_R",        (DL_FUNC) &XGBGetGlobalConfig_R,        0},
   {NULL, NULL, 0}
 };
 

R-package/src/xgboost_R.cc

@@ -49,6 +49,21 @@ void _DMatrixFinalizer(SEXP ext) {
   R_API_END();
 }
 
+SEXP XGBSetGlobalConfig_R(SEXP json_str) {
+  R_API_BEGIN();
+  CHECK_CALL(XGBSetGlobalConfig(CHAR(asChar(json_str))));
+  R_API_END();
+  return R_NilValue;
+}
+
+SEXP XGBGetGlobalConfig_R() {
+  const char* json_str;
+  R_API_BEGIN();
+  CHECK_CALL(XGBGetGlobalConfig(&json_str));
+  R_API_END();
+  return mkString(json_str);
+}
+
 SEXP XGDMatrixCreateFromFile_R(SEXP fname, SEXP silent) {
   SEXP ret;
   R_API_BEGIN();

R-package/src/xgboost_R.h

@@ -21,6 +21,19 @@
  */
 XGB_DLL SEXP XGCheckNullPtr_R(SEXP handle);
 
+/*!
+ * \brief Set global configuration
+ * \param json_str a JSON string representing the list of key-value pairs
+ * \return R_NilValue
+ */
+XGB_DLL SEXP XGBSetGlobalConfig_R(SEXP json_str);
+
+/*!
+ * \brief Get global configuration
+ * \return JSON string
+ */
+XGB_DLL SEXP XGBGetGlobalConfig_R();
+
 /*!
  * \brief load a data matrix
  * \param fname name of the content

R-package/src/xgboost_custom.cc

@@ -16,7 +16,7 @@ void CustomLogMessage::Log(const std::string& msg) {
 namespace xgboost {
 ConsoleLogger::~ConsoleLogger() {
   if (cur_verbosity_ == LogVerbosity::kIgnore ||
-      cur_verbosity_ <= global_verbosity_) {
+      cur_verbosity_ <= GlobalVerbosity()) {
     dmlc::CustomLogMessage::Log(log_stream_.str());
   }
 }

R-package/tests/testthat/test_config.R

@@ -0,0 +1,11 @@
+context('Test global configuration')
+
+test_that('Global configuration works with verbosity', {
+  old_verbosity <- xgb.get.config()$verbosity
+  for (v in c(0, 1, 2, 3)) {
+    xgb.set.config(verbosity = v)
+    expect_equal(xgb.get.config()$verbosity, v)
+  }
+  xgb.set.config(verbosity = old_verbosity)
+  expect_equal(xgb.get.config()$verbosity, old_verbosity)
+})