These functions are used for running prediction and explanation algorithms. More...

Collaboration diagram for Prediction:

Functions
int	XGBoosterPredict (BoosterHandle handle, DMatrixHandle dmat, int option_mask, unsigned ntree_limit, int training, bst_ulong out_len, const float *out_result)
	make prediction based on dmat (deprecated, use XGBoosterPredictFromDMatrix instead) More...

int	XGBoosterPredictFromDMatrix (BoosterHandle handle, DMatrixHandle dmat, char const config, bst_ulong const out_shape, bst_ulong out_dim, float const **out_result)
	Make prediction from DMatrix, replacing XGBoosterPredict. More...

int	XGBoosterPredictFromDense (BoosterHandle handle, char const values, char const config, DMatrixHandle m, bst_ulong const *out_shape, bst_ulong out_dim, const float **out_result)
	Inplace prediction from CPU dense matrix. More...

int	XGBoosterPredictFromCSR (BoosterHandle handle, char const indptr, char const indices, char const values, bst_ulong ncol, char const config, DMatrixHandle m, bst_ulong const *out_shape, bst_ulong out_dim, const float **out_result)
	Inplace prediction from CPU CSR matrix. More...

int	XGBoosterPredictFromCudaArray (BoosterHandle handle, char const values, char const config, DMatrixHandle m, bst_ulong const *out_shape, bst_ulong out_dim, const float **out_result)
	Inplace prediction from CUDA Dense matrix (cupy in Python). More...

int	XGBoosterPredictFromCudaColumnar (BoosterHandle handle, char const values, char const config, DMatrixHandle m, bst_ulong const *out_shape, bst_ulong out_dim, const float **out_result)
	Inplace prediction from CUDA dense dataframe (cuDF in Python). More...

Detailed Description

These functions are used for running prediction and explanation algorithms.

Function Documentation

◆ XGBoosterPredict()

int XGBoosterPredict	(	BoosterHandle	handle,
		DMatrixHandle	dmat,
		int	option_mask,
		unsigned	ntree_limit,
		int	training,
		bst_ulong *	out_len,
		const float **	out_result
	)

make prediction based on dmat (deprecated, use XGBoosterPredictFromDMatrix instead)

Deprecated:

See also: XGBoosterPredictFromDMatrix()

Parameters

handle	handle
dmat	data matrix
option_mask	bit-mask of options taken in prediction, possible values 0:normal prediction 1:output margin instead of transformed value 2:output leaf index of trees instead of leaf value, note leaf index is unique per tree 4:output feature contributions to individual predictions
ntree_limit	limit number of trees used for prediction, this is only valid for boosted trees when the parameter is set to 0, we will use all the trees
training	Whether the prediction function is used as part of a training loop. Prediction can be run in 2 scenarios: Given data matrix X, obtain prediction y_pred from the model. Obtain the prediction for computing gradients. For example, DART booster performs dropout during training, and the prediction result will be different from the one obtained by normal inference step due to dropped trees. Set training=false for the first scenario. Set training=true for the second scenario. The second scenario applies when you are defining a custom objective function.
out_len	used to store length of returning result
out_result	used to set a pointer to array

Returns: 0 when success, -1 when failure happens

◆ XGBoosterPredictFromCSR()

int XGBoosterPredictFromCSR	(	BoosterHandle	handle,
		char const *	indptr,
		char const *	indices,
		char const *	values,
		bst_ulong	ncol,
		char const *	config,
		DMatrixHandle	m,
		bst_ulong const **	out_shape,
		bst_ulong *	out_dim,
		const float **	out_result
	)

Inplace prediction from CPU CSR matrix.

Note: If the booster is configured to run on a CUDA device, XGBoost falls back to run prediction with DMatrix with a performance warning.

Parameters

handle	Booster handle.
indptr	JSON encoded array_interface to row pointer in CSR.
indices	JSON encoded array_interface to column indices in CSR.
values	JSON encoded array_interface to values in CSR..
ncol	Number of features in data.
config	See XGBoosterPredictFromDMatrix for more info. Additional fields for inplace prediction are: "missing": float
m	An optional (NULL if not available) proxy DMatrix instance storing meta info.
out_shape	See XGBoosterPredictFromDMatrix for more info.
out_dim	See XGBoosterPredictFromDMatrix for more info.
out_result	See XGBoosterPredictFromDMatrix for more info.

Returns: 0 when success, -1 when failure happens

◆ XGBoosterPredictFromCudaArray()

int XGBoosterPredictFromCudaArray	(	BoosterHandle	handle,
		char const *	values,
		char const *	config,
		DMatrixHandle	m,
		bst_ulong const **	out_shape,
		bst_ulong *	out_dim,
		const float **	out_result
	)

Inplace prediction from CUDA Dense matrix (cupy in Python).

Note: If the booster is configured to run on a CPU, XGBoost falls back to run prediction with DMatrix with a performance warning.

Parameters

handle	Booster handle
values	JSON encoded cuda_array_interface to values.
config	See XGBoosterPredictFromDMatrix for more info. Additional fields for inplace prediction are: "missing": float
m	An optional (NULL if not available) proxy DMatrix instance storing meta info.
out_shape	See XGBoosterPredictFromDMatrix for more info.
out_dim	See XGBoosterPredictFromDMatrix for more info.
out_result	See XGBoosterPredictFromDMatrix for more info.

Returns: 0 when success, -1 when failure happens

◆ XGBoosterPredictFromCudaColumnar()

int XGBoosterPredictFromCudaColumnar	(	BoosterHandle	handle,
		char const *	values,
		char const *	config,
		DMatrixHandle	m,
		bst_ulong const **	out_shape,
		bst_ulong *	out_dim,
		const float **	out_result
	)

Inplace prediction from CUDA dense dataframe (cuDF in Python).

Note: If the booster is configured to run on a CPU, XGBoost falls back to run prediction with DMatrix with a performance warning.

Parameters

handle	Booster handle
values	List of cuda_array_interface for all columns encoded in JSON list.
config	See XGBoosterPredictFromDMatrix for more info. Additional fields for inplace prediction are: "missing": float
m	An optional (NULL if not available) proxy DMatrix instance storing meta info.
out_shape	See XGBoosterPredictFromDMatrix for more info.
out_dim	See XGBoosterPredictFromDMatrix for more info.
out_result	See XGBoosterPredictFromDMatrix for more info.

Returns: 0 when success, -1 when failure happens

◆ XGBoosterPredictFromDense()

int XGBoosterPredictFromDense	(	BoosterHandle	handle,
		char const *	values,
		char const *	config,
		DMatrixHandle	m,
		bst_ulong const **	out_shape,
		bst_ulong *	out_dim,
		const float **	out_result
	)

Inplace prediction from CPU dense matrix.

Note: If the booster is configured to run on a CUDA device, XGBoost falls back to run prediction with DMatrix with a performance warning.

Parameters

handle	Booster handle.
values	JSON encoded array_interface to values.
config	See XGBoosterPredictFromDMatrix for more info. Additional fields for inplace prediction are: "missing": float
m	An optional (NULL if not available) proxy DMatrix instance storing meta info.
out_shape	See XGBoosterPredictFromDMatrix for more info.
out_dim	See XGBoosterPredictFromDMatrix for more info.
out_result	See XGBoosterPredictFromDMatrix for more info.

Returns: 0 when success, -1 when failure happens

Examples: inference.c.

◆ XGBoosterPredictFromDMatrix()

int XGBoosterPredictFromDMatrix	(	BoosterHandle	handle,
		DMatrixHandle	dmat,
		char const *	config,
		bst_ulong const **	out_shape,
		bst_ulong *	out_dim,
		float const **	out_result
	)

Make prediction from DMatrix, replacing XGBoosterPredict.

Parameters

handle	Booster handle
dmat	DMatrix handle
config	String encoded predict configuration in JSON format, with following available fields in the JSON object:

"type": [0, 6]

0: normal prediction
1: output margin
2: predict contribution
3: predict approximated contribution
4: predict feature interaction
5: predict approximated feature interaction
6: predict leaf "training": bool Whether the prediction function is used as part of a training loop. Not used for inplace prediction.

Prediction can be run in 2 scenarios:

Given data matrix X, obtain prediction y_pred from the model.
Obtain the prediction for computing gradients. For example, DART booster performs dropout during training, and the prediction result will be different from the one obtained by normal inference step due to dropped trees. Set training=false for the first scenario. Set training=true for the second scenario. The second scenario applies when you are defining a custom objective function. "iteration_begin": int Beginning iteration of prediction. "iteration_end": int End iteration of prediction. Set to 0 this will become the size of tree model (all the trees). "strict_shape": bool Whether should we reshape the output with stricter rules. If set to true, normal/margin/contrib/interaction predict will output consistent shape disregarding the use of multi-class model, and leaf prediction will output 4-dim array representing: (n_samples, n_iterations, n_classes, n_trees_in_forest)

Example JSON input for running a normal prediction with strict output shape, 2 dim for softprob , 1 dim for others.

 {
    "type": 0,
    "training": false,
    "iteration_begin": 0,
    "iteration_end": 0,
    "strict_shape": true
}

Parameters

out_shape	Shape of output prediction (copy before use).
out_dim	Dimension of output prediction.
out_result	Buffer storing prediction value (copy before use).

Returns: 0 when success, -1 when failure happens

See also: XGBoosterPredictFromDense XGBoosterPredictFromCSR XGBoosterPredictFromCudaArray XGBoosterPredictFromCudaColumnar

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

Functions

Detailed Description

Function Documentation

◆ XGBoosterPredict()

◆ XGBoosterPredictFromCSR()

◆ XGBoosterPredictFromCudaArray()

◆ XGBoosterPredictFromCudaColumnar()

◆ XGBoosterPredictFromDense()

◆ XGBoosterPredictFromDMatrix()