跳到内容

构建 xgb.DMatrix 对象

来源: R/xgb.DMatrix.R
xgb.DMatrix.Rd

从给定数据源构建一个 'xgb.DMatrix' 对象，该对象可以传递给函数，例如 xgb.train() 或 predict()。

用法

xgb.DMatrix(
  data,
  label = NULL,
  weight = NULL,
  base_margin = NULL,
  missing = NA,
  silent = FALSE,
  feature_names = colnames(data),
  feature_types = NULL,
  nthread = NULL,
  group = NULL,
  qid = NULL,
  label_lower_bound = NULL,
  label_upper_bound = NULL,
  feature_weights = NULL,
  data_split_mode = "row",
  ...
)

xgb.QuantileDMatrix(
  data,
  label = NULL,
  weight = NULL,
  base_margin = NULL,
  missing = NA,
  feature_names = colnames(data),
  feature_types = NULL,
  nthread = NULL,
  group = NULL,
  qid = NULL,
  label_lower_bound = NULL,
  label_upper_bound = NULL,
  feature_weights = NULL,
  ref = NULL,
  max_bin = NULL
)

参数

data

用于创建 DMatrix 的数据源，创建的 DMatrix 可用于拟合模型或从已拟合模型中获取预测结果。

支持的输入类型如下：

  • matrix 对象，类型为 numeric、integer 或 logical。

  • data.frame 对象，列类型为 numeric、integer、logical 或 factor

请注意，xgboost 对分类类型使用基于 0 的编码，因此 factor 类型（使用基于 1 的编码）会在函数调用内部进行转换。请注意，factor 类型的编码不会作为模型的一部分保存，因此在后续调用 predict 时，用户有责任确保因子列具有与构建 DMatrix 时相同的水平（levels）。

不支持其他列类型。

  • CSR 矩阵，来自 Matrix 包的 dgRMatrix 类。

  • CSC 矩阵，来自 Matrix 包的 dgCMatrix 类。

xgb.QuantileDMatrix 不支持这些类型。

  • XGBoost 自己的 DMatrix 二进制格式，由 xgb.DMatrix.save() 生成。

  • 单行 CSR 矩阵，来自 Matrix 包的 dsparseVector 类，将其解释为单行（仅在使用已拟合模型进行预测时）。

label

训练数据的标签。对于分类问题，应将其编码为从零开始计数的整数。

weight

每个实例的权重。

请注意，对于排序任务，权重是按组计算的。在排序任务中，权重分配给每个组（而不是每个数据点）。这是因为我们只关心每个组内数据点的相对顺序，因此为单个数据点分配权重没有意义。

base_margin

用于从现有模型进行提升的基础裕度（base margin）。

对于多输出模型，也可以传递多维度的 base_margin。

missing

一个浮点值，用于表示数据中的缺失值（从文本文件创建 DMatrix 时不使用）。当数据中的零、无穷大或某些其他极端值表示缺失值时，此参数很有用。

silent

是否在从文件加载后抑制打印信息性消息。

feature_names

设置特征名称。会覆盖数据框和矩阵中的列名。

注意：在调用 predict 时，不会按名称引用列，因此无论列名如何，其中的列顺序必须与构建 DMatrix 时的列顺序相同。

feature_types

设置特征类型。

如果 data 是 data.frame 且未提供 feature_types，则特征类型将根据列类型自动推断。

否则，可以传递一个与 data 中的列数长度相同的字符向量，其可能的值如下：

  • "c"，表示分类列。

  • "q"，表示数值列。

  • "int"，表示整数列。

  • "i"，表示逻辑（布尔）列。

请注意，虽然分类类型在模型拟合时与其他类型不同处理，但其他类型不影响生成的模型，只对特征重要性等其他功能产生影响。

重要：分类特征，如果通过 feature_types 手动指定，必须编码为从零开始计数的整数，并且将数据传递给 predict() 时需要应用相同的编码。即使传递 factor 类型，编码也不会保存，因此请确保传递给 predict 的 factor 列具有相同的 levels。

nthread

用于创建 DMatrix 的线程数。

group

所有排序组的组大小。

qid

数据样本的查询 ID，用于排序。

label_lower_bound

生存训练的下界。

label_upper_bound

生存训练的上界。

feature_weights

设置列采样的特征权重。

data_split_mode

尚未使用。此参数用于分布式训练，目前 R 包尚不支持。

...

未使用。

之前 XGBoost 版本中属于此函数的一些参数目前已弃用或已重命名。如果传递了弃用或重命名的参数，将抛出警告（默认情况下），并使用其当前等效参数。如果在 '严格模式' 选项下使用，此警告将变为错误。

如果传递了既不是当前函数参数也不是弃用或重命名参数的其他参数，则会根据“严格模式”选项抛出警告或错误。

重要： ... 在未来版本中将被移除，并且所有当前的弃用警告都将变为错误。请仅使用函数签名中包含的参数。

ref

提供分位数信息的训练数据集，在创建 xgb.QuantileDMatrix() 的验证/测试数据集时需要。将训练 DMatrix 作为参考意味着应用于训练数据的相同分位数化将应用于验证/测试数据

max_bin

直方图 bin 的数量，应与训练参数 max_bin 保持一致。

仅在构建 QuantileDMatrix 时支持此参数。

值

一个 'xgb.DMatrix' 对象。如果调用 xgb.QuantileDMatrix，它将具有额外的子类 xgb.QuantileDMatrix。

详情

函数 xgb.QuantileDMatrix() 将构建一个已经应用了直方图方法量化的 DMatrix，在使用直方图方法（tree_method = "hist"，这是默认算法）时，这可以减少内存使用（与先使用常规 DMatrix 再对其进行量化相比），但不能用于排序索引方法（tree_method = "exact"）或近似方法（tree_method = "approx"）。

请注意，DMatrix 对象不能通过 R 函数序列化，例如 saveRDS() 或 save()。如果 DMatrix 被序列化然后反序列化（例如，在 R 会话中保存数据或在 Rmd 文件中缓存块时），结果对象将无法再使用，需要从原始数据源重新构建。

示例

data(agaricus.train, package = "xgboost")

## Keep the number of threads to 1 for examples
nthread <- 1
data.table::setDTthreads(nthread)
dtrain <- with(
  agaricus.train, xgb.DMatrix(data, label = label, nthread = nthread)
)
fname <- file.path(tempdir(), "xgb.DMatrix.data")
xgb.DMatrix.save(dtrain, fname)
dtrain <- xgb.DMatrix(fname, nthread = 1)