DMatrix 是 XGBoost 使用的所有算法（包括训练、预测和解释）的基本数据存储。DMatrix 有几种变体，包括正常的 DMatrix（即 CSR 矩阵）、用于节省内存的基于直方图的树方法的 QuantileDMatrix，以及最后一个实验性的基于外部内存的 DMatrix，它在训练期间分批读取数据。后两种变体请参阅 Streaming 组。更多...

DMatrix 的协作图

模块
	流式传输
	分位数 DMatrix 和外部内存 DMatrix 可以从批量数据创建。

函数
int	XGDMatrixCreateFromFile (const char fname, int silent, DMatrixHandle out)
	加载一个数据矩阵更多...

int	XGDMatrixCreateFromURI (char const config, DMatrixHandle out)
	加载一个数据矩阵更多...

int	XGDMatrixCreateFromColumnar (char const data, char const config, DMatrixHandle *out)
	从列式数据创建 DMatrix。 (表) 更多...

int	XGDMatrixCreateFromCSR (char const indptr, char const indices, char const data, bst_ulong ncol, char const config, DMatrixHandle *out)
	从 CSR 矩阵创建 DMatrix。更多...

int	XGDMatrixCreateFromDense (char const data, char const config, DMatrixHandle *out)
	从密集数组创建 DMatrix。更多...

int	XGDMatrixCreateFromCSC (char const indptr, char const indices, char const data, bst_ulong nrow, char const config, DMatrixHandle *out)
	从 CSC 矩阵创建 DMatrix。更多...

int	XGDMatrixCreateFromMat (const float data, bst_ulong nrow, bst_ulong ncol, float missing, DMatrixHandle out)
	从密集矩阵创建矩阵内容更多...

int	XGDMatrixCreateFromMat_omp (const float data, bst_ulong nrow, bst_ulong ncol, float missing, DMatrixHandle out, int nthread)
	从密集矩阵创建矩阵内容更多...

int	XGDMatrixCreateFromCudaColumnar (char const data, char const config, DMatrixHandle *out)
	从 CUDA 列式格式创建 DMatrix。 (cuDF) 更多...

int	XGDMatrixCreateFromCudaArrayInterface (char const data, char const config, DMatrixHandle *out)
	从 CUDA 数组创建 DMatrix。更多...

int	XGDMatrixSliceDMatrix (DMatrixHandle handle, const int idxset, bst_ulong len, DMatrixHandle out)
	从现有矩阵的切片内容创建新的 dmatrix 更多...

int	XGDMatrixSliceDMatrixEx (DMatrixHandle handle, const int idxset, bst_ulong len, DMatrixHandle out, int allow_groups)
	从现有矩阵的切片内容创建新的 dmatrix 更多...

int	XGDMatrixFree (DMatrixHandle handle)
	释放数据矩阵中的空间更多...

int	XGDMatrixSaveBinary (DMatrixHandle handle, const char *fname, int silent)
	将 DMatrix 对象保存到文件。不支持 `QuantileDMatrix` 和外部内存 DMatrix。更多...

int	XGDMatrixSetInfoFromInterface (DMatrixHandle handle, char const field, char const data)
	将接口中的内容设置为信息中的内容。更多...

int	XGDMatrixSetFloatInfo (DMatrixHandle handle, const char field, const float array, bst_ulong len)
	将浮点向量设置为信息中的内容更多...

int	XGDMatrixSetUIntInfo (DMatrixHandle handle, const char field, const unsigned array, bst_ulong len)

int	XGDMatrixSetStrFeatureInfo (DMatrixHandle handle, const char field, const char *features, const bst_ulong size)
	设置所有特征的字符串编码信息。更多...

int	XGDMatrixGetStrFeatureInfo (DMatrixHandle handle, const char field, bst_ulong size, const char ***out_features)
	获取所有特征的字符串编码信息。更多...

int	XGDMatrixSetDenseInfo (DMatrixHandle handle, const char field, void const data, bst_ulong size, int type)

int	XGDMatrixGetFloatInfo (const DMatrixHandle handle, const char field, bst_ulong out_len, const float **out_dptr)
	从矩阵获取浮点信息向量。更多...

int	XGDMatrixGetUIntInfo (const DMatrixHandle handle, const char field, bst_ulong out_len, const unsigned **out_dptr)
	从矩阵获取 uint32 信息向量更多...

int	XGDMatrixNumRow (DMatrixHandle handle, bst_ulong *out)
	获取行数。更多...

int	XGDMatrixNumCol (DMatrixHandle handle, bst_ulong *out)
	获取列数更多...

int	XGDMatrixNumNonMissing (DMatrixHandle handle, bst_ulong *out)
	从 DMatrix 获取有效值的数量。更多...

int	XGDMatrixDataSplitMode (DMatrixHandle handle, bst_ulong *out)
	从 DMatrix 获取数据分割模式。更多...

int	XGDMatrixGetDataAsCSR (DMatrixHandle const handle, char const config, bst_ulong out_indptr, unsigned out_indices, float out_data)
	以 CSR 矩阵形式获取 DMatrix 的预测值（用于测试）。如果是量化 DMatrix，则返回量化值。更多...

int	XGDMatrixGetQuantileCut (DMatrixHandle const handle, char const config, char const out_indptr, char const *out_data)
	导出用于训练基于直方图的模型（如 `hist` 和 `approx`）的分位数截断值。对模型压缩很有用。更多...

详细描述

DMatrix 是 XGBoost 使用的所有算法（包括训练、预测和解释）的基本数据存储。DMatrix 有几种变体，包括正常的 DMatrix（即 CSR 矩阵）、用于节省内存的基于直方图的树方法的 QuantileDMatrix，以及最后一个实验性的基于外部内存的 DMatrix，它在训练期间分批读取数据。后两种变体请参阅 Streaming 组。

函数文档

◆ XGDMatrixCreateFromColumnar()

int XGDMatrixCreateFromColumnar	(	char const *	数据,
		char const *	config,
		DMatrixHandle *	out
	)

从列式数据创建 DMatrix。（表格）

DMatrix 的一种特殊输入类型是列式格式，它指的是基于列的数据框。XGBoost 可以接受整数和浮点数等数值数据类型，以及称为字典（在 arrow 的术语中）的分类类型。分类类型的添加在 3.1.0 中引入。数据框由列表数组接口表示，每个列对应一个对象。

分类类型由 3 个缓冲区表示：有效性掩码、类别名称（在大多数数据框实现中称为索引）以及用于在行中表示类别的代码。XGBoost 通过接受列表中的两个 JSON 编码的 arrow 数组来消耗分类列。列表中的第一个项是一个 JSON 对象，包含 {"offsets": IntegerArray, "values": StringArray }，表示 arrow 列式格式定义的字符串名称。第二个缓冲区是带掩码的整数数组，它存储类别代码以及有效性掩码。

[
// 分类列，表示为一个数组（列表）
  [
    {
'offsets'
      {
'data': (129412626415808, True),
'typestr': '<i4', 'version': 3, 'strides': None, 'shape': (3,), 'mask': None
      },
'values'
      {
'data': (129412626416000, True),
'typestr': '<i1', 'version': 3, 'strides': None, 'shape': (7,), 'mask': None
      }
    },
    {
'data': (106200854378448, True),
'typestr': '<i1', 'version': 3, 'strides': None, 'shape': (2,), 'mask': None
    }
  ],
// 数值列，表示为一个对象，行数与上一列（2）相同
  {
'data': (106200854378448, True),
'typestr': '<f4', 'version': 3, 'strides': None, 'shape': (2,), 'mask': None
  }
]

至于数值输入，它们与密集数组相同。

参数

数据	JSON 编码的数组接口列表。
config	有关详细信息，请参阅 XGDMatrixCreateFromDense。
out	创建的 DMatrix。

返回: 成功返回 0，失败返回 -1

◆ XGDMatrixCreateFromCSC()

int XGDMatrixCreateFromCSC	(	char const *	indptr,
		char const *	indices,
		char const *	数据,
		bst_ulong	nrow,
		char const *	config,
		DMatrixHandle *	out
	)

从 CSC 矩阵创建 DMatrix。

参数

indptr	JSON 编码的 CSC 中列指针的array_interface。
indices	JSON 编码的 CSC 中行索引的array_interface。
数据	JSON 编码的 CSC 中值的array_interface。
nrow	矩阵的行数。
config	有关详细信息，请参阅 XGDMatrixCreateFromDense。
out	创建的 dmatrix。

返回: 成功返回 0，失败返回 -1

示例: c-api-demo.c.

◆ XGDMatrixCreateFromCSR()

int XGDMatrixCreateFromCSR	(	char const *	indptr,
		char const *	indices,
		char const *	数据,
		bst_ulong	ncol,
		char const *	config,
		DMatrixHandle *	out
	)

从 CSR 矩阵创建 DMatrix。

参数

indptr	JSON 编码的 CSR 中行指针的array_interface。
indices	JSON编码的CSR中列索引的array_interface。
数据	JSON 编码的 CSR 中值的array_interface。
ncol	列数。
config	有关详细信息，请参阅 XGDMatrixCreateFromDense。
out	创建的 dmatrix

返回: 成功返回 0，失败返回 -1

示例: c-api-demo.c.

◆ XGDMatrixCreateFromCudaArrayInterface()

int XGDMatrixCreateFromCudaArrayInterface	(	char const *	数据,
		char const *	config,
		DMatrixHandle *	out
	)

从 CUDA 数组创建 DMatrix。

参数

数据	用于数组数据的 JSON 编码cuda_array_interface。
config	JSON 编码的配置。必需的字段包括 missing: 要表示缺失值的值。 nthread (可选): 用于初始化 DMatrix 的线程数。 data_split_mode (可选): 数据是否事先按行或按列拆分。默认为行。
out	创建的 dmatrix

返回: 成功返回 0，失败返回 -1

◆ XGDMatrixCreateFromCudaColumnar()

int XGDMatrixCreateFromCudaColumnar	(	char const *	数据,
		char const *	config,
		DMatrixHandle *	out
	)

从 CUDA 列式格式创建 DMatrix。（cuDF）

有关列式格式的简要说明，请参阅 XGDMatrixCreateFromColumnar。

参数

数据	JSON 编码的数组接口列表。
config	有关详细信息，请参阅 XGDMatrixCreateFromDense。
out	创建的 dmatrix

返回: 成功返回 0，失败返回 -1

◆ XGDMatrixCreateFromDense()

int XGDMatrixCreateFromDense	(	char const *	数据,
		char const *	config,
		DMatrixHandle *	out
	)

从密集数组创建 DMatrix。

数组接口定义在 https://numpy.com.cn/doc/2.1/reference/arrays.interface.html。我们将接口编码为 JSON 对象。

参数

数据	用于数组值的 JSON 编码array_interface。
config	JSON 编码的配置。必需的字段包括 missing: 要表示缺失值的值。 nthread (可选): 用于初始化 DMatrix 的线程数。 data_split_mode (可选): 数据是否事先按行或按列拆分。默认为行。
out	创建的 DMatrix

返回: 成功返回 0，失败返回 -1

示例: inference.c.

◆ XGDMatrixCreateFromFile()

int XGDMatrixCreateFromFile	(	const char *	fname,
		int	silent,
		DMatrixHandle *	out
	)

加载数据矩阵

已废弃: 自 2.0.0 起

另请参阅: XGDMatrixCreateFromURI()

参数

fname	文件的名称
silent	加载期间是否打印消息
out	已加载的数据矩阵

返回: 成功返回 0，失败返回 -1

示例: c-api-demo.c.

◆ XGDMatrixCreateFromMat()

int XGDMatrixCreateFromMat	(	const float *	数据,
		bst_ulong	nrow,
		bst_ulong	ncol,
		float	missing,
		DMatrixHandle *	out
	)

从密集矩阵创建矩阵内容

参数

数据	指向数据空间的指针
nrow	行数
ncol	列数
missing	哪个值代表缺失值
out	创建的 dmatrix

返回: 成功返回 0，失败返回 -1

示例: c-api-demo.c.

◆ XGDMatrixCreateFromMat_omp()

int XGDMatrixCreateFromMat_omp	(	const float *	数据,
		bst_ulong	nrow,
		bst_ulong	ncol,
		float	missing,
		DMatrixHandle *	out,
		int	nthread
	)

从密集矩阵创建矩阵内容

参数

数据	指向数据空间的指针
nrow	行数
ncol	列数
missing	哪个值代表缺失值
out	创建的 dmatrix
nthread	线程数（最多可用核心数，如果 <=0 则使用所有核心）

返回: 成功返回 0，失败返回 -1

◆ XGDMatrixCreateFromURI()

int XGDMatrixCreateFromURI	(	char const *	config,
		DMatrixHandle *	out
	)

加载数据矩阵

参数

config

用于 DMatrix 构建的 JSON 编码参数。可接受的字段包括

uri: 输入文件的 URI。加载文本数据时需要 format 参数。

embed:rst:leading-asterisk
*            See :doc:`/tutorials/input_format` for more info.
*

silent (可选): 加载期间是否打印消息。默认为 true。
data_split_mode (可选): 文件是否事先按行或按列拆分以进行分布式计算。默认为行。

out 已加载的数据矩阵

返回: 成功返回 0，失败返回 -1

◆ XGDMatrixDataSplitMode()

int XGDMatrixDataSplitMode	(	DMatrixHandle	handle,
		bst_ulong *	out
	)

从 DMatrix 获取数据分割模式。

参数

handle	指向 DMatrix 的句柄
out	数据分割模式的输出

返回: 成功返回 0，失败返回 -1

◆ XGDMatrixFree()

int XGDMatrixFree ( DMatrixHandle handle )

释放数据矩阵中的空间

返回: 成功返回 0，失败返回 -1

示例: c-api-demo.c, external_memory.c, 和 inference.c。

◆ XGDMatrixGetDataAsCSR()

int XGDMatrixGetDataAsCSR	(	DMatrixHandle const	handle,
		char const *	config,
		bst_ulong *	out_indptr,
		unsigned *	out_indices,
		float *	out_data
	)

以 CSR 矩阵形式获取 DMatrix 的预测值（用于测试）。如果是量化 DMatrix，则返回量化值。

与大多数 XGBoost C 函数不同，XGDMatrixGetDataAsCSR 的调用者需要为返回缓冲区分配内存，而不是使用 XGBoost 的线程本地内存。这是为了避免分配直到线程退出才能释放的大块内存缓冲区。

自: 1.7.0

参数

handle	指向 DMatrix 的句柄
config	JSON 配置字符串。目前它应该是一个空文档，保留供将来使用。
out_indptr	输出 CSR 矩阵的 indptr。
out_indices	输出 CSR 矩阵的列索引。
out_data	CSR 矩阵的数据值。

返回: 成功返回 0，失败返回 -1

◆ XGDMatrixGetFloatInfo()

int XGDMatrixGetFloatInfo	(	const DMatrixHandle	handle,
		const char *	field,
		bst_ulong *	out_len,
		const float **	out_dptr
	)

从矩阵获取浮点信息向量。

参数

handle	一个数据矩阵实例
field	字段名
out_len	用于设置结果长度
out_dptr	指向结果的指针

返回: 成功返回 0，失败返回 -1

示例: c-api-demo.c.

◆ XGDMatrixGetQuantileCut()

int XGDMatrixGetQuantileCut	(	DMatrixHandle const	handle,
		char const *	config,
		char const **	out_indptr,
		char const **	out_data
	)

导出用于训练基于直方图的模型（如 hist 和 approx）的分位数截断值。对模型压缩很有用。

自: 2.0.0

参数

handle	指向 DMatrix 的句柄
config	JSON 配置字符串。目前它应该是一个空文档，保留供将来使用。
out_indptr	输出 CSC 矩阵的 indptr，表示为 JSON 编码的 __(cuda_)array_interface__。
out_data	输出 CSC 矩阵的值，表示为 JSON 编码的 __(cuda_)array_interface__。

◆ XGDMatrixGetStrFeatureInfo()

int XGDMatrixGetStrFeatureInfo	(	DMatrixHandle	handle,
		const char *	field,
		bst_ulong *	size,
		const char ***	out_features
	)

获取所有特征的字符串编码信息。

接受的字段有

feature_name
feature_type

调用者负责在下一次调用任何 XGBoost API 函数之前复制数据。

参数

handle	数据矩阵的一个实例
field	字段名
size	输出指针 `features` 的大小（返回的字符串数量）。
out_features	指向字符串数组的指针的地址。结果存储在线程本地内存中。

返回: 成功返回 0，失败返回 -1

char const **c_out_features = NULL;
bst_ulong out_size = 0;
 
// 假设特征名称已通过 `XGDMatrixSetStrFeatureInfo` 设置。
XGDMatrixGetStrFeatureInfo(handle, "feature_name", &out_size,
&c_out_features)
 
for (bst_ulong i = 0; i < out_size; ++i) {
  // 这里我们只是打印字符串。如果特征名称有价值，请复制出来
  // 打印后。
printf("feature %lu: %s\n", i, c_out_features[i]);
}

◆ XGDMatrixGetUIntInfo()

int XGDMatrixGetUIntInfo	(	const DMatrixHandle	handle,
		const char *	field,
		bst_ulong *	out_len,
		const unsigned **	out_dptr
	)

从矩阵获取 uint32 信息向量

参数

handle	一个数据矩阵实例
field	字段名
out_len	字段的长度。
out_dptr	指向结果的指针

返回: 成功返回 0，失败返回 -1

◆ XGDMatrixNumCol()

int XGDMatrixNumCol	(	DMatrixHandle	handle,
		bst_ulong *	out
	)

获取列数

参数

handle	指向 DMatrix 的句柄
out	列数的输出

返回: 成功返回 0，失败返回 -1

◆ XGDMatrixNumNonMissing()

int XGDMatrixNumNonMissing	(	DMatrixHandle	handle,
		bst_ulong *	out
	)

从 DMatrix 获取有效值数量。

参数

handle	指向 DMatrix 的句柄
out	非缺失值数量的输出

返回: 成功返回 0，失败返回 -1

◆ XGDMatrixNumRow()

int XGDMatrixNumRow	(	DMatrixHandle	handle,
		bst_ulong *	out
	)

获取行数。

参数

handle	指向 DMatrix 的句柄
out	用于保存行数的地址。

返回: 成功返回 0，失败返回 -1

◆ XGDMatrixSaveBinary()

int XGDMatrixSaveBinary	(	DMatrixHandle	handle,
		const char *	fname,
		int	silent
	)

将 DMatrix 对象保存到文件。不支持 QuantileDMatrix 和外部内存 DMatrix。

参数

handle	一个数据矩阵实例
fname	文件名
silent	保存时打印统计信息

返回: 成功返回 0，失败返回 -1

◆ XGDMatrixSetDenseInfo()

int XGDMatrixSetDenseInfo	(	DMatrixHandle	handle,
		const char *	field,
		void const *	数据,
		bst_ulong	size,
		int	type
	)

已废弃: 自 2.1.0 起

请改用 XGDMatrixSetInfoFromInterface。

示例: external_memory.c, 和 inference.c。

◆ XGDMatrixSetFloatInfo()

int XGDMatrixSetFloatInfo	(	DMatrixHandle	handle,
		const char *	field,
		const float *	数组,
		bst_ulong	长度
	)

将浮点向量设置为信息中的内容

参数

handle	一个数据矩阵实例
field	字段名，可以是 label、weight
数组	指向浮点向量的指针
长度	数组长度

返回: 成功返回 0，失败返回 -1

◆ XGDMatrixSetInfoFromInterface()

int XGDMatrixSetInfoFromInterface	(	DMatrixHandle	handle,
		char const *	field,
		char const *	数据
	)

将数组接口中的内容设置为信息中的内容。

参数

handle	数据矩阵的一个实例
field	字段名。
数据	用于密集矩阵/向量中值的 JSON 编码array_interface。

返回: 成功返回 0，失败返回 -1

◆ XGDMatrixSetStrFeatureInfo()

int XGDMatrixSetStrFeatureInfo	(	DMatrixHandle	handle,
		const char *	field,
		const char **	features,
		const bst_ulong	size
	)

设置所有特征的字符串编码信息。

接受的字段有

feature_name
feature_type

参数

handle	数据矩阵的一个实例
field	字段名
features	指向字符串数组的指针。
size	`features` 指针的大小（传入的字符串数量）。

返回: 成功返回 0，失败返回 -1

char const* feat_names [] {"feat_0", "feat_1"};
XGDMatrixSetStrFeatureInfo(handle, "feature_name", feat_names, 2);
 
// i 代表整数，q 代表数量级，c 代表分类。类似地，"int" 和 "float" 也可以识别。
// 也被识别。
char const* feat_types [] {"i", "q"};
XGDMatrixSetStrFeatureInfo(handle, "feature_type", feat_types, 2);

◆ XGDMatrixSetUIntInfo()

int XGDMatrixSetUIntInfo	(	DMatrixHandle	handle,
		const char *	field,
		const unsigned *	数组,
		bst_ulong	长度
	)

已废弃: 自 2.1.0 起

请改用 XGDMatrixSetInfoFromInterface。

◆ XGDMatrixSliceDMatrix()

int XGDMatrixSliceDMatrix	(	DMatrixHandle	handle,
		const int *	idxset,
		bst_ulong	长度,
		DMatrixHandle *	out
	)

从现有矩阵的切片内容创建新 dmatrix

参数

handle	要切片的 DMatrix 实例
idxset	索引集
长度	索引集长度
out	切片后的新矩阵

返回: 成功返回 0，失败返回 -1

◆ XGDMatrixSliceDMatrixEx()

int XGDMatrixSliceDMatrixEx	(	DMatrixHandle	handle,
		const int *	idxset,
		bst_ulong	长度,
		DMatrixHandle *	out,
		int	allow_groups
	)

从现有矩阵的切片内容创建新 dmatrix

参数

handle	要切片的 DMatrix 实例
idxset	索引集
长度	索引集长度
out	切片后的新矩阵
allow_groups	允许切片带组的数组

返回: 成功返回 0，失败返回 -1

模块

函数

详细描述

函数文档

◆ XGDMatrixCreateFromColumnar()

◆ XGDMatrixCreateFromCSC()

◆ XGDMatrixCreateFromCSR()

◆ XGDMatrixCreateFromCudaArrayInterface()

◆ XGDMatrixCreateFromCudaColumnar()

◆ XGDMatrixCreateFromDense()

◆ XGDMatrixCreateFromFile()

◆ XGDMatrixCreateFromMat()

◆ XGDMatrixCreateFromMat_omp()

◆ XGDMatrixCreateFromURI()

◆ XGDMatrixDataSplitMode()

◆ XGDMatrixFree()

◆ XGDMatrixGetDataAsCSR()

◆ XGDMatrixGetFloatInfo()

◆ XGDMatrixGetQuantileCut()

◆ XGDMatrixGetStrFeatureInfo()

◆ XGDMatrixGetUIntInfo()

◆ XGDMatrixNumCol()

◆ XGDMatrixNumNonMissing()

◆ XGDMatrixNumRow()

◆ XGDMatrixSaveBinary()

◆ XGDMatrixSetDenseInfo()

◆ XGDMatrixSetFloatInfo()

◆ XGDMatrixSetInfoFromInterface()

◆ XGDMatrixSetStrFeatureInfo()

◆ XGDMatrixSetUIntInfo()

◆ XGDMatrixSliceDMatrix()

◆ XGDMatrixSliceDMatrixEx()