XGB-14:DMatrix的文本输入格式

简要描述XGBoost的文本输入格式。然而，对于具有支持的语言环境（如Python或R）的用户，建议使用该生态系统中的数据解析器。例如，可以使用sklearn.datasets.load_svmlight_file()。

基本输入格式

XGBoost目前支持两种文本格式的数据导入：LIBSVM和CSV。本文档的其余部分将描述LIBSVM格式（有关CSV格式的描述，请参见此Wikipedia文章）。请注意，XGBoost不理解文件扩展名，也不尝试猜测文件格式，因为关于LIBSVM或CSV文件扩展名的普遍协议不存在。相反，它使用URI格式来指定精确的输入文件类型。例如，如果提供一个csv文件./data.train.csv作为输入，XGBoost将盲目地使用默认的LIBSVM解析器对其进行解析并生成解析器错误。相反，用户需要提供一个形如train.csv?format=csv或train.csv?format=libsvm的URI。对于外部内存输入，URI的形式应该类似于train.csv?format=csv#dtrain.cache。

对于训练或预测，XGBoost接受以下格式的实例文件train.txt：

1 101:1.2 102:0.03
0 1:2.1 10001:300 10002:400
0 0:1.3 1:0.3
1 0:0.01 1:0.3
0 0:0.2 1:0.3

每一行表示一个单独的实例，在第一行中，‘1’是实例标签，‘101’和‘102’是特征索引，‘1.2’和‘0.03’是特征值。在二分类情况下，‘1’用于表示正样本，‘0’用于表示负样本。还支持在 [0,1] 范围内的概率值作为标签，以表示该实例为正样本的概率。

附加信息的辅助文件

群组输入格式：

对于排序任务，XGBoost支持群组输入格式。在排序任务中，实例在实际场景中被分类到查询群组中。例如，在学习对网页进行排序的情况下，网页实例按其查询进行分组。XGBoost需要一个文件来指示群组信息。例如，如果实例文件是上面显示的train.txt，则群组文件应命名为train.txt.group，并具有以下格式：

2
3

这意味着数据集包含5个实例，前两个实例属于一组，另外三个实例属于另一组。群组文件中的数字实际上表示实例文件中每组中实例的数量，按照它们在实例文件中的顺序。在配置时，无需指定群组文件的路径。如果实例文件名为xxx，XGBoost将检查同一目录中是否存在名为xxx.group的文件。

实例权重文件

训练数据中的实例可以被赋予权重，以区分它们之间的相对重要性。例如，如果为示例中的train.txt文件提供一个实例权重文件train.txt.weight，如下所示：

1
0.5
0.5
1
0.5

这意味着XGBoost在训练时将更加强调第一个和第四个实例（即正实例）。配置与配置组信息类似。如果实例文件名为xxx，XGBoost将在同一目录中查找名为xxx.weight的文件。如果文件存在，将在训练时提取并使用实例权重。

注意：

如果选择将训练数据保存为二进制缓冲区（使用save_binary()），请注意生成的二进制缓冲区文件将包括实例权重。要更新权重，请使用set_weight()函数。

初始边界文件

XGBoost支持为每个实例提供初始边际预测。例如，如果使用逻辑回归对train.txt文件进行了初始预测，可以创建以下文件train.txt.base_margin：

-0.4
1.0
3.4

XGBoost将使用这些值作为初始边际预测并从中提升。关于base_margin的一个重要说明是，它应该是转换之前的边际预测，因此如果使用的是对数损失，需要使用对数变换之前的值。如果正在使用XGBoost预测器，请使用pred_margin=1来输出边际值。

嵌入附加信息到 LIBSVM 文件中

此部分适用于单节点和多节点设置。

查询 ID 列

这对于排名任务非常有用，其中实例被分组成查询组。可以通过在每一行中添加形如 qid:xx 的标记，将每个实例的查询组 ID 嵌入到 LIBSVM 文件中train.txt：

1 qid:1 101:1.2 102:0.03
0 qid:1 1:2.1 10001:300 10002:400
0 qid:2 0:1.3 1:0.3
1 qid:2 0:0.01 1:0.3
0 qid:3 0:0.2 1:0.3
1 qid:3 3:-0.1 10:-0.3
0 qid:3 6:0.2 10:0.15

注意以下限制：

• 不允许仅为某些实例指定查询 ID，而对其他实例不指定。要么每一行都分配查询 ID，要么完全不分配。
• 行必须按查询 ID 升序排序。例如，不能使一行的查询 ID 比以下任何一行都大。

实例权重

可以通过在 LIBSVM 文件中将每个实例标签与相应的权重一起附加来指定实例权重[label]:[weight]，如下例所示train.txt：

1:1.0 101:1.2 102:0.03
0:0.5 1:2.1 10001:300 10002:400
0:0.5 0:1.3 1:0.3
1:1.0 0:0.01 1:0.3
0:0.5 0:0.2 1:0.3

其中负实例的权重是正实例权重的一半。