XGBoost 回调构造函数 — xgb.Callback • xgboost

用于定义可在模型训练的不同阶段（训练前/后、每次提升迭代前/后）执行的回调函数结构的构造函数。

用法

xgb.Callback(
  cb_name = "custom_callback",
  env = new.env(),
  f_before_training = function(env, model, data, evals, begin_iteration, end_iteration)
    NULL,
  f_before_iter = function(env, model, data, evals, iteration) NULL,
  f_after_iter = function(env, model, data, evals, iteration, iter_feval) NULL,
  f_after_training = function(env, model, data, evals, iteration, final_feval,
    prev_cb_res) NULL
)

参数

cb_name

回调的名称。

如果回调产生非 NULL 结果（通过执行在 f_after_training 下传入的函数），该结果将作为 R 属性添加到生成的助推器（或作为 CV 结果中的命名元素），其属性名称在此处指定。

回调名称必须是唯一的——即不能有两个名称相同的回调。

env

一个将传递给回调中不同函数的环境对象。请注意，此环境不会与其他回调共享。

f_before_training

一个将在训练开始前执行的函数。

如果为此或其他函数输入传入 NULL，则不会执行任何函数。

如果传入一个函数，它将使用非命名参数调用，这些参数与每个函数参数的默认值中显示的函数签名匹配。

f_before_iter

一个将在每次提升轮次前执行的函数。

此函数可以通过输出一个评估为 TRUE 的值来指示训练是否应该结束——即，如果在给定轮次中此处提供的函数的输出为 TRUE，则训练将在当前迭代发生之前停止。

NULL 的返回值将被解释为 FALSE。

f_after_iter

一个将在每次提升轮次后执行的函数。

此函数可以通过输出一个评估为 TRUE 的值来指示训练是否应该结束——即，如果在给定轮次中此处提供的函数的输出为 TRUE，则训练将在该轮次停止。

NULL 的返回值将被解释为 FALSE。

f_after_training

一个将在训练结束后执行的函数。

此函数可以选择性地输出非 NULL 的内容，该内容将成为助推器 R 属性的一部分（假设将 keep_extra_attributes=TRUE 传递给 xgb.train()），在 xgb.train() 的情况下，其名称由参数 cb_name 提供；或者成为 xgb.cv() 结果中命名元素的一部分。

值

一个 xgb.Callback 对象，可以传递给 xgb.train() 或 xgb.cv()。

详细信息

将传递给所提供函数的参数如下：

env 作为参数 env 传入的相同环境。

它可能被函数修改，例如，用于跟踪迭代期间发生的情况或类似情况。

此环境仅由提供给回调的函数使用，并且在模型拟合函数终止后不会保留（参见参数 f_after_training）。
model 使用 xgb.train() 时的助推器对象，或使用 xgb.cv() 时的折叠。

对于 xgb.cv()，折叠是具有以下结构的一个列表：
- dtrain: 该折叠的训练数据（作为 xgb.DMatrix 对象）。
- bst: 该折叠的 xgb.Booster 对象。
- evals: 一个包含两个 DMatrix 的列表，名称分别为 train 和 test（test 是该折叠的保留数据）。
- index: 该折叠的保留数据的索引（从 1 开始索引），evals 中的 test 条目由此获得。
此对象不应以与训练冲突的方式进行原地修改（例如，以将轮数重置为零的方式重置训练更新的参数以覆盖轮数）。

请注意，在回调函数期间分配给助推器的任何 R 属性，此后将不会保留，因为助推器对象变量在训练期间不会重新分配。但是，可以通过 xgb.attr() 或 xgb.attributes() 设置助推器的 C 级属性，这些属性应在剩余的迭代和训练完成后仍然可用。

为了跨迭代保留变量，建议使用 env。
data 正在拟合模型的作为 xgb.DMatrix 对象的数据。

请注意，对于 xgb.cv()，这将是完整数据，而特定折叠的数据可以在 model 对象中找到。
evals 评估数据，作为参数 evals 传递给 xgb.train()。

对于 xgb.cv()，这将始终为 NULL。
begin_iteration 将要执行的第一个提升迭代的索引（从 1 开始索引）。

这通常是“1”，但当使用训练继续时，根据更新的参数，提升轮次将从前一个模型结束的位置继续，在这种情况下，这将大于 1。
end_iteration 将要执行的最后一个提升迭代的索引（从 1 开始索引，包括此结束）。

它应与传递给 xgb.train() 或 xgb.cv() 的参数 nrounds 匹配。

请注意，提升可能会在此最后一次迭代之前中断，例如通过使用提前停止回调 xgb.cb.early.stop()。
iteration 正在执行的迭代编号的索引（第一次迭代将与参数 begin_iteration 相同，然后下一次将加 1，依此类推）。
iter_feval 为所提供的 evals 计算的评估指标，由目标或参数 custom_metric 确定。

对于 xgb.train()，这将是一个命名向量，其中 evals 中的每个元素对应一个条目，名称由“evals name” + “-” + “metric name”确定——例如，如果 evals 包含名为“tr”的条目且指标为“rmse”，这将是一个名为“tr-rmse”的单元素向量。

对于 xgb.cv()，这将是一个二维矩阵，维度为 [length(evals), nfolds]，其中行名将遵循与 xgb.train() 中传入的一维向量相同的命名逻辑。

请注意，在内部，内置回调（例如 xgb.cb.print.evaluation）通过计算行均值和标准差来汇总此表。
final_feval 最后一次提升轮次执行后的评估结果（格式与 iter_feval 相同，并将是模型拟合期间执行的最后一轮中作为 iter_feval 传入的完全相同的输入）。
prev_cb_res 在进行训练继续时，如果助推器 R 属性中有任何相同名称（由参数 cb_name 给出）的回调的先前运行结果。

有时，可能希望将新结果附加到以前的结果，内置回调（例如 xgb.cb.evaluation.log）将自动完成此操作，它将新行附加到以前的表中。

如果没有此类先前的回调结果可用（在从头开始拟合模型而不是更新现有模型时永远不会有），这将为 NULL。

对于不支持训练继续的 xgb.cv()，这将始终为 NULL。

以下名称（cb_name 值）保留用于内部回调：

print_evaluation
evaluation_log
reset_parameters
early_stop
save_model
cv_predict
gblinear_history

以下名称保留用于其他非回调属性：

names
class
call
params
niter
nfeatures
folds

当使用内置的提前停止回调 (xgb.cb.early.stop) 时，该回调将始终在其他回调之前执行，因为它设置了一些其他回调可能也会使用的助推器 C 级属性。否则，执行顺序将与回调传递给模型拟合函数的顺序匹配。

另请参阅

内置回调

示例

# Example constructing a custom callback that calculates
# squared error on the training data (no separate test set),
# and outputs the per-iteration results.
ssq_callback <- xgb.Callback(
  cb_name = "ssq",
  f_before_training = function(env, model, data, evals,
                               begin_iteration, end_iteration) {
    # A vector to keep track of a number at each iteration
    env$logs <- rep(NA_real_, end_iteration - begin_iteration + 1)
  },
  f_after_iter = function(env, model, data, evals, iteration, iter_feval) {
    # This calculates the sum of squared errors on the training data.
    # Note that this can be better done by passing an 'evals' entry,
    # but this demonstrates a way in which callbacks can be structured.
    pred <- predict(model, data)
    err <- pred - getinfo(data, "label")
    sq_err <- sum(err^2)
    env$logs[iteration] <- sq_err
    cat(
      sprintf(
        "Squared error at iteration %d: %.2f\n",
        iteration, sq_err
      )
    )

    # A return value of 'TRUE' here would signal to finalize the training
    return(FALSE)
  },
  f_after_training = function(env, model, data, evals, iteration,
                              final_feval, prev_cb_res) {
    return(env$logs)
  }
)

data(mtcars)

y <- mtcars$mpg
x <- as.matrix(mtcars[, -1])

dm <- xgb.DMatrix(x, label = y, nthread = 1)
model <- xgb.train(
  data = dm,
  params = xgb.params(objective = "reg:squarederror", nthread = 1),
  nrounds = 5,
  callbacks = list(ssq_callback)
)

# Result from 'f_after_iter' will be available as an attribute
attributes(model)$ssq