DMatrix

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

DMatrix 的协作图

模块
	Streaming
	Quantile DMatrix 和基于外部内存的 DMatrix 可以从数据批次创建。

函数
int	XGDMatrixCreateFromFile (const char *fname, int silent, DMatrixHandle *out)
	加载数据矩阵 更多信息...
int	XGDMatrixCreateFromURI (char const *config, DMatrixHandle *out)
	加载数据矩阵 更多信息...
int	XGDMatrixCreateFromCSREx (const size_t *indptr, const unsigned *indices, const float *data, size_t nindptr, size_t nelem, size_t num_col, DMatrixHandle *out)
	从 CSR 格式创建矩阵内容 更多信息...
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	XGDMatrixCreateFromCSCEx (const size_t *col_ptr, const unsigned *indices, const float *data, size_t nindptr, size_t nelem, size_t num_row, DMatrixHandle *out)
	从 CSC 格式创建矩阵内容 更多信息...
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)
	将 DMatrix 中的预测变量获取为 CSR 矩阵用于测试。如果这是量化 DMatrix，则返回量化值。 更多信息...
int	XGDMatrixGetQuantileCut (DMatrixHandle const handle, char const *config, char const **out_indptr, char const **out_data)
	导出用于训练基于直方图的模型（如 hist 和 approx）的分位数切点。对于模型压缩很有用。 更多信息...

详细描述

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

函数文档

XGDMatrixCreateFromColumnar()

int XGDMatrixCreateFromColumnar	(	char const *	data,
		char const *	config,
		DMatrixHandle *	out
	)

从列式数据创建 DMatrix。(表格)

一种特殊的 DMatrix 输入是列式格式，它指的是基于 arrow 格式的列式数据帧。

参数

data	一个 JSON 编码的数组接口列表。
config	参见 XGDMatrixCreateFromDense 了解详情。
out	创建的 DMatrix。

返回值

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

XGDMatrixCreateFromCSC()

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

从 CSC 矩阵创建 DMatrix。

参数

indptr	JSON 编码的 array_interface，指向 CSC 中的列指针。
indices	JSON 编码的 array_interface，指向 CSC 中的行索引。
data	JSON 编码的 array_interface，指向 CSC 中的值。
nrow	矩阵的行数。
config	参见 XGDMatrixCreateFromDense 了解详情。
out	创建的 DMatrix。

返回值

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

示例

c-api-demo.c.

XGDMatrixCreateFromCSCEx()

int XGDMatrixCreateFromCSCEx	(	const size_t *	col_ptr,
		const unsigned *	indices,
		const float *	data,
		size_t	nindptr,
		size_t	nelem,
		size_t	num_row,
		DMatrixHandle *	out
	)

从 CSC 格式创建矩阵内容

已弃用

自 2.0.0 版本起

另请参见

XGDMatrixCreateFromCSC()

XGDMatrixCreateFromCSR()

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

从 CSR 矩阵创建 DMatrix。

参数

indptr	JSON 编码的 array_interface，指向 CSR 中的行指针。
indices	JSON 编码的 array_interface，指向 CSR 中的列索引。
data	JSON 编码的 array_interface，指向 CSR 中的值。
ncol	列数。
config	参见 XGDMatrixCreateFromDense 了解详情。
out	创建的 DMatrix

返回值

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

示例

c-api-demo.c.

XGDMatrixCreateFromCSREx()

int XGDMatrixCreateFromCSREx	(	const size_t *	indptr,
		const unsigned *	indices,
		const float *	data,
		size_t	nindptr,
		size_t	nelem,
		size_t	num_col,
		DMatrixHandle *	out
	)

从 CSR 格式创建矩阵内容

已弃用

自 2.0.0 版本起

另请参见

XGDMatrixCreateFromCSR()

XGDMatrixCreateFromCudaArrayInterface()

int XGDMatrixCreateFromCudaArrayInterface	(	char const *	data,
		char const *	config,
		DMatrixHandle *	out
	)

从 CUDA 数组创建 DMatrix。

参数

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

返回值

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

XGDMatrixCreateFromCudaColumnar()

int XGDMatrixCreateFromCudaColumnar	(	char const *	data,
		char const *	config,
		DMatrixHandle *	out
	)

从 CUDA 列式格式创建 DMatrix。(cuDF)

参见 XGDMatrixCreateFromColumnar 以获取关于列式格式的简要描述。

参数

data	一个 JSON 编码的数组接口列表。
config	参见 XGDMatrixCreateFromDense 了解详情。
out	创建的 DMatrix

返回值

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

XGDMatrixCreateFromDense()

int XGDMatrixCreateFromDense	(	char const *	data,
		char const *	config,
		DMatrixHandle *	out
	)

从密集数组创建 DMatrix。

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

参数

data	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 *	data,
		bst_ulong	nrow,
		bst_ulong	ncol,
		float	missing,
		DMatrixHandle *	out
	)

从密集矩阵创建矩阵内容

参数

data	指向数据空间的指针
nrow	行数
ncol	列数
missing	用于表示缺失值的值
out	创建的 DMatrix

返回值

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

示例

c-api-demo.c.

XGDMatrixCreateFromMat_omp()

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

从密集矩阵创建矩阵内容

参数

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

返回值

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

XGDMatrixCreateFromURI()

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

加载数据矩阵

参数

config	用于构造 DMatrix 的 JSON 编码参数。接受的字段有： uri: 输入文件的 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
	)

将 DMatrix 中的预测变量获取为 CSR 矩阵用于测试。如果这是量化 DMatrix，则返回量化值。

与大多数 XGBoost C 函数不同，XGDMatrixGetDataAsCSR 的调用者需要为返回缓冲区分配内存，而不是使用 XGBoost 的线程局部内存。这是为了避免分配一个在退出线程之前无法释放的巨大内存缓冲区。

Since

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）的分位数切点。对于模型压缩很有用。

Since

2.0.0

参数

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

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 * feat_names [] = {"feat_0", "feat_1"};
bst_ulong out_size = 0;
 
// 假设特征名已经通过 `XGDMatrixSetStrFeatureInfo` 设置。
XGDMatrixGetStrFeatureInfo(handle, "feature_name", &out_size,
&c_out_features)
 
for (bst_ulong i = 0; i < out_size; ++i) {
  // 这里我们只是简单地打印字符串。如果打印后特征名还有用，请复制出来。
  // useful after printing.
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 *	data,
		bst_ulong	size,
		int	type
	)

已弃用

自 2.1.0 版本起

请改用 XGDMatrixSetInfoFromInterface。

示例

external_memory.c, 和 inference.c。

XGDMatrixSetFloatInfo()

int XGDMatrixSetFloatInfo	(	DMatrixHandle	handle,
		const char *	field,
		const float *	array,
		bst_ulong	len
	)

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

参数

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

返回值

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

XGDMatrixSetInfoFromInterface()

int XGDMatrixSetInfoFromInterface	(	DMatrixHandle	handle,
		char const *	field,
		char const *	data
	)

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

参数

handle	一个数据矩阵实例
field	字段名。
data	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 *	array,
		bst_ulong	len
	)

已弃用

自 2.1.0 版本起

请改用 XGDMatrixSetInfoFromInterface。

XGDMatrixSliceDMatrix()

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

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

参数

handle	要切片的数据矩阵实例
idxset	索引集合
len	索引集合的长度
out	切片后的新矩阵

返回值

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

XGDMatrixSliceDMatrixEx()

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

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

参数

handle	要切片的数据矩阵实例
idxset	索引集合
len	索引集合的长度
out	切片后的新矩阵
allow_groups	允许对带有分组的数组进行切片

返回值

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