[WIP] [R] Replace vignettes and examples

.github/workflows/r_tests.yml

@@ -77,6 +77,11 @@ jobs:
           # Must run before checkout to have the latest git installed.
           # No need to add pandoc, the container has it figured out.
           apt update && apt install libcurl4-openssl-dev libssl-dev libssh2-1-dev libgit2-dev libglpk-dev libxml2-dev libharfbuzz-dev libfribidi-dev git librsvg2-dev librsvg2-2 -y
+      - name: Install system quarto
+        run: |
+          apt-get install -y wget
+          wget https://github.com/quarto-dev/quarto-cli/releases/download/v1.6.40/quarto-1.6.40-linux-amd64.deb
+          dpkg -i quarto-1.6.40-linux-amd64.deb
       - name: Trust git cloning project sources
         run: |
           git config --global --add safe.directory "${GITHUB_WORKSPACE}"

R-package/DESCRIPTION

@@ -45,10 +45,11 @@ License: Apache License (== 2.0) | file LICENSE
 URL: https://github.com/dmlc/xgboost
 BugReports: https://github.com/dmlc/xgboost/issues
 NeedsCompilation: yes
-VignetteBuilder: knitr
+VignetteBuilder: knitr, quarto
 Suggests:
     knitr,
     rmarkdown,
+    quarto,
     ggplot2 (>= 1.0.1),
     DiagrammeR (>= 0.9.0),
     DiagrammeRsvg,

R-package/R/xgb.importance.R

@@ -38,85 +38,64 @@
 #' (based on C++ code), it starts at 0 (as in C/C++ or Python) instead of 1 (usual in R).
 #'
 #' @examples
-#'
-#' # binomial classification using "gbtree":
-#' data(agaricus.train, package = "xgboost")
-#'
-#' bst <- xgb.train(
-#'   data = xgb.DMatrix(agaricus.train$data, label = agaricus.train$label),
-#'   nrounds = 2,
-#'   params = xgb.params(
-#'     max_depth = 2,
-#'     nthread = 2,
-#'     objective = "binary:logistic"
-#'   )
+#' # binary classification using "gbtree":
+#' data("ToothGrowth")
+#' x <- ToothGrowth[, c("len", "dose")]
+#' y <- ToothGrowth$supp
+#' model_tree_binary <- xgboost(
+#'   x, y,
+#'   nrounds = 5L,
+#'   nthreads = 1L,
+#'   booster = "gbtree",
+#'   max_depth = 2L
 #' )
-#'
-#' xgb.importance(model = bst)
-#'
-#' # binomial classification using "gblinear":
-#' bst <- xgb.train(
-#'   data = xgb.DMatrix(agaricus.train$data, label = agaricus.train$label),
-#'   nrounds = 20,
-#'   params = xgb.params(
-#'     booster = "gblinear",
-#'     learning_rate = 0.3,
-#'     nthread = 1,
-#'     objective = "binary:logistic"
-#'   )
+#' xgb.importance(model_tree_binary)
+#'
+#' # binary classification using "gblinear":
+#' model_tree_linear <- xgboost(
+#'   x, y,
+#'   nrounds = 5L,
+#'   nthreads = 1L,
+#'   booster = "gblinear",
+#'   learning_rate = 0.3
 #' )
-#'
-#' xgb.importance(model = bst)
-#'
-#' # multiclass classification using "gbtree":
-#' nclass <- 3
-#' nrounds <- 10
-#' mbst <- xgb.train(
-#'   data = xgb.DMatrix(
-#'     as.matrix(iris[, -5]),
-#'     label = as.numeric(iris$Species) - 1
-#'   ),
-#'   nrounds = nrounds,
-#'   params = xgb.params(
-#'     max_depth = 3,
-#'     nthread = 2,
-#'     objective = "multi:softprob",
-#'     num_class = nclass
-#'   )
+#' xgb.importance(model_tree_linear)
+#'
+#' # multi-class classification using "gbtree":
+#' data("iris")
+#' x <- iris[, c("Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width")]
+#' y <- iris$Species
+#' model_tree_multi <- xgboost(
+#'   x, y,
+#'   nrounds = 5L,
+#'   nthreads = 1L,
+#'   booster = "gbtree",
+#'   max_depth = 3
 #' )
-#'
 #' # all classes clumped together:
-#' xgb.importance(model = mbst)
-#'
+#' xgb.importance(model_tree_multi)
 #' # inspect importances separately for each class:
+#' num_classes <- 3L
+#' nrounds <- 5L
 #' xgb.importance(
-#'   model = mbst, trees = seq(from = 1, by = nclass, length.out = nrounds)
+#'   model_tree_multi, trees = seq(from = 1, by = num_classes, length.out = nrounds)
 #' )
 #' xgb.importance(
-#'   model = mbst, trees = seq(from = 2, by = nclass, length.out = nrounds)
+#'   model_tree_multi, trees = seq(from = 2, by = num_classes, length.out = nrounds)
 #' )
 #' xgb.importance(
-#'   model = mbst, trees = seq(from = 3, by = nclass, length.out = nrounds)
+#'   model_tree_multi, trees = seq(from = 3, by = num_classes, length.out = nrounds)
 #' )
 #'
-#' # multiclass classification using "gblinear":
-#' mbst <- xgb.train(
-#'   data = xgb.DMatrix(
-#'     scale(as.matrix(iris[, -5])),
-#'     label = as.numeric(iris$Species) - 1
-#'   ),
-#'   nrounds = 15,
-#'   params = xgb.params(
-#'     booster = "gblinear",
-#'     learning_rate = 0.2,
-#'     nthread = 1,
-#'     objective = "multi:softprob",
-#'     num_class = nclass
-#'   )
+#' # multi-class classification using "gblinear":
+#' model_linear_multi <- xgboost(
+#'   x, y,
+#'   nrounds = 5L,
+#'   nthreads = 1L,
+#'   booster = "gblinear",
+#'   learning_rate = 0.2
 #' )
-#'
-#' xgb.importance(model = mbst)
-#'
+#' xgb.importance(model_linear_multi)
 #' @export
 xgb.importance <- function(model = NULL, feature_names = getinfo(model, "feature_name"), trees = NULL) {
 

R-package/R/xgb.plot.deepness.R

@@ -49,27 +49,24 @@
 #' data.table::setDTthreads(nthread)
 #'
 #' ## Change max_depth to a higher number to get a more significant result
-#' bst <- xgb.train(
-#'   data = xgb.DMatrix(agaricus.train$data, label = agaricus.train$label),
+#' model <- xgboost(
+#'   agaricus.train$data, factor(agaricus.train$label),
 #'   nrounds = 50,
-#'   params = xgb.params(
-#'     max_depth = 6,
-#'     nthread = nthread,
-#'     objective = "binary:logistic",
-#'     subsample = 0.5,
-#'     min_child_weight = 2
-#'   )
+#'   max_depth = 6,
+#'   nthreads = nthread,
+#'   subsample = 0.5,
+#'   min_child_weight = 2
 #' )
 #'
-#' xgb.plot.deepness(bst)
-#' xgb.ggplot.deepness(bst)
+#' xgb.plot.deepness(model)
+#' xgb.ggplot.deepness(model)
 #'
 #' xgb.plot.deepness(
-#'   bst, which = "max.depth", pch = 16, col = rgb(0, 0, 1, 0.3), cex = 2
+#'   model, which = "max.depth", pch = 16, col = rgb(0, 0, 1, 0.3), cex = 2
 #' )
 #'
 #' xgb.plot.deepness(
-#'   bst, which = "med.weight", pch = 16, col = rgb(0, 0, 1, 0.3), cex = 2
+#'   model, which = "med.weight", pch = 16, col = rgb(0, 0, 1, 0.3), cex = 2
 #' )
 #'
 #' @rdname xgb.plot.deepness

R-package/R/xgb.plot.importance.R

@@ -50,17 +50,14 @@
 #' nthread <- 2
 #' data.table::setDTthreads(nthread)
 #'
-#' bst <- xgb.train(
-#'   data = xgb.DMatrix(agaricus.train$data, label = agaricus.train$label),
+#' model <- xgboost(
+#'   agaricus.train$data, factor(agaricus.train$label),
 #'   nrounds = 2,
-#'   params = xgb.params(
-#'     max_depth = 3,
-#'     nthread = nthread,
-#'     objective = "binary:logistic"
-#'   )
+#'   max_depth = 3,
+#'   nthreads = nthread
 #' )
 #'
-#' importance_matrix <- xgb.importance(colnames(agaricus.train$data), model = bst)
+#' importance_matrix <- xgb.importance(model)
 #' xgb.plot.importance(
 #'   importance_matrix, rel_to_first = TRUE, xlab = "Relative importance"
 #' )

R-package/R/xgb.plot.multi.trees.R

@@ -36,26 +36,23 @@
 #' nthread <- 2
 #' data.table::setDTthreads(nthread)
 #'
-#' bst <- xgb.train(
-#'   data = xgb.DMatrix(agaricus.train$data, label = agaricus.train$label),
+#' model <- xgboost(
+#'   agaricus.train$data, factor(agaricus.train$label),
 #'   nrounds = 30,
-#'   verbose = 0,
-#'   params = xgb.params(
-#'     max_depth = 15,
-#'     learning_rate = 1,
-#'     nthread = nthread,
-#'     objective = "binary:logistic",
-#'     min_child_weight = 50
-#'   )
+#'   verbosity = 0L,
+#'   nthreads = nthread,
+#'   max_depth = 15,
+#'   learning_rate = 1,
+#'   min_child_weight = 50
 #' )
 #'
-#' p <- xgb.plot.multi.trees(model = bst, features_keep = 3)
+#' p <- xgb.plot.multi.trees(model, features_keep = 3)
 #' print(p)
 #'
 #' # Below is an example of how to save this plot to a file.
 #' if (require("DiagrammeR") && require("DiagrammeRsvg") && require("rsvg")) {
 #'   fname <- file.path(tempdir(), "tree.pdf")
-#'   gr <- xgb.plot.multi.trees(bst, features_keep = 3, render = FALSE)
+#'   gr <- xgb.plot.multi.trees(model, features_keep = 3, render = FALSE)
 #'   export_graph(gr, fname, width = 1500, height = 600)
 #' }
 #' @export

R-package/R/xgb.plot.shap.R

@@ -81,51 +81,44 @@
 #' data.table::setDTthreads(nthread)
 #' nrounds <- 20
 #'
-#' bst <- xgb.train(
-#'   data = xgb.DMatrix(agaricus.train$data, agaricus.train$label),
+#' model_binary <- xgboost(
+#'   agaricus.train$data, factor(agaricus.train$label),
 #'   nrounds = nrounds,
-#'   verbose = 0,
-#'   params = xgb.params(
-#'     learning_rate = 0.1,
-#'     max_depth = 3,
-#'     subsample = 0.5,
-#'     objective = "binary:logistic",
-#'     nthread = nthread
-#'   )
+#'   verbosity = 0L,
+#'   learning_rate = 0.1,
+#'   max_depth = 3L,
+#'   subsample = 0.5,
+#'   nthreads = nthread
 #' )
 #'
-#' xgb.plot.shap(agaricus.test$data, model = bst, features = "odor=none")
+#' xgb.plot.shap(agaricus.test$data, model = model_binary, features = "odor=none")
 #'
-#' contr <- predict(bst, agaricus.test$data, predcontrib = TRUE)
-#' xgb.plot.shap(agaricus.test$data, contr, model = bst, top_n = 12, n_col = 3)
+#' contr <- predict(model_binary, agaricus.test$data, type = "contrib")
+#' xgb.plot.shap(agaricus.test$data, contr, model = model_binary, top_n = 12, n_col = 3)
 #'
 #' # Summary plot
-#' xgb.ggplot.shap.summary(agaricus.test$data, contr, model = bst, top_n = 12)
+#' xgb.ggplot.shap.summary(agaricus.test$data, contr, model = model_binary, top_n = 12)
 #'
 #' # Multiclass example - plots for each class separately:
-#' nclass <- 3
 #' x <- as.matrix(iris[, -5])
 #' set.seed(123)
 #' is.na(x[sample(nrow(x) * 4, 30)]) <- TRUE # introduce some missing values
 #'
-#' mbst <- xgb.train(
-#'   data = xgb.DMatrix(x, label = as.numeric(iris$Species) - 1),
+#' model_multiclass <- xgboost(
+#'   x, iris$Species,
 #'   nrounds = nrounds,
-#'   verbose = 0,
-#'   params = xgb.params(
-#'     max_depth = 2,
-#'     subsample = 0.5,
-#'     nthread = nthread,
-#'     objective = "multi:softprob",
-#'     num_class = nclass
-#'   )
+#'   verbosity = 0,
+#'   max_depth = 2,
+#'   subsample = 0.5,
+#'   nthreads = nthread
 #' )
+#' nclass <- 3
 #' trees0 <- seq(from = 1, by = nclass, length.out = nrounds)
 #' col <- rgb(0, 0, 1, 0.5)
 #'
 #' xgb.plot.shap(
 #'   x,
-#'   model = mbst,
+#'   model = model_multiclass,
 #'   trees = trees0,
 #'   target_class = 0,
 #'   top_n = 4,
@@ -137,7 +130,7 @@
 #'
 #' xgb.plot.shap(
 #'   x,
-#'   model = mbst,
+#'   model = model_multiclass,
 #'   trees = trees0 + 1,
 #'   target_class = 1,
 #'   top_n = 4,
@@ -149,7 +142,7 @@
 #'
 #' xgb.plot.shap(
 #'   x,
-#'   model = mbst,
+#'   model = model_multiclass,
 #'   trees = trees0 + 2,
 #'   target_class = 2,
 #'   top_n = 4,
@@ -160,7 +153,7 @@
 #' )
 #'
 #' # Summary plot
-#' xgb.ggplot.shap.summary(x, model = mbst, target_class = 0, top_n = 4)
+#' xgb.ggplot.shap.summary(x, model = model_multiclass, target_class = 0, top_n = 4)
 #'
 #' @rdname xgb.plot.shap
 #' @export

R-package/R/xgb.plot.tree.R

@@ -37,25 +37,23 @@
 #' line.
 #'
 #' @examples
-#' data(agaricus.train, package = "xgboost")
-#'
-#' bst <- xgb.train(
-#'   data = xgb.DMatrix(agaricus.train$data, agaricus.train$label),
-#'   nrounds = 2,
-#'   params = xgb.params(
-#'     max_depth = 3,
-#'     nthread = 2,
-#'     objective = "binary:logistic"
-#'   )
+#' data("ToothGrowth")
+#' x <- ToothGrowth[, c("len", "dose")]
+#' y <- ToothGrowth$supp
+#' model <- xgboost(
+#'   x, y,
+#'   nthreads = 1L,
+#'   nrounds = 3L,
+#'   max_depth = 3L
 #' )
 #'
 #' # plot the first tree
-#' xgb.plot.tree(model = bst, tree_idx = 1)
+#' xgb.plot.tree(model, tree_idx = 1)
 #'
 #' # Below is an example of how to save this plot to a file.
 #' if (require("DiagrammeR") && require("htmlwidgets")) {
 #'   fname <- file.path(tempdir(), "plot.html'")
-#'   gr <- xgb.plot.tree(bst, tree_idx = 1)
+#'   gr <- xgb.plot.tree(model, tree_idx = 1)
 #'   htmlwidgets::saveWidget(gr, fname)
 #' }
 #' @export