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

Collaboration diagram for Booster:

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
int	XGBoosterCreate (const DMatrixHandle dmats[], bst_ulong len, BoosterHandle *out)
	Create a XGBoost learner (booster) More...

int	XGBoosterFree (BoosterHandle handle)
	Delete the booster. More...

int	XGBoosterReset (BoosterHandle handle)
	Reset the booster object to release data caches used for training. More...

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). More...

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. More...

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

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

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

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

int	XGBoosterTrainOneIter (BoosterHandle handle, DMatrixHandle dtrain, int iter, char const grad, char const hess)
	Update a model with gradient and Hessian. This is used for training with a custom objective function. More...

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

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 More...

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 More...

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 More...

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 More...

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

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

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

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. More...

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. More...

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. More...

Detailed Description

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

During training, the booster object has many caches for improved performance. In addition to gradient and prediction, it also includes runtime buffers like leaf partitions. These buffers persist with the Booster object until either XGBoosterReset() is called or the booster is deleted by the XGBoosterFree().

Function Documentation

◆ XGBoosterBoostedRounds()

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()

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

Deprecated:: since 2.1.0

◆ XGBoosterCreate()

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

Create a XGBoost learner (booster)

Parameters

dmats	matrices that are set to be cached by the booster.
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()

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()

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()

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()

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()

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()

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()

int XGBoosterFree ( BoosterHandle handle )

Delete the booster.

Parameters

handle The handle to be freed.

Returns: 0 when success, -1 when failure happens

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

◆ XGBoosterGetAttr()

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()

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()

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()

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

◆ XGBoosterReset()

int XGBoosterReset ( BoosterHandle handle )

Reset the booster object to release data caches used for training.

Since: 3.0.0

Returns: 0 when success, -1 when failure happens

◆ XGBoosterSetAttr()

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()

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()

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()

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.

◆ XGBoosterTrainOneIter()

int XGBoosterTrainOneIter	(	BoosterHandle	handle,
		DMatrixHandle	dtrain,
		int	iter,
		char const *	grad,
		char const *	hess
	)

Update a model with gradient and Hessian. This is used for training with a custom objective function.

Since: 2.0.0

Parameters

handle	handle
dtrain	The training data.
iter	The current iteration round. When training continuation is used, the count should restart.
grad	Json encoded __(cuda)_array_interface__ for gradient.
hess	Json encoded __(cuda)_array_interface__ for Hessian.

Returns: 0 when success, -1 when failure happens

◆ XGBoosterUpdateOneIter()

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()

◆ XGBoosterReset()

◆ XGBoosterSetAttr()

◆ XGBoosterSetParam()

◆ XGBoosterSetStrFeatureInfo()

◆ XGBoosterSlice()

◆ XGBoosterTrainOneIter()

◆ XGBoosterUpdateOneIter()