c_api.h File Reference

Copyright 2015~2023 by XGBoost Contributors. More...

#include <stddef.h>
#include <stdio.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	XGBoostBatchCSR
	Mini batch used in XGBoost Data Iteration. More...

Macros
#define	XGB_EXTERN_C
#define	XGB_DLL   XGB_EXTERN_C __attribute__ ((visibility ("default")))

Typedefs
typedef uint64_t	bst_ulong
typedef void *	DMatrixHandle
	handle to DMatrix
typedef void *	BoosterHandle
	handle to Booster
typedef void *	DataIterHandle
	handle to a external data iterator
typedef void *	DataHolderHandle
	handle to a internal data holder.

Functions
XGB_DLL void	XGBoostVersion (int *major, int *minor, int *patch)
	Return the version of the XGBoost library being currently used.
XGB_DLL int	XGBuildInfo (char const **out)
	Get compile information of shared library.
XGB_DLL const char *	XGBGetLastError ()
	get string message of the last error
XGB_DLL int	XGBRegisterLogCallback (void(*callback)(const char *))
	register callback function for LOG(INFO) messages – helpful messages that are not errors. Note: this function can be called by multiple threads. The callback function will run on the thread that registered it
XGB_DLL int	XGBSetGlobalConfig (char const *config)
	Set global configuration (collection of parameters that apply globally). This function accepts the list of key-value pairs representing the global-scope parameters to be configured. The list of key-value pairs are passed in as a JSON string.
XGB_DLL int	XGBGetGlobalConfig (char const **out_config)
	Get current global configuration (collection of parameters that apply globally).
XGB_DLL int	XGDMatrixCreateFromFile (const char *fname, int silent, DMatrixHandle *out)
	load a data matrix
XGB_DLL int	XGDMatrixCreateFromURI (char const *config, DMatrixHandle *out)
	load a data matrix
XGB_DLL int	XGDMatrixCreateFromCSREx (const size_t *indptr, const unsigned *indices, const float *data, size_t nindptr, size_t nelem, size_t num_col, DMatrixHandle *out)
	create a matrix content from CSR format
XGB_DLL int	XGDMatrixCreateFromCSR (char const *indptr, char const *indices, char const *data, bst_ulong ncol, char const *config, DMatrixHandle *out)
	Create a matrix from CSR matrix.
XGB_DLL int	XGDMatrixCreateFromDense (char const *data, char const *config, DMatrixHandle *out)
	Create a matrix from dense array.
XGB_DLL int	XGDMatrixCreateFromCSC (char const *indptr, char const *indices, char const *data, bst_ulong nrow, char const *config, DMatrixHandle *out)
	Create a matrix from a CSC matrix.
XGB_DLL 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)
	create a matrix content from CSC format
XGB_DLL int	XGDMatrixCreateFromMat (const float *data, bst_ulong nrow, bst_ulong ncol, float missing, DMatrixHandle *out)
	create matrix content from dense matrix
XGB_DLL int	XGDMatrixCreateFromMat_omp (const float *data, bst_ulong nrow, bst_ulong ncol, float missing, DMatrixHandle *out, int nthread)
	create matrix content from dense matrix
XGB_DLL int	XGDMatrixCreateFromDT (void **data, const char **feature_stypes, bst_ulong nrow, bst_ulong ncol, DMatrixHandle *out, int nthread)
	create matrix content from python data table
XGB_DLL int	XGDMatrixCreateFromCudaColumnar (char const *data, char const *config, DMatrixHandle *out)
	Create DMatrix from CUDA columnar format. (cuDF)
XGB_DLL int	XGDMatrixCreateFromCudaArrayInterface (char const *data, char const *config, DMatrixHandle *out)
	Create DMatrix from CUDA array.
XGB_EXTERN_C typedef int	XGBCallbackSetData (DataHolderHandle handle, XGBoostBatchCSR batch)
	Callback to set the data to handle,.
XGB_EXTERN_C typedef int	XGBCallbackDataIterNext (DataIterHandle data_handle, XGBCallbackSetData *set_function, DataHolderHandle set_function_handle)
	The data reading callback function. The iterator will be able to give subset of batch in the data.
XGB_DLL int	XGDMatrixCreateFromDataIter (DataIterHandle data_handle, XGBCallbackDataIterNext *callback, const char *cache_info, DMatrixHandle *out)
	Create a DMatrix from a data iterator.
XGB_DLL int	XGProxyDMatrixCreate (DMatrixHandle *out)
	Second set of callback functions, used by constructing Quantile DMatrix or external memory DMatrix using custom iterator.
XGB_EXTERN_C typedef int	XGDMatrixCallbackNext (DataIterHandle iter)
	Callback function prototype for getting next batch of data.
XGB_EXTERN_C typedef void	DataIterResetCallback (DataIterHandle handle)
	Callback function prototype for resetting external iterator.
XGB_DLL int	XGDMatrixCreateFromCallback (DataIterHandle iter, DMatrixHandle proxy, DataIterResetCallback *reset, XGDMatrixCallbackNext *next, char const *config, DMatrixHandle *out)
	Create an external memory DMatrix with data iterator.
XGB_DLL int	XGQuantileDMatrixCreateFromCallback (DataIterHandle iter, DMatrixHandle proxy, DataIterHandle ref, DataIterResetCallback *reset, XGDMatrixCallbackNext *next, char const *config, DMatrixHandle *out)
	Create a Quantile DMatrix with data iterator.
XGB_DLL int	XGDeviceQuantileDMatrixCreateFromCallback (DataIterHandle iter, DMatrixHandle proxy, DataIterResetCallback *reset, XGDMatrixCallbackNext *next, float missing, int nthread, int max_bin, DMatrixHandle *out)
	Create a Device Quantile DMatrix with data iterator.
XGB_DLL int	XGProxyDMatrixSetDataCudaArrayInterface (DMatrixHandle handle, const char *c_interface_str)
	Set data on a DMatrix proxy.
XGB_DLL int	XGProxyDMatrixSetDataCudaColumnar (DMatrixHandle handle, const char *c_interface_str)
	Set data on a DMatrix proxy.
XGB_DLL int	XGProxyDMatrixSetDataDense (DMatrixHandle handle, char const *c_interface_str)
	Set data on a DMatrix proxy.
XGB_DLL int	XGProxyDMatrixSetDataCSR (DMatrixHandle handle, char const *indptr, char const *indices, char const *data, bst_ulong ncol)
	Set data on a DMatrix proxy.
XGB_DLL int	XGImportArrowRecordBatch (DataIterHandle data_handle, void *ptr_array, void *ptr_schema)
XGB_DLL int	XGDMatrixCreateFromArrowCallback (XGDMatrixCallbackNext *next, char const *config, DMatrixHandle *out)
	Construct DMatrix from arrow using callbacks. Arrow related C API is not stable and subject to change in the future.
XGB_DLL int	XGDMatrixSliceDMatrix (DMatrixHandle handle, const int *idxset, bst_ulong len, DMatrixHandle *out)
	create a new dmatrix from sliced content of existing matrix
XGB_DLL int	XGDMatrixSliceDMatrixEx (DMatrixHandle handle, const int *idxset, bst_ulong len, DMatrixHandle *out, int allow_groups)
	create a new dmatrix from sliced content of existing matrix
XGB_DLL int	XGDMatrixFree (DMatrixHandle handle)
	free space in data matrix
XGB_DLL int	XGDMatrixSaveBinary (DMatrixHandle handle, const char *fname, int silent)
	load a data matrix into binary file
XGB_DLL int	XGDMatrixSetInfoFromInterface (DMatrixHandle handle, char const *field, char const *c_interface_str)
	Set content in array interface to a content in info.
XGB_DLL int	XGDMatrixSetFloatInfo (DMatrixHandle handle, const char *field, const float *array, bst_ulong len)
	set float vector to a content in info
XGB_DLL int	XGDMatrixSetUIntInfo (DMatrixHandle handle, const char *field, const unsigned *array, bst_ulong len)
	set uint32 vector to a content in info
XGB_DLL int	XGDMatrixSetStrFeatureInfo (DMatrixHandle handle, const char *field, const char **features, const bst_ulong size)
	Set string encoded information of all features.
XGB_DLL int	XGDMatrixGetStrFeatureInfo (DMatrixHandle handle, const char *field, bst_ulong *size, const char ***out_features)
	Get string encoded information of all features.
XGB_DLL int	XGDMatrixSetDenseInfo (DMatrixHandle handle, const char *field, void const *data, bst_ulong size, int type)
	Set meta info from dense matrix. Valid field names are:
XGB_DLL int	XGDMatrixSetGroup (DMatrixHandle handle, const unsigned *group, bst_ulong len)
	(deprecated) Use XGDMatrixSetUIntInfo instead. Set group of the training matrix
XGB_DLL int	XGDMatrixGetFloatInfo (const DMatrixHandle handle, const char *field, bst_ulong *out_len, const float **out_dptr)
	get float info vector from matrix.
XGB_DLL int	XGDMatrixGetUIntInfo (const DMatrixHandle handle, const char *field, bst_ulong *out_len, const unsigned **out_dptr)
	get uint32 info vector from matrix
XGB_DLL int	XGDMatrixNumRow (DMatrixHandle handle, bst_ulong *out)
	get number of rows.
XGB_DLL int	XGDMatrixNumCol (DMatrixHandle handle, bst_ulong *out)
	get number of columns
XGB_DLL int	XGDMatrixNumNonMissing (DMatrixHandle handle, bst_ulong *out)
	Get number of valid values from DMatrix.
XGB_DLL int	XGDMatrixGetDataAsCSR (DMatrixHandle const handle, char const *config, bst_ulong *out_indptr, unsigned *out_indices, float *out_data)
	Get the predictors from DMatrix as CSR matrix for testing.
XGB_DLL int	XGDMatrixGetQuantileCut (DMatrixHandle const handle, char const *config, char const **out_indptr, char const **out_data)
	Export the quantile cuts used for training histogram-based models like hist and approx.
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	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)
XGB_DLL 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.
XGB_DLL 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.
XGB_DLL 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.
XGB_DLL 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).
XGB_DLL 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).
XGB_DLL int	XGBoosterLoadModel (BoosterHandle handle, const char *fname)
	Load model from existing file.
XGB_DLL int	XGBoosterSaveModel (BoosterHandle handle, const char *fname)
	Save model into existing file.
XGB_DLL int	XGBoosterLoadModelFromBuffer (BoosterHandle handle, const void *buf, bst_ulong len)
	load model from in memory buffer
XGB_DLL int	XGBoosterSaveModelToBuffer (BoosterHandle handle, char const *config, bst_ulong *out_len, char const **out_dptr)
	Save model into raw bytes, return header of the array. User must copy the result out, before next xgboost call.
XGB_DLL int	XGBoosterGetModelRaw (BoosterHandle handle, bst_ulong *out_len, const char **out_dptr)
	Save booster to a buffer with in binary format.
XGB_DLL int	XGBoosterSerializeToBuffer (BoosterHandle handle, bst_ulong *out_len, const char **out_dptr)
	Memory snapshot based serialization method. Saves everything states into buffer.
XGB_DLL int	XGBoosterUnserializeFromBuffer (BoosterHandle handle, const void *buf, bst_ulong len)
	Memory snapshot based serialization method. Loads the buffer returned from XGBoosterSerializeToBuffer.
XGB_DLL int	XGBoosterLoadRabitCheckpoint (BoosterHandle handle, int *version)
	Initialize the booster from rabit checkpoint. This is used in distributed training API.
XGB_DLL int	XGBoosterSaveRabitCheckpoint (BoosterHandle handle)
	Save the current checkpoint to rabit.
XGB_DLL int	XGBoosterSaveJsonConfig (BoosterHandle handle, bst_ulong *out_len, char const **out_str)
	Save XGBoost's internal configuration into a JSON document. Currently the support is experimental, function signature may change in the future without notice.
XGB_DLL int	XGBoosterLoadJsonConfig (BoosterHandle handle, char const *config)
	Load XGBoost's internal configuration from a JSON document. Currently the support is experimental, function signature may change in the future without notice.
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.
XGB_DLL int	XGCommunicatorInit (char const *config)
	Initialize the collective communicator.
XGB_DLL int	XGCommunicatorFinalize (void)
	Finalize the collective communicator.
XGB_DLL int	XGCommunicatorGetRank (void)
	Get rank of current process.
XGB_DLL int	XGCommunicatorGetWorldSize (void)
	Get total number of processes.
XGB_DLL int	XGCommunicatorIsDistributed (void)
	Get if the communicator is distributed.
XGB_DLL int	XGCommunicatorPrint (char const *message)
	Print the message to the communicator.
XGB_DLL int	XGCommunicatorGetProcessorName (const char **name_str)
	Get the name of the processor.
XGB_DLL int	XGCommunicatorBroadcast (void *send_receive_buffer, size_t size, int root)
	Broadcast a memory region to all others from root. This function is NOT thread-safe.
XGB_DLL int	XGCommunicatorAllreduce (void *send_receive_buffer, size_t count, int data_type, int op)
	Perform in-place allreduce. This function is NOT thread-safe.

Detailed Description

Copyright 2015~2023 by XGBoost Contributors.

Author

Tianqi Chen

C API of XGBoost, used for interfacing to other languages.