The Booster class is the gradient-boosted model for XGBoost. More...

Modules
	Prediction
	These functions are used for running prediction and explanation algorithms.

	Serialization
	There are multiple ways to serialize a Booster object depending on the use case.

Functions
XGB_DLL int	XGBoosterCreate (const DMatrixHandle dmats[], bst_ulong len, BoosterHandle *out)
	create xgboost learner

XGB_DLL int	XGBoosterFree (BoosterHandle handle)
	free obj in handle

XGB_DLL int	XGBoosterSlice (BoosterHandle handle, int begin_layer, int end_layer, int step, BoosterHandle *out)
	Slice a model using boosting index. The slice m:n indicates taking all trees that were fit during the boosting rounds m, (m+1), (m+2), ..., (n-1).

XGB_DLL int	XGBoosterBoostedRounds (BoosterHandle handle, int *out)
	Get number of boosted rounds from gradient booster. When process_type is update, this number might drop due to removed tree.

XGB_DLL int	XGBoosterSetParam (BoosterHandle handle, const char name, const char value)
	set parameters

XGB_DLL int	XGBoosterGetNumFeature (BoosterHandle handle, bst_ulong *out)
	get number of features

XGB_DLL int	XGBoosterUpdateOneIter (BoosterHandle handle, int iter, DMatrixHandle dtrain)
	update the model in one round using dtrain

XGB_DLL int	XGBoosterBoostOneIter (BoosterHandle handle, DMatrixHandle dtrain, float grad, float hess, bst_ulong len)
	update the model, by directly specify gradient and second order gradient, this can be used to replace UpdateOneIter, to support customized loss function

XGB_DLL int	XGBoosterEvalOneIter (BoosterHandle handle, int iter, DMatrixHandle dmats[], const char evnames[], bst_ulong len, const char *out_result)
	get evaluation statistics for xgboost

XGB_DLL int	XGBoosterDumpModel (BoosterHandle handle, const char fmap, int with_stats, bst_ulong out_len, const char ***out_dump_array)
	dump model, return array of strings representing model dump

XGB_DLL int	XGBoosterDumpModelEx (BoosterHandle handle, const char fmap, int with_stats, const char format, bst_ulong out_len, const char **out_dump_array)
	dump model, return array of strings representing model dump

XGB_DLL int	XGBoosterDumpModelWithFeatures (BoosterHandle handle, int fnum, const char fname, const char ftype, int with_stats, bst_ulong out_len, const char **out_models)
	dump model, return array of strings representing model dump

XGB_DLL int	XGBoosterDumpModelExWithFeatures (BoosterHandle handle, int fnum, const char fname, const char ftype, int with_stats, const char format, bst_ulong out_len, const char ***out_models)
	dump model, return array of strings representing model dump

XGB_DLL int	XGBoosterGetAttr (BoosterHandle handle, const char key, const char out, int success)
	Get string attribute from Booster.

XGB_DLL int	XGBoosterSetAttr (BoosterHandle handle, const char key, const char value)
	Set or delete string attribute.

XGB_DLL int	XGBoosterGetAttrNames (BoosterHandle handle, bst_ulong out_len, const char **out)
	Get the names of all attribute from Booster.

XGB_DLL int	XGBoosterSetStrFeatureInfo (BoosterHandle handle, const char field, const char *features, const bst_ulong size)
	Set string encoded feature info in Booster, similar to the feature info in DMatrix.

XGB_DLL int	XGBoosterGetStrFeatureInfo (BoosterHandle handle, const char field, bst_ulong len, const char ***out_features)
	Get string encoded feature info from Booster, similar to feature info in DMatrix.

XGB_DLL int	XGBoosterFeatureScore (BoosterHandle handle, const char config, bst_ulong out_n_features, char const **out_features, bst_ulong out_dim, bst_ulong const out_shape, float const out_scores)
	Calculate feature scores for tree models. When used on linear model, only the `weight` importance type is defined, and output scores is a row major matrix with shape [n_features, n_classes] for multi-class model. For tree model, out_n_feature is always equal to out_n_scores and has multiple definitions of importance type.

Detailed Description

The Booster class is the gradient-boosted model for XGBoost.

Function Documentation

◆ XGBoosterBoostedRounds()

XGB_DLL int XGBoosterBoostedRounds	(	BoosterHandle	handle,
		int *	out
	)

Get number of boosted rounds from gradient booster. When process_type is update, this number might drop due to removed tree.

Parameters

handle	Handle to booster.
out	Pointer to output integer.

Returns: 0 when success, -1 when failure happens

◆ XGBoosterBoostOneIter()

XGB_DLL int XGBoosterBoostOneIter	(	BoosterHandle	handle,
		DMatrixHandle	dtrain,
		float *	grad,
		float *	hess,
		bst_ulong	len
	)

update the model, by directly specify gradient and second order gradient, this can be used to replace UpdateOneIter, to support customized loss function

Parameters

handle	handle
dtrain	training data
grad	gradient statistics
hess	second order gradient statistics
len	length of grad/hess array

Returns: 0 when success, -1 when failure happens

◆ XGBoosterCreate()

XGB_DLL int XGBoosterCreate	(	const DMatrixHandle	dmats[],
		bst_ulong	len,
		BoosterHandle *	out
	)

create xgboost learner

Parameters

dmats	matrices that are set to be cached
len	length of dmats
out	handle to the result booster

Returns: 0 when success, -1 when failure happens

Examples: c-api-demo.c, external_memory.c, and inference.c.

◆ XGBoosterDumpModel()

XGB_DLL int XGBoosterDumpModel	(	BoosterHandle	handle,
		const char *	fmap,
		int	with_stats,
		bst_ulong *	out_len,
		const char ***	out_dump_array
	)

dump model, return array of strings representing model dump

Parameters

handle	handle
fmap	name to fmap can be empty string
with_stats	whether to dump with statistics
out_len	length of output array
out_dump_array	pointer to hold representing dump of each model

Returns: 0 when success, -1 when failure happens

◆ XGBoosterDumpModelEx()

XGB_DLL int XGBoosterDumpModelEx	(	BoosterHandle	handle,
		const char *	fmap,
		int	with_stats,
		const char *	format,
		bst_ulong *	out_len,
		const char ***	out_dump_array
	)

dump model, return array of strings representing model dump

Parameters

handle	handle
fmap	name to fmap can be empty string
with_stats	whether to dump with statistics
format	the format to dump the model in
out_len	length of output array
out_dump_array	pointer to hold representing dump of each model

Returns: 0 when success, -1 when failure happens

◆ XGBoosterDumpModelExWithFeatures()

XGB_DLL int XGBoosterDumpModelExWithFeatures	(	BoosterHandle	handle,
		int	fnum,
		const char **	fname,
		const char **	ftype,
		int	with_stats,
		const char *	format,
		bst_ulong *	out_len,
		const char ***	out_models
	)

dump model, return array of strings representing model dump

Parameters

handle	handle
fnum	number of features
fname	names of features
ftype	types of features
with_stats	whether to dump with statistics
format	the format to dump the model in
out_len	length of output array
out_models	pointer to hold representing dump of each model

Returns: 0 when success, -1 when failure happens

◆ XGBoosterDumpModelWithFeatures()

XGB_DLL int XGBoosterDumpModelWithFeatures	(	BoosterHandle	handle,
		int	fnum,
		const char **	fname,
		const char **	ftype,
		int	with_stats,
		bst_ulong *	out_len,
		const char ***	out_models
	)

dump model, return array of strings representing model dump

Parameters

handle	handle
fnum	number of features
fname	names of features
ftype	types of features
with_stats	whether to dump with statistics
out_len	length of output array
out_models	pointer to hold representing dump of each model

Returns: 0 when success, -1 when failure happens

◆ XGBoosterEvalOneIter()

XGB_DLL int XGBoosterEvalOneIter	(	BoosterHandle	handle,
		int	iter,
		DMatrixHandle	dmats[],
		const char *	evnames[],
		bst_ulong	len,
		const char **	out_result
	)

get evaluation statistics for xgboost

Parameters

handle	handle
iter	current iteration rounds
dmats	pointers to data to be evaluated
evnames	pointers to names of each data
len	length of dmats
out_result	the string containing evaluation statistics

Returns: 0 when success, -1 when failure happens

Examples: c-api-demo.c, and external_memory.c.

◆ XGBoosterFeatureScore()

XGB_DLL int XGBoosterFeatureScore	(	BoosterHandle	handle,
		const char *	config,
		bst_ulong *	out_n_features,
		char const ***	out_features,
		bst_ulong *	out_dim,
		bst_ulong const **	out_shape,
		float const **	out_scores
	)

Calculate feature scores for tree models. When used on linear model, only the weight importance type is defined, and output scores is a row major matrix with shape [n_features, n_classes] for multi-class model. For tree model, out_n_feature is always equal to out_n_scores and has multiple definitions of importance type.

Parameters

handle	An instance of Booster
config	Parameters for computing scores encoded as JSON. Accepted JSON keys are: importance_type: A JSON string with following possible values: 'weight': the number of times a feature is used to split the data across all trees. 'gain': the average gain across all splits the feature is used in. 'cover': the average coverage across all splits the feature is used in. 'total_gain': the total gain across all splits the feature is used in. 'total_cover': the total coverage across all splits the feature is used in. feature_map: An optional JSON string with URI or path to the feature map file. feature_names: An optional JSON array with string names for each feature.
out_n_features	Length of output feature names.
out_features	An array of string as feature names, ordered the same as output scores.
out_dim	Dimension of output feature scores.
out_shape	Shape of output feature scores with length of `out_dim`.
out_scores	An array of floating point as feature scores with shape of `out_shape`.

Returns: 0 when success, -1 when failure happens

◆ XGBoosterFree()

XGB_DLL int XGBoosterFree ( BoosterHandle handle )

free obj in handle

Parameters

handle handle to be freed

Returns: 0 when success, -1 when failure happens

Examples: c-api-demo.c, external_memory.c, and inference.c.

◆ XGBoosterGetAttr()

XGB_DLL int XGBoosterGetAttr	(	BoosterHandle	handle,
		const char *	key,
		const char **	out,
		int *	success
	)

Get string attribute from Booster.

Parameters

handle	handle
key	The key of the attribute.
out	The result attribute, can be NULL if the attribute do not exist.
success	Whether the result is contained in out.

Returns: 0 when success, -1 when failure happens

◆ XGBoosterGetAttrNames()

XGB_DLL int XGBoosterGetAttrNames	(	BoosterHandle	handle,
		bst_ulong *	out_len,
		const char ***	out
	)

Get the names of all attribute from Booster.

Parameters

handle	handle
out_len	the argument to hold the output length
out	pointer to hold the output attribute stings

Returns: 0 when success, -1 when failure happens

◆ XGBoosterGetNumFeature()

XGB_DLL int XGBoosterGetNumFeature	(	BoosterHandle	handle,
		bst_ulong *	out
	)

get number of features

Parameters

handle	Handle to booster.
out	number of features

Returns: 0 when success, -1 when failure happens

Examples: c-api-demo.c.

◆ XGBoosterGetStrFeatureInfo()

XGB_DLL int XGBoosterGetStrFeatureInfo	(	BoosterHandle	handle,
		const char *	field,
		bst_ulong *	len,
		const char ***	out_features
	)

Get string encoded feature info from Booster, similar to feature info in DMatrix.

Accepted fields are:

feature_name
feature_type

Caller is responsible for copying out the data, before next call to any API function of XGBoost.

Parameters

handle	An instance of Booster
field	Field name
len	Size of output pointer `features` (number of strings returned).
out_features	Address of a pointer to array of strings. Result is stored in thread local memory.

Returns: 0 when success, -1 when failure happens

◆ XGBoosterSetAttr()

XGB_DLL int XGBoosterSetAttr	(	BoosterHandle	handle,
		const char *	key,
		const char *	value
	)

Set or delete string attribute.

Parameters

handle	handle
key	The key of the attribute.
value	The value to be saved. If nullptr, the attribute would be deleted.

Returns: 0 when success, -1 when failure happens

◆ XGBoosterSetParam()

XGB_DLL int XGBoosterSetParam	(	BoosterHandle	handle,
		const char *	name,
		const char *	value
	)

set parameters

Parameters

handle	handle
name	parameter name
value	value of parameter

Returns: 0 when success, -1 when failure happens

Examples: c-api-demo.c, and external_memory.c.

◆ XGBoosterSetStrFeatureInfo()

XGB_DLL int XGBoosterSetStrFeatureInfo	(	BoosterHandle	handle,
		const char *	field,
		const char **	features,
		const bst_ulong	size
	)

Set string encoded feature info in Booster, similar to the feature info in DMatrix.

Accepted fields are:

feature_name
feature_type

Parameters

handle	An instance of Booster
field	Field name
features	Pointer to array of strings.
size	Size of `features` pointer (number of strings passed in).

Returns: 0 when success, -1 when failure happens

◆ XGBoosterSlice()

XGB_DLL int XGBoosterSlice	(	BoosterHandle	handle,
		int	begin_layer,
		int	end_layer,
		int	step,
		BoosterHandle *	out
	)

Slice a model using boosting index. The slice m:n indicates taking all trees that were fit during the boosting rounds m, (m+1), (m+2), ..., (n-1).

Parameters

handle	Booster to be sliced.
begin_layer	start of the slice
end_layer	end of the slice; end_layer=0 is equivalent to end_layer=num_boost_round
step	step size of the slice
out	Sliced booster.

Returns: 0 when success, -1 when failure happens, -2 when index is out of bound.

◆ XGBoosterUpdateOneIter()

XGB_DLL int XGBoosterUpdateOneIter	(	BoosterHandle	handle,
		int	iter,
		DMatrixHandle	dtrain
	)

update the model in one round using dtrain

Parameters

handle	handle
iter	current iteration rounds
dtrain	training data

Returns: 0 when success, -1 when failure happens

Examples: c-api-demo.c, external_memory.c, and inference.c.

Modules

Functions

Detailed Description

Function Documentation

◆ XGBoosterBoostedRounds()

◆ XGBoosterBoostOneIter()

◆ XGBoosterCreate()

◆ XGBoosterDumpModel()

◆ XGBoosterDumpModelEx()

◆ XGBoosterDumpModelExWithFeatures()

◆ XGBoosterDumpModelWithFeatures()

◆ XGBoosterEvalOneIter()

◆ XGBoosterFeatureScore()

◆ XGBoosterFree()

◆ XGBoosterGetAttr()

◆ XGBoosterGetAttrNames()

◆ XGBoosterGetNumFeature()

◆ XGBoosterGetStrFeatureInfo()

◆ XGBoosterSetAttr()

◆ XGBoosterSetParam()

◆ XGBoosterSetStrFeatureInfo()

◆ XGBoosterSlice()

◆ XGBoosterUpdateOneIter()