从早期XGBoost版本迁移代码

XGBoost 的 R 语言绑定在 1.x 和 2.x 版本之间有很大的破坏性更改。之前使用 XGBoost 版本的 R 代码可能需要修改才能在新版本中运行。本指南概述了主要区别。

• 函数 xgboost()

  • 以前，此函数接受参数“data”和“label”，现在已分别重命名为“x”和“y”，与其他流行的 R 包保持一致。

  • 以前，现在是“x”的“data”参数必须作为 XGBoost 的“DMatrix”或 R 矩阵传递。现在，该参数允许 R data.frames、矩阵和来自“Matrix”包的稀疏矩阵，但不允许 XGBoost 自己的 DMatrix。当传递 data.frame 时，将根据列的类型推断分类列。

  • 以前，现在是“y”的“label”数据必须按照 XGBoost 核心库使用的格式编码后传递给 xgboost() — 这意味着：二元变量必须编码为 0/1，生存目标边界必须作为不同的参数传递等等。在最新版本中，“y”现在无需事先手动编码：它应该作为相应类的 R 对象传递，就像基础 R 和核心 R 包中用于相应 XGBoost 目标的回归函数一样 — 例如，分类问题应该传递 factor，生存问题传递 Surv，回归问题传递数值向量等等。学习排序不被 xgboost() 支持，但被 xgb.train 支持。

  • 以前，xgboost() 接受 params 参数和 ... 下的命名参数。现在所有训练参数都应作为命名参数传递，并且所有接受的参数都是具有包内文档的显式函数参数。某些参数不允许，因为它们是根据其余数据自动确定的，例如多类别分类的类别数量是根据“y”自动确定的。此外，具有同义词或在不同可能参数下接受的参数（例如“eta”和“learning_rate”）现在只接受其更具描述性的形式（因此不接受“eta”，但接受“learning_rate”）。

  • 此函数 xgboost() 生成的模型现在返回一个不同的类“xgboost”，它是“xgb.Booster”的子类，但具有更多元数据和具有不同默认值的 predict 方法。

  • 此函数 xgboost() 现在仅用于交互式使用。对于希望集成 XGBoost 包的包开发者，强烈建议改用 xgb.train，这是一个低级函数，它密切模仿 Python 包中的相同函数，并且旨在减少破坏性更改。

• 函数 xgb.train()

  • 以前，xgb.train() 允许在“params”列表和 ... 下作为命名参数传递参数。现在，所有训练参数都应在 params 下传递。

  • 为了更容易发现和传递参数，现在有一个函数 xgb.params，它可以生成一个列表以传递给 params 参数。xgb.params 只是一个具有命名参数的函数，列出了 xgb.train 接受的所有内容，并为所有参数提供包内文档，返回一个简单的命名列表。

  • 旨在由 DMatrix 构造函数使用的参数必须直接传递给 xgb.DMatrix（例如，用于分类特征或特征名称的参数）。

  • 某些参数已重命名（例如，以前的“watchlist”现在是“evals”，与 Python 包保持一致）。

  • 传递给 xgb.train 的回调格式已大量重写。有关详细信息，请参阅 xgb.Callback 的文档。

• 函数 xgb.DMatrix()

  • 此函数现在接受“data.frame”输入，并根据其类型确定哪些特征是分类的 — 任何类型为“factor”或“character”的都将被视为分类。请注意，当将数据传递给“predict”方法时，“factor”变量必须具有相同的编码（即相同的级别），因为 XGBoost 不会为您重新编码它们。

  • 以前，一些参数（例如特征类型）必须作为列表在参数“info”下传递，而现在它们都直接是“xgb.DMatrix”的函数参数。

  • 现在有其他类型的 DMatrix 构造函数可能更适合某些用例 — 例如，有“xgb.QuantileDMatrix”，它将立即量化特征（因此避免冗余复制并减少内存消耗），用于 XGBoost 中的直方图方法（但请注意，量化 DMatrix 不能与“exact”排序索引方法一起使用）。

  • 请注意，“label”数据仍需以核心 XGBoost 库使用的格式进行编码 — 例如，分类目标应接收编码为零和一的“label”数据。

  • 已弃用从文本文件创建 DMatrix。

• 函数 xgb.cv()

  • 虽然以前此函数与旧的 xgboost() 类似地接受“data”和“label”，但现在它只接受 xgb.DMatrix 对象。

  • 该函数的作用域已扩展，以支持 XGBoost 提供的更多功能，例如生存和学习排序目标。

• 方法 predict

  • 现在有两种预测方法，根据模型是通过 xgboost() 还是 xgb.train() 产生的，具有不同的默认参数。xgboost() 函数更倾向于交互式使用，因此此类对象（“xgboost”类）上的“predict”方法的默认值将默认执行更多数据验证，例如检查列名是否匹配，否则重新排序。通过 xgb.train() 创建的模型（“xgb.Booster”类）的“predict”方法具有与以前相同的默认值，因此例如，它在默认行为下不会重新排序列以匹配名称。

  • “xgboost”类对象（由 xgboost() 产生，而非由 xgb.train() 产生）的“predict”方法现在可以通过参数 type 控制预测类型，类似于基础 R 的“stats”模块中的“predict”方法 — 例如，现在可以执行 predict(model, type="class")；而“xgb.Booster”对象（由 xgb.train() 产生）的“predict”方法，就像以前一样，通过单独的参数（例如 outputmargin）控制这些。

  • 以前，使用部分树进行预测时，采用基于 0 的索引和模仿 Python 范围的范围语法，而现在它们使用 R 中常见的基于 1 的索引，并且它们的范围行为与 R 的 seq 函数的范围行为匹配。请注意，“使用所有树”和“使用直到早停标准的树”的语法已更改（详见文档）。

• Booster 对象

  • 这些对象的结构已被修改 — 现在它们被表示为一个简单的 R“ALTLIST”（一种特殊的“list”对象），并带有额外的属性。

  • 这些对象现在不能通过向其添加更多字段来修改，但可以将其元数据作为属性添加。

  • 这些对象区分两种类型的属性

    • R 端属性（可以通过 R 函数 attributes(model) 和 attributes(model)$field <- val 访问和修改），允许任意对象。许多属性由模型构建函数自动添加，例如评估日志（一个 data.table，其中包含每个迭代计算的指标），这些以前是模型字段。

    • C 级属性，只允许符合 JSON 的数据，可以通过函数 xgb.attributes(model) 访问和设置。这些 C 级属性可以通过不同 XGBoost 接口中的序列化模型共享，而 R 级属性是 R 接口特有的。XGBoost 语言绑定中一些标准的属性，例如最佳迭代，作为 C 属性保留。

  • 以前，刚从磁盘格式反序列化的模型需要调用其上的“xgb.Booster.complete”方法才能完成完整的反序列化过程才能使用，否则会在首次调用“predict”时自动调用此方法。现在序列化处理得更优雅，不再涉及额外的函数/方法 — 也就是说，如果使用 saveRDS() 将模型保存到磁盘，然后使用 readRDS() 读回，模型将立即完全加载，无需在其上调用额外的方法。

其他建议

默认情况下，XGBoost 可能会识别出某些参数已从早期版本中删除或重命名，并且仍然接受与以前使用重命名或删除的参数时相同的函数调用，但在此过程中会发出弃用警告，突出显示更改。

这些行为将在未来版本中移除，目前返回弃用警告的函数调用将在未来停止工作，因此为了确保调用 XGBoost 的代码仍然可以运行，应确保它不会发出弃用警告。

可选地，可以通过选项“xgboost.strict_mode”将这些弃用警告转换为错误（同时仍将其他类型的警告保留为警告）— 示例：.. code-block:: r

options(“xgboost.strict_mode” = TRUE)

它也可以通过环境变量 XGB_STRICT_MODE=1 来控制，该变量优先于 R 选项 — 例如：.. code-block:: r

Sys.setenv(“XGB_STRICT_MODE” = “1”)

强烈建议包开发者在他们的包检查期间启用此选项，以确保与 XGBoost 更好的兼容性。