跳到内容

构造 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
)

参数

数据

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

支持的输入类型如下：

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

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

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

不支持其他列类型。

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

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

这些不受 xgb.QuantileDMatrix 支持。

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

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

标签

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

权重

每个实例的权重。

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

基本边距

从现有模型进行提升所使用的基本边距。

在多输出模型的情况下，也可以传递多维基本边距。

缺失值

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

静默模式

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

特征名称

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

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

特征类型

设置特征类型。

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

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

  • "c"，表示分类列。

  • "q"，表示数值列。

  • "int"，表示整数列。

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

请注意，虽然分类类型在模型拟合目的方面与其他类型不同，但其他类型不影响生成的模型，但在特征重要性等其他功能中会产生影响。

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

线程数

用于创建 DMatrix 的线程数。

组

所有排名组的组大小。

查询 ID

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

标签下限

生存训练的下限。

标签上限

生存训练的上限。

特征权重

设置列采样的特征权重。

数据分割模式

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

...

未使用。

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

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

重要： ... 将在未来版本中删除，所有当前的弃用警告将变为错误。请仅使用构成函数签名的参数。

引用

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

最大 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)