拟合XGBoost模型 — xgb.train • xgboost

将XGBoost模型拟合到DMatrix格式的给定数据（例如，由xgb.DMatrix()生成的数据）。有关XGBoost功能的更详细解释，请参阅教程《增强树简介》，以及其他XGBoost教程，以了解XGBoost的特性和用法。

与用户友好的交互式函数xgboost()相比，xgb.train是一个更底层的接口，它允许更精细的控制并公开核心库提供的更多功能（例如学习排序目标），但它只与XGBoost自己的数据格式（“DMatrices”）一起使用，而不是常规的R对象。

此函数的语法与XGBoost Python包中的同名函数非常相似，建议包开发者使用它而不是xgboost()，因为它将提供一个更稳定的接口（更少破坏性更改）和更低的数据验证开销。

如果您是从XGBoost的1.x系列版本迁移过来，请参阅迁移指南。

用法

xgb.train(
  params = xgb.params(),
  data,
  nrounds,
  evals = list(),
  objective = NULL,
  custom_metric = NULL,
  verbose = 1,
  print_every_n = 1L,
  early_stopping_rounds = NULL,
  maximize = NULL,
  save_period = NULL,
  save_name = "xgboost.model",
  xgb_model = NULL,
  callbacks = list(),
  ...
)

参数

params

控制模型构建过程的XGBoost参数列表。详情请参阅在线文档和xgb.params()的文档。

应作为带有命名条目的列表传递。未在此列表中指定的参数将使用其默认值。

可以通过函数xgb.params()创建命名参数列表，该函数接受所有有效参数作为函数参数。

数据

训练数据集。xgb.train()只接受xgb.DMatrix作为输入。

请注意，有一个函数xgboost()旨在接受R数据对象作为输入，例如数据框和矩阵。

nrounds

最大增强迭代次数。

evals

用于评估模型性能的xgb.DMatrix数据集的命名列表。在每次增强迭代期间，将为每个数据集计算在eval_metric（在params下）或custom_metric（此处为函数参数）中指定的指标，并最终作为名为evaluation_log的字段存储在结果对象中。

当verbose>=1或xgb.cb.print.evaluation()回调函数启用时，性能结果将在训练期间持续打印出来。

例如，指定evals=list(validation1=mat1, validation2=mat2)可以跟踪每轮模型在mat1和mat2上的性能。

objective

自定义目标函数。应接受两个参数：第一个是当前预测（根据目标/类别数量，可以是数值向量或矩阵），第二个是用于训练的data DMatrix对象。

它应返回一个包含两个元素grad和hess（按此顺序）的列表，根据目标/类别数量，可以是数值向量或数值矩阵（与作为第一个参数传递的预测维度相同）。

custom_metric

自定义评估函数。与objective一样，应接受两个参数，第一个是预测，第二个是data DMatrix。

应返回一个包含两个元素metric（将为此指标显示的名称，应为字符串/字符）和value（函数计算的数字，应为数值标量）的列表。

请注意，即使传递了custom_metric，目标也有一个关联的默认指标，除了它之外也会进行评估。为了禁用内置指标，可以传递参数disable_default_eval_metric = TRUE。

verbose

如果为0，xgboost将保持静默。如果为1，它将打印有关性能的信息。如果为2，将打印一些额外信息。请注意，设置verbose > 0会自动启用xgb.cb.print.evaluation(period=1)回调函数。

print_every_n

当传递verbose>0时，评估日志（在evals下传递的数据上计算的指标）将根据此处传递的值每n次迭代打印一次。无论此'n'如何，第一次和最后一次迭代始终包含在内。

仅当在evals下传递数据且传递verbose>0时才有效。该参数传递给xgb.cb.print.evaluation()回调函数。

early_stopping_rounds

在evals下传递的评估数据上，如果性能（由提供的或目标默认选择的评估指标衡量）没有改善，训练将在此轮次后停止。此参数表示停止前的最大增强轮次。

必须传递evals才能使用此功能。设置此参数将添加xgb.cb.early.stop()回调函数。

如果为NULL，则不使用提前停止。

maximize

如果设置了feval和early_stopping_rounds，则也必须设置此参数。当其为TRUE时，表示评估分数越大越好。此参数传递给xgb.cb.early.stop()回调函数。

save_period

当不为NULL时，模型将在每save_period轮后保存到磁盘。0表示在结束时保存。保存由xgb.cb.save.model()回调函数处理。

save_name

周期性保存模型文件的名称或路径。

xgb_model

一个先前构建的模型，用于继续训练。可以是xgb.Booster类的对象，或者其原始数据，或者是先前保存模型的文件名。

callbacks

在增强过程中执行各种任务的回调函数列表。请参阅xgb.Callback()。根据参数值，会自动创建一些回调函数。用户可以提供现有或自己的回调方法来自定义训练过程。

请注意，某些回调可能会尝试在结果模型对象中保留属性，例如评估日志（一个data.table对象）——请注意，这些对象作为R属性保留，因此在使用XGBoost自己的序列化器（如xgb.save()）时不会保存（但在使用R序列化器（如saveRDS()）时会保留）。

...

未使用。

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

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

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

值

一个xgb.Booster类的对象。

详细信息

与xgboost()相比，xgb.train()接口支持高级功能，如evals、自定义目标和评估指标函数等，区别在于它们与xgb.DMatrix对象一起工作，并且不遵循典型的R习惯用法。

如果存在OpenMP，并行化将自动启用。线程数也可以通过nthread参数手动指定。

在XGBoost语言绑定中，默认随机种子默认为零，但在R中，如果未手动提供参数seed，它将通过R自己的随机数生成器生成一个随机种子，该生成器的种子又可通过set.seed控制。如果传递了seed，它将覆盖R中的RNG。

当设置某些参数时，会自动创建以下回调

当verbose > 0且print_every_n参数传递给它时，xgb.cb.print.evaluation()被开启。
当evals存在时，xgb.cb.evaluation.log()被开启。
xgb.cb.early.stop()：当设置early_stopping_rounds时。
xgb.cb.save.model()：当设置save_period > 0时。

请注意，此函数返回的xgb.Booster类型的对象与典型的R对象行为略有不同（它是一个“altrep”列表类），并且它将内部助推器属性（限于可JSON化的数据）与R特有属性（通常是回调的结果）分离。内部助推器属性通过xgb.attr()访问，并通过xgb.save()等序列化函数在接口之间共享；R特有属性通过attributes()和attr()访问，仅在R接口中使用，仅在使用R的序列化器（如saveRDS()）时保留，并且不被predict.xgb.Booster()等函数使用。

请注意，一个自动添加的R属性是params——此属性从该函数的params参数分配，仅作为助推器输入的参考，但在接受助推器对象的其他方法中不使用——因此，例如，更改助推器的配置需要调用xgb.config<-或xgb.model.parameters<-，而简单地修改attributes(model)$params$<...>在其他地方将无效。

参考文献

Tianqi Chen 和 Carlos Guestrin，《XGBoost: A Scalable Tree Boosting System》，第22届SIGKDD知识发现和数据挖掘会议，2016年，https://arxiv.org/abs/1603.02754

另请参阅

xgb.Callback(), predict.xgb.Booster(), xgb.cv()

示例

data(agaricus.train, package = "xgboost")
data(agaricus.test, 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)
)
dtest <- with(
  agaricus.test, xgb.DMatrix(data, label = label, nthread = nthread)
)
evals <- list(train = dtrain, eval = dtest)

## A simple xgb.train example:
param <- xgb.params(
  max_depth = 2,
  nthread = nthread,
  objective = "binary:logistic",
  eval_metric = "auc"
)
bst <- xgb.train(param, dtrain, nrounds = 2, evals = evals, verbose = 0)

## An xgb.train example where custom objective and evaluation metric are
## used:
logregobj <- function(preds, dtrain) {
   labels <- getinfo(dtrain, "label")
   preds <- 1/(1 + exp(-preds))
   grad <- preds - labels
   hess <- preds * (1 - preds)
   return(list(grad = grad, hess = hess))
}
evalerror <- function(preds, dtrain) {
  labels <- getinfo(dtrain, "label")
  err <- as.numeric(sum(labels != (preds > 0)))/length(labels)
  return(list(metric = "error", value = err))
}

# These functions could be used by passing them as 'objective' and
# 'eval_metric' parameters in the params list:
param <- xgb.params(
  max_depth = 2,
  nthread = nthread,
  objective = logregobj,
  eval_metric = evalerror
)
bst <- xgb.train(param, dtrain, nrounds = 2, evals = evals, verbose = 0)

# ... or as dedicated 'objective' and 'custom_metric' parameters of xgb.train:
bst <- xgb.train(
  within(param, rm("objective", "eval_metric")),
  dtrain, nrounds = 2, evals = evals,
  objective = logregobj, custom_metric = evalerror
)


## An xgb.train example of using variable learning rates at each iteration:
param <- xgb.params(
  max_depth = 2,
  learning_rate = 1,
  nthread = nthread,
  objective = "binary:logistic",
  eval_metric = "auc"
)
my_learning_rates <- list(learning_rate = c(0.5, 0.1))

bst <- xgb.train(
 param,
 dtrain,
 nrounds = 2,
 evals = evals,
 verbose = 0,
 callbacks = list(xgb.cb.reset.parameters(my_learning_rates))
)

## Early stopping:
bst <- xgb.train(
  param, dtrain, nrounds = 25, evals = evals, early_stopping_rounds = 3
)