[R] Improve more docstrings (#9919)

R-package/R/xgb.ggplot.R

@@ -127,22 +127,20 @@ xgb.ggplot.shap.summary <- function(data, shap_contrib = NULL, features = NULL,
   p
 }
 
-#' Combine and melt feature values and SHAP contributions for sample
-#' observations.
+#' Combine feature values and SHAP values
 #'
-#' Conforms to data format required for ggplot functions.
+#' Internal function used to combine and melt feature values and SHAP contributions
+#' as required for ggplot functions related to SHAP.
 #'
-#' Internal utility function.
+#' @param data_list The result of `xgb.shap.data()`.
+#' @param normalize Whether to standardize feature values to mean 0 and
+#'   standard deviation 1. This is useful for comparing multiple features on the same
+#'   plot. Default is \code{FALSE}.
 #'
-#' @param data_list List containing 'data' and 'shap_contrib' returned by
-#'   \code{xgb.shap.data()}.
-#' @param normalize Whether to standardize feature values to have mean 0 and
-#'   standard deviation 1 (useful for comparing multiple features on the same
-#'   plot). Default \code{FALSE}.
-#'
-#' @return A data.table containing the observation ID, the feature name, the
+#' @return A `data.table` containing the observation ID, the feature name, the
 #'   feature value (normalized if specified), and the SHAP contribution value.
 #' @noRd
+#' @keywords internal
 prepare.ggplot.shap.data <- function(data_list, normalize = FALSE) {
   data <- data_list[["data"]]
   shap_contrib <- data_list[["shap_contrib"]]
@@ -163,15 +161,16 @@ prepare.ggplot.shap.data <- function(data_list, normalize = FALSE) {
   p_data
 }
 
-#' Scale feature value to have mean 0, standard deviation 1
+#' Scale feature values
 #'
-#' This is used to compare multiple features on the same plot.
-#' Internal utility function
+#' Internal function that scales feature values to mean 0 and standard deviation 1.
+#' Useful to compare multiple features on the same plot.
 #'
-#' @param x Numeric vector
+#' @param x Numeric vector.
 #'
-#' @return Numeric vector with mean 0 and sd 1.
+#' @return Numeric vector with mean 0 and standard deviation 1.
 #' @noRd
+#' @keywords internal
 normalize <- function(x) {
   loc <- mean(x, na.rm = TRUE)
   scale <- stats::sd(x, na.rm = TRUE)

R-package/R/xgb.importance.R

@@ -1,83 +1,115 @@
-#' Importance of features in a model.
-#'
-#' Creates a \code{data.table} of feature importances in a model.
-#'
-#' @param feature_names character vector of feature names. If the model already
-#'       contains feature names, those would be used when \code{feature_names=NULL} (default value).
-#'       Non-null \code{feature_names} could be provided to override those in the model.
-#' @param model object of class \code{xgb.Booster}.
-#' @param trees (only for the gbtree booster) an integer vector of tree indices that should be included
-#'          into the importance calculation. If set to \code{NULL}, all trees of the model are parsed.
-#'          It could be useful, e.g., in multiclass classification to get feature importances
-#'          for each class separately. IMPORTANT: the tree index in xgboost models
-#'          is zero-based (e.g., use \code{trees = 0:4} for first 5 trees).
-#' @param data deprecated.
-#' @param label deprecated.
-#' @param target deprecated.
+#' Feature importance
+#'
+#' Creates a `data.table` of feature importances.
+#'
+#' @param feature_names Character vector used to overwrite the feature names
+#'        of the model. The default is `NULL` (use original feature names).
+#' @param model Object of class `xgb.Booster`.
+#' @param trees An integer vector of tree indices that should be included
+#'        into the importance calculation (only for the "gbtree" booster).
+#'        The default (`NULL`) parses all trees.
+#'        It could be useful, e.g., in multiclass classification to get feature importances
+#'        for each class separately. *Important*: the tree index in XGBoost models
+#'        is zero-based (e.g., use `trees = 0:4` for the first five trees).
+#' @param data Deprecated.
+#' @param label Deprecated.
+#' @param target Deprecated.
 #'
 #' @details
 #'
 #' This function works for both linear and tree models.
 #'
 #' For linear models, the importance is the absolute magnitude of linear coefficients.
-#' For that reason, in order to obtain a meaningful ranking by importance for a linear model,
-#' the features need to be on the same scale (which you also would want to do when using either
-#' L1 or L2 regularization).
-#'
-#' @return
-#'
-#' For a tree model, a \code{data.table} with the following columns:
-#' \itemize{
-#'   \item \code{Features} names of the features used in the model;
-#'   \item \code{Gain} represents fractional contribution of each feature to the model based on
-#'        the total gain of this feature's splits. Higher percentage means a more important
-#'        predictive feature.
-#'   \item \code{Cover} metric of the number of observation related to this feature;
-#'   \item \code{Frequency} percentage representing the relative number of times
-#'        a feature have been used in trees.
-#' }
-#'
-#' A linear model's importance \code{data.table} has the following columns:
-#' \itemize{
-#'   \item \code{Features} names of the features used in the model;
-#'   \item \code{Weight} the linear coefficient of this feature;
-#'   \item \code{Class} (only for multiclass models) class label.
-#' }
-#'
-#' If \code{feature_names} is not provided and \code{model} doesn't have \code{feature_names},
-#' index of the features will be used instead. Because the index is extracted from the model dump
+#' To obtain a meaningful ranking by importance for linear models, the features need to
+#' be on the same scale (which is also recommended when using L1 or L2 regularization).
+#'
+#' @return A `data.table` with the following columns:
+#'
+#' For a tree model:
+#' - `Features`: Names of the features used in the model.
+#' - `Gain`: Fractional contribution of each feature to the model based on
+#'    the total gain of this feature's splits. Higher percentage means higher importance.
+#' - `Cover`: Metric of the number of observation related to this feature.
+#' - `Frequency`: Percentage of times a feature has been used in trees.
+#'
+#' For a linear model:
+#' - `Features`: Names of the features used in the model.
+#' - `Weight`: Linear coefficient of this feature.
+#' - `Class`: Class label (only for multiclass models).
+#'
+#' If `feature_names` is not provided and `model` doesn't have `feature_names`,
+#' the index of the features will be used instead. Because the index is extracted from the model dump
 #' (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 <- xgboost(data = agaricus.train$data, label = agaricus.train$label, max_depth = 2,
-#'                eta = 1, nthread = 2, nrounds = 2, objective = "binary:logistic")
+#' # binomial classification using "gbtree":
+#' data(agaricus.train, package = "xgboost")
+#'
+#' bst <- xgboost(
+#'   data = agaricus.train$data,
+#'   label = agaricus.train$label,
+#'   max_depth = 2,
+#'   eta = 1,
+#'   nthread = 2,
+#'   nrounds = 2,
+#'   objective = "binary:logistic"
+#' )
+#'
 #' xgb.importance(model = bst)
 #'
-#' # binomial classification using gblinear:
-#' bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, booster = "gblinear",
-#'                eta = 0.3, nthread = 1, nrounds = 20, objective = "binary:logistic")
+#' # binomial classification using "gblinear":
+#' bst <- xgboost(
+#'   data = agaricus.train$data,
+#'   label = agaricus.train$label,
+#'   booster = "gblinear",
+#'   eta = 0.3,
+#'   nthread = 1,
+#'   nrounds = 20,objective = "binary:logistic"
+#' )
+#'
 #' xgb.importance(model = bst)
 #'
-#' # multiclass classification using gbtree:
+#' # multiclass classification using "gbtree":
 #' nclass <- 3
 #' nrounds <- 10
-#' mbst <- xgboost(data = as.matrix(iris[, -5]), label = as.numeric(iris$Species) - 1,
-#'                max_depth = 3, eta = 0.2, nthread = 2, nrounds = nrounds,
-#'                objective = "multi:softprob", num_class = nclass)
+#' mbst <- xgboost(
+#'   data = as.matrix(iris[, -5]),
+#'   label = as.numeric(iris$Species) - 1,
+#'   max_depth = 3,
+#'   eta = 0.2,
+#'   nthread = 2,
+#'   nrounds = nrounds,
+#'   objective = "multi:softprob",
+#'   num_class = nclass
+#' )
+#'
 #' # all classes clumped together:
 #' xgb.importance(model = mbst)
+#'
 #' # inspect importances separately for each class:
-#' xgb.importance(model = mbst, trees = seq(from=0, by=nclass, length.out=nrounds))
-#' xgb.importance(model = mbst, trees = seq(from=1, by=nclass, length.out=nrounds))
-#' xgb.importance(model = mbst, trees = seq(from=2, by=nclass, length.out=nrounds))
-#'
-#' # multiclass classification using gblinear:
-#' mbst <- xgboost(data = scale(as.matrix(iris[, -5])), label = as.numeric(iris$Species) - 1,
-#'                booster = "gblinear", eta = 0.2, nthread = 1, nrounds = 15,
-#'                objective = "multi:softprob", num_class = nclass)
+#' xgb.importance(
+#'   model = mbst, trees = seq(from = 0, by = nclass, length.out = nrounds)
+#' )
+#' xgb.importance(
+#'   model = mbst, trees = seq(from = 1, by = nclass, length.out = nrounds)
+#' )
+#' xgb.importance(
+#'   model = mbst, trees = seq(from = 2, by = nclass, length.out = nrounds)
+#' )
+#'
+#' # multiclass classification using "gblinear":
+#' mbst <- xgboost(
+#'   data = scale(as.matrix(iris[, -5])),
+#'   label = as.numeric(iris$Species) - 1,
+#'   booster = "gblinear",
+#'   eta = 0.2,
+#'   nthread = 1,
+#'   nrounds = 15,
+#'   objective = "multi:softprob",
+#'   num_class = nclass
+#' )
+#'
 #' xgb.importance(model = mbst)
 #'
 #' @export

R-package/R/xgb.model.dt.tree.R

@@ -1,57 +1,58 @@
-#' Parse a boosted tree model text dump
+#' Parse model text dump
 #'
-#' Parse a boosted tree model text dump into a \code{data.table} structure.
+#' Parse a boosted tree model text dump into a `data.table` structure.
 #'
-#' @param feature_names character vector of feature names. If the model already
-#'          contains feature names, those would be used when \code{feature_names=NULL} (default value).
-#'          Non-null \code{feature_names} could be provided to override those in the model.
-#' @param model object of class \code{xgb.Booster}
-#' @param text \code{character} vector previously generated by the \code{xgb.dump}
-#'          function  (where parameter \code{with_stats = TRUE} should have been set).
-#'          \code{text} takes precedence over \code{model}.
-#' @param trees an integer vector of tree indices that should be parsed.
-#'          If set to \code{NULL}, all trees of the model are parsed.
-#'          It could be useful, e.g., in multiclass classification to get only
-#'          the trees of one certain class. IMPORTANT: the tree index in xgboost models
-#'          is zero-based (e.g., use \code{trees = 0:4} for first 5 trees).
-#' @param use_int_id a logical flag indicating whether nodes in columns "Yes", "No", "Missing" should be
-#'          represented as integers (when FALSE) or as "Tree-Node" character strings (when FALSE).
-#' @param ... currently not used.
+#' @param feature_names Character vector used to overwrite the feature names
+#'        of the model. The default (`NULL`) uses the original feature names.
+#' @param model Object of class `xgb.Booster`.
+#' @param text Character vector previously generated by the function [xgb.dump()]
+#'        (called with parameter `with_stats = TRUE`). `text` takes precedence over `model`.
+#' @param trees An integer vector of tree indices that should be used.
+#'        The default (`NULL`) uses all trees.
+#'        Useful, e.g., in multiclass classification to get only
+#'        the trees of one class. *Important*: the tree index in XGBoost models
+#'        is zero-based (e.g., use `trees = 0:4` for the first five trees).
+#' @param use_int_id A logical flag indicating whether nodes in columns "Yes", "No", and
+#'        "Missing" should be represented as integers (when `TRUE`) or as "Tree-Node"
+#'        character strings (when `FALSE`, default).
+#' @param ... Currently not used.
 #'
 #' @return
-#' A \code{data.table} with detailed information about model trees' nodes.
+#' A `data.table` with detailed information about tree nodes. It has the following columns:
+#' - `Tree`: integer ID of a tree in a model (zero-based index).
+#' - `Node`: integer ID of a node in a tree (zero-based index).
+#' - `ID`: character identifier of a node in a model (only when `use_int_id = FALSE`).
+#' - `Feature`: for a branch node, a feature ID or name (when available);
+#'              for a leaf node, it simply labels it as `"Leaf"`.
+#' - `Split`: location of the split for a branch node (split condition is always "less than").
+#' - `Yes`: ID of the next node when the split condition is met.
+#' - `No`: ID of the next node when the split condition is not met.
+#' - `Missing`: ID of the next node when the branch value is missing.
+#' - `Quality`: either the split gain (change in loss) or the leaf value.
+#' - `Cover`: metric related to the number of observations either seen by a split
+#'            or collected by a leaf during training.
 #'
-#' The columns of the \code{data.table} are:
-#'
-#' \itemize{
-#'  \item \code{Tree}: integer ID of a tree in a model (zero-based index)
-#'  \item \code{Node}: integer ID of a node in a tree (zero-based index)
-#'  \item \code{ID}: character identifier of a node in a model (only when \code{use_int_id=FALSE})
-#'  \item \code{Feature}: for a branch node, it's a feature id or name (when available);
-#'              for a leaf note, it simply labels it as \code{'Leaf'}
-#'  \item \code{Split}: location of the split for a branch node (split condition is always "less than")
-#'  \item \code{Yes}: ID of the next node when the split condition is met
-#'  \item \code{No}: ID of the next node when the split condition is not met
-#'  \item \code{Missing}: ID of the next node when branch value is missing
-#'  \item \code{Quality}: either the split gain (change in loss) or the leaf value
-#'  \item \code{Cover}: metric related to the number of observation either seen by a split
-#'                      or collected by a leaf during training.
-#' }
-#'
-#' When \code{use_int_id=FALSE}, columns "Yes", "No", and "Missing" point to model-wide node identifiers
-#' in the "ID" column. When \code{use_int_id=TRUE}, those columns point to node identifiers from
+#' When `use_int_id = FALSE`, columns "Yes", "No", and "Missing" point to model-wide node identifiers
+#' in the "ID" column. When `use_int_id = TRUE`, those columns point to node identifiers from
 #' the corresponding trees in the "Node" column.
 #'
 #' @examples
 #' # Basic use:
 #'
-#' data(agaricus.train, package='xgboost')
+#' data(agaricus.train, package = "xgboost")
 #' ## Keep the number of threads to 1 for examples
 #' nthread <- 1
 #' data.table::setDTthreads(nthread)
 #'
-#' bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, max_depth = 2,
-#'                eta = 1, nthread = nthread, nrounds = 2,objective = "binary:logistic")
+#' bst <- xgboost(
+#'   data = agaricus.train$data,
+#'   label = agaricus.train$label,
+#'   max_depth = 2,
+#'   eta = 1,
+#'   nthread = nthread,
+#'   nrounds = 2,
+#'   objective = "binary:logistic"
+#' )
 #'
 #' (dt <- xgb.model.dt.tree(colnames(agaricus.train$data), bst))
 #'
@@ -60,8 +61,12 @@
 #' (dt <- xgb.model.dt.tree(model = bst))
 #'
 #' # How to match feature names of splits that are following a current 'Yes' branch:
-#'
-#' merge(dt, dt[, .(ID, Y.Feature=Feature)], by.x='Yes', by.y='ID', all.x=TRUE)[order(Tree,Node)]
+#' merge(
+#'   dt,
+#'   dt[, .(ID, Y.Feature = Feature)], by.x = "Yes", by.y = "ID", all.x = TRUE
+#' )[
+#'   order(Tree, Node)
+#' ]
 #'
 #' @export
 xgb.model.dt.tree <- function(feature_names = NULL, model = NULL, text = NULL,