xgboost
|
C API of XGBoost, used for interfacing to other languages. More...
#include <stdio.h>
#include <stdint.h>
Go to the source code of this file.
Classes | |
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 More... | |
typedef void * | BoosterHandle |
handle to Booster More... | |
typedef void * | DataIterHandle |
handle to a external data iterator More... | |
typedef void * | DataHolderHandle |
handle to a internal data holder. More... | |
Functions | |
XGB_DLL void | XGBoostVersion (int *major, int *minor, int *patch) |
Return the version of the XGBoost library being currently used. More... | |
XGB_DLL int | XGBuildInfo (char const **out) |
Get compile information of shared library. More... | |
const XGB_DLL char * | XGBGetLastError (void) |
get string message of the last error More... | |
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 More... | |
XGB_DLL int | XGBSetGlobalConfig (const char *json_str) |
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. More... | |
XGB_DLL int | XGBGetGlobalConfig (const char **json_str) |
Get current global configuration (collection of parameters that apply globally). More... | |
XGB_DLL int | XGDMatrixCreateFromFile (const char *fname, int silent, DMatrixHandle *out) |
load a data matrix More... | |
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 More... | |
XGB_DLL int | XGDMatrixCreateFromCSR (char const *indptr, char const *indices, char const *data, bst_ulong ncol, char const *json_config, DMatrixHandle *out) |
Create a matrix from CSR matrix. More... | |
XGB_DLL int | XGDMatrixCreateFromDense (char const *data, char const *json_config, DMatrixHandle *out) |
Create a matrix from dense array. More... | |
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 More... | |
XGB_DLL int | XGDMatrixCreateFromMat (const float *data, bst_ulong nrow, bst_ulong ncol, float missing, DMatrixHandle *out) |
create matrix content from dense matrix More... | |
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 More... | |
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 More... | |
XGB_DLL int | XGDMatrixCreateFromCudaColumnar (char const *data, char const *json_config, DMatrixHandle *out) |
Create DMatrix from CUDA columnar format. (cuDF) More... | |
XGB_DLL int | XGDMatrixCreateFromCudaArrayInterface (char const *data, char const *json_config, DMatrixHandle *out) |
Create DMatrix from CUDA array. More... | |
XGB_EXTERN_C typedef int | XGBCallbackSetData (DataHolderHandle handle, XGBoostBatchCSR batch) |
Callback to set the data to handle,. More... | |
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. More... | |
XGB_DLL int | XGDMatrixCreateFromDataIter (DataIterHandle data_handle, XGBCallbackDataIterNext *callback, const char *cache_info, DMatrixHandle *out) |
Create a DMatrix from a data iterator. More... | |
XGB_DLL int | XGProxyDMatrixCreate (DMatrixHandle *out) |
Create a DMatrix proxy for setting data, can be free by XGDMatrixFree. More... | |
XGB_EXTERN_C typedef int | XGDMatrixCallbackNext (DataIterHandle iter) |
Callback function prototype for getting next batch of data. More... | |
XGB_EXTERN_C typedef void | DataIterResetCallback (DataIterHandle handle) |
Callback function prototype for resetting external iterator. More... | |
XGB_DLL int | XGDMatrixCreateFromCallback (DataIterHandle iter, DMatrixHandle proxy, DataIterResetCallback *reset, XGDMatrixCallbackNext *next, char const *c_json_config, DMatrixHandle *out) |
Create an external memory DMatrix with data iterator. More... | |
XGB_DLL int | XGDeviceQuantileDMatrixCreateFromCallback (DataIterHandle iter, DMatrixHandle proxy, DataIterResetCallback *reset, XGDMatrixCallbackNext *next, float missing, int nthread, int max_bin, DMatrixHandle *out) |
Create a Quantile DMatrix with data iterator. More... | |
XGB_DLL int | XGProxyDMatrixSetDataCudaArrayInterface (DMatrixHandle handle, const char *c_interface_str) |
Set data on a DMatrix proxy. More... | |
XGB_DLL int | XGProxyDMatrixSetDataCudaColumnar (DMatrixHandle handle, const char *c_interface_str) |
Set data on a DMatrix proxy. More... | |
XGB_DLL int | XGProxyDMatrixSetDataDense (DMatrixHandle handle, char const *c_interface_str) |
Set data on a DMatrix proxy. More... | |
XGB_DLL int | XGProxyDMatrixSetDataCSR (DMatrixHandle handle, char const *indptr, char const *indices, char const *data, bst_ulong ncol) |
Set data on a DMatrix proxy. More... | |
XGB_DLL int | XGImportArrowRecordBatch (DataIterHandle data_handle, void *ptr_array, void *ptr_schema) |
XGB_DLL int | XGDMatrixCreateFromArrowCallback (XGDMatrixCallbackNext *next, char const *json_config, DMatrixHandle *out) |
Construct DMatrix from arrow using callbacks. Arrow related C API is not stable and subject to change in the future. More... | |
XGB_DLL int | XGDMatrixSliceDMatrix (DMatrixHandle handle, const int *idxset, bst_ulong len, DMatrixHandle *out) |
create a new dmatrix from sliced content of existing matrix More... | |
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 More... | |
XGB_DLL int | XGDMatrixFree (DMatrixHandle handle) |
free space in data matrix More... | |
XGB_DLL int | XGDMatrixSaveBinary (DMatrixHandle handle, const char *fname, int silent) |
load a data matrix into binary file More... | |
XGB_DLL int | XGDMatrixSetInfoFromInterface (DMatrixHandle handle, char const *field, char const *c_interface_str) |
Set content in array interface to a content in info. More... | |
XGB_DLL int | XGDMatrixSetFloatInfo (DMatrixHandle handle, const char *field, const float *array, bst_ulong len) |
set float vector to a content in info More... | |
XGB_DLL int | XGDMatrixSetUIntInfo (DMatrixHandle handle, const char *field, const unsigned *array, bst_ulong len) |
set uint32 vector to a content in info More... | |
XGB_DLL int | XGDMatrixSetStrFeatureInfo (DMatrixHandle handle, const char *field, const char **features, const bst_ulong size) |
Set string encoded information of all features. More... | |
XGB_DLL int | XGDMatrixGetStrFeatureInfo (DMatrixHandle handle, const char *field, bst_ulong *size, const char ***out_features) |
Get string encoded information of all features. More... | |
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: More... | |
XGB_DLL int | XGDMatrixSetGroup (DMatrixHandle handle, const unsigned *group, bst_ulong len) |
(deprecated) Use XGDMatrixSetUIntInfo instead. Set group of the training matrix More... | |
XGB_DLL int | XGDMatrixGetFloatInfo (const DMatrixHandle handle, const char *field, bst_ulong *out_len, const float **out_dptr) |
get float info vector from matrix. More... | |
XGB_DLL int | XGDMatrixGetUIntInfo (const DMatrixHandle handle, const char *field, bst_ulong *out_len, const unsigned **out_dptr) |
get uint32 info vector from matrix More... | |
XGB_DLL int | XGDMatrixNumRow (DMatrixHandle handle, bst_ulong *out) |
get number of rows. More... | |
XGB_DLL int | XGDMatrixNumCol (DMatrixHandle handle, bst_ulong *out) |
get number of columns More... | |
XGB_DLL int | XGBoosterCreate (const DMatrixHandle dmats[], bst_ulong len, BoosterHandle *out) |
create xgboost learner More... | |
XGB_DLL int | XGBoosterFree (BoosterHandle handle) |
free obj in handle More... | |
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). More... | |
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. More... | |
XGB_DLL int | XGBoosterSetParam (BoosterHandle handle, const char *name, const char *value) |
set parameters More... | |
XGB_DLL int | XGBoosterGetNumFeature (BoosterHandle handle, bst_ulong *out) |
get number of features More... | |
XGB_DLL int | XGBoosterUpdateOneIter (BoosterHandle handle, int iter, DMatrixHandle dtrain) |
update the model in one round using dtrain More... | |
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 More... | |
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 More... | |
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) More... | |
XGB_DLL int | XGBoosterPredictFromDMatrix (BoosterHandle handle, DMatrixHandle dmat, char const *c_json_config, bst_ulong const **out_shape, bst_ulong *out_dim, float const **out_result) |
Make prediction from DMatrix, replacing XGBoosterPredict . More... | |
XGB_DLL int | XGBoosterPredictFromDense (BoosterHandle handle, char const *values, char const *c_json_config, DMatrixHandle m, bst_ulong const **out_shape, bst_ulong *out_dim, const float **out_result) |
XGB_DLL int | XGBoosterPredictFromCSR (BoosterHandle handle, char const *indptr, char const *indices, char const *values, bst_ulong ncol, char const *c_json_config, DMatrixHandle m, bst_ulong const **out_shape, bst_ulong *out_dim, const float **out_result) |
XGB_DLL int | XGBoosterPredictFromCudaArray (BoosterHandle handle, char const *values, char const *c_json_config, DMatrixHandle m, bst_ulong const **out_shape, bst_ulong *out_dim, const float **out_result) |
XGB_DLL int | XGBoosterPredictFromCudaColumnar (BoosterHandle handle, char const *values, char const *c_json_config, DMatrixHandle m, bst_ulong const **out_shape, bst_ulong *out_dim, const float **out_result) |
XGB_DLL int | XGBoosterLoadModel (BoosterHandle handle, const char *fname) |
Load model from existing file. More... | |
XGB_DLL int | XGBoosterSaveModel (BoosterHandle handle, const char *fname) |
Save model into existing file. More... | |
XGB_DLL int | XGBoosterLoadModelFromBuffer (BoosterHandle handle, const void *buf, bst_ulong len) |
load model from in memory buffer More... | |
XGB_DLL int | XGBoosterSaveModelToBuffer (BoosterHandle handle, char const *json_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. More... | |
XGB_DLL int | XGBoosterGetModelRaw (BoosterHandle handle, bst_ulong *out_len, const char **out_dptr) |
Deprecated, use XGBoosterSaveModelToBuffer instead. More... | |
XGB_DLL int | XGBoosterSerializeToBuffer (BoosterHandle handle, bst_ulong *out_len, const char **out_dptr) |
Memory snapshot based serialization method. Saves everything states into buffer. More... | |
XGB_DLL int | XGBoosterUnserializeFromBuffer (BoosterHandle handle, const void *buf, bst_ulong len) |
Memory snapshot based serialization method. Loads the buffer returned from ‘XGBoosterSerializeToBuffer’. More... | |
XGB_DLL int | XGBoosterLoadRabitCheckpoint (BoosterHandle handle, int *version) |
Initialize the booster from rabit checkpoint. This is used in distributed training API. More... | |
XGB_DLL int | XGBoosterSaveRabitCheckpoint (BoosterHandle handle) |
Save the current checkpoint to rabit. More... | |
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. More... | |
XGB_DLL int | XGBoosterLoadJsonConfig (BoosterHandle handle, char const *json_parameters) |
Load XGBoost's internal configuration from a JSON document. Currently the support is experimental, function signature may change in the future without notice. More... | |
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 More... | |
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 More... | |
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 More... | |
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 More... | |
XGB_DLL int | XGBoosterGetAttr (BoosterHandle handle, const char *key, const char **out, int *success) |
Get string attribute from Booster. More... | |
XGB_DLL int | XGBoosterSetAttr (BoosterHandle handle, const char *key, const char *value) |
Set or delete string attribute. More... | |
XGB_DLL int | XGBoosterGetAttrNames (BoosterHandle handle, bst_ulong *out_len, const char ***out) |
Get the names of all attribute from Booster. More... | |
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. More... | |
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. More... | |
XGB_DLL int | XGBoosterFeatureScore (BoosterHandle handle, const char *json_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... | |
C API of XGBoost, used for interfacing to other languages.
Copyright (c) 2015~2021 by Contributors
#define XGB_DLL XGB_EXTERN_C __attribute__ ((visibility ("default"))) |
#define XGB_EXTERN_C |
typedef void* BoosterHandle |
handle to Booster
typedef uint64_t bst_ulong |
typedef void* DataHolderHandle |
handle to a internal data holder.
typedef void* DataIterHandle |
handle to a external data iterator
========================== Begin data callback APIs =========================
Short notes for data callback
There are 2 sets of data callbacks for DMatrix. The first one is currently exclusively used by JVM packages. It uses XGBoostBatchCSR
to accept batches for CSR formated input, and concatenate them into 1 final big CSR. The related functions are:
Another set is used by external data iterator. It accept foreign data iterators as callbacks. There are 2 different senarios where users might want to pass in callbacks instead of raw data. First it's the Quantile DMatrix used by GPU Hist. For this case, the data is first compressed by quantile sketching then merged. This is particular useful for distributed setting as it eliminates 2 copies of data. 1 by a concat
from external library to make the data into a blob for normal DMatrix initialization, another by the internal CSR copy of DMatrix. The second use case is external memory support where users can pass a custom data iterator into XGBoost for loading data in batches. There are short notes on each of the use case in respected DMatrix factory function.
Related functions are:
typedef void* DMatrixHandle |
handle to DMatrix
XGB_EXTERN_C typedef void DataIterResetCallback | ( | DataIterHandle | handle | ) |
Callback function prototype for resetting external iterator.
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.
If there is data, the function will call set_function to set the data.
data_handle | The handle to the callback. |
set_function | The batch returned by the iterator |
set_function_handle | The handle to be passed to set function. |
XGB_EXTERN_C typedef int XGBCallbackSetData | ( | DataHolderHandle | handle, |
XGBoostBatchCSR | batch | ||
) |
Callback to set the data to handle,.
handle | The handle to the callback. |
batch | The data content to be set. |
XGB_DLL int XGBGetGlobalConfig | ( | const char ** | json_str | ) |
Get current global configuration (collection of parameters that apply globally).
json_str | pointer to received returned global configuration, represented as a JSON string. |
const XGB_DLL char* XGBGetLastError | ( | void | ) |
get string message of the last error
all function in this file will return 0 when success and -1 when an error occurred, XGBGetLastError can be called to retrieve the error
this function is thread safe and can be called by different thread
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.
handle | Handle to booster. |
out | Pointer to output integer. |
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
handle | handle |
dtrain | training data |
grad | gradient statistics |
hess | second order gradient statistics |
len | length of grad/hess array |
XGB_DLL int XGBoosterCreate | ( | const DMatrixHandle | dmats[], |
bst_ulong | len, | ||
BoosterHandle * | out | ||
) |
create xgboost learner
dmats | matrices that are set to be cached |
len | length of dmats |
out | handle to the result booster |
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
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 |
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
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 |
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
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 |
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
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 |
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
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 |
XGB_DLL int XGBoosterFeatureScore | ( | BoosterHandle | handle, |
const char * | json_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.
handle | An instance of Booster |
json_config | Parameters for computing scores. Accepted JSON keys are:
|
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 . |
XGB_DLL int XGBoosterFree | ( | BoosterHandle | handle | ) |
free obj in handle
handle | handle to be freed |
XGB_DLL int XGBoosterGetAttr | ( | BoosterHandle | handle, |
const char * | key, | ||
const char ** | out, | ||
int * | success | ||
) |
Get string attribute from Booster.
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. |
XGB_DLL int XGBoosterGetAttrNames | ( | BoosterHandle | handle, |
bst_ulong * | out_len, | ||
const char *** | out | ||
) |
Get the names of all attribute from Booster.
handle | handle |
out_len | the argument to hold the output length |
out | pointer to hold the output attribute stings |
XGB_DLL int XGBoosterGetModelRaw | ( | BoosterHandle | handle, |
bst_ulong * | out_len, | ||
const char ** | out_dptr | ||
) |
Deprecated, use XGBoosterSaveModelToBuffer
instead.
XGB_DLL int XGBoosterGetNumFeature | ( | BoosterHandle | handle, |
bst_ulong * | out | ||
) |
get number of features
out | number of features |
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:
Caller is responsible for copying out the data, before next call to any API function of XGBoost.
handle | An instance of Booster |
field | Field name |
size | 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. |
XGB_DLL int XGBoosterLoadJsonConfig | ( | BoosterHandle | handle, |
char const * | json_parameters | ||
) |
Load XGBoost's internal configuration from a JSON document. Currently the support is experimental, function signature may change in the future without notice.
handle | handle to Booster object. |
json_parameters | string representation of a JSON document. |
XGB_DLL int XGBoosterLoadModel | ( | BoosterHandle | handle, |
const char * | fname | ||
) |
Load model from existing file.
handle | handle |
fname | File URI or file name. |
XGB_DLL int XGBoosterLoadModelFromBuffer | ( | BoosterHandle | handle, |
const void * | buf, | ||
bst_ulong | len | ||
) |
load model from in memory buffer
handle | handle |
buf | pointer to the buffer |
len | the length of the buffer |
XGB_DLL int XGBoosterLoadRabitCheckpoint | ( | BoosterHandle | handle, |
int * | version | ||
) |
Initialize the booster from rabit checkpoint. This is used in distributed training API.
handle | handle |
version | The output version of the model. |
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)
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:
|
out_len | used to store length of returning result |
out_result | used to set a pointer to array |
XGB_DLL int XGBoosterPredictFromCSR | ( | BoosterHandle | handle, |
char const * | indptr, | ||
char const * | indices, | ||
char const * | values, | ||
bst_ulong | ncol, | ||
char const * | c_json_config, | ||
DMatrixHandle | m, | ||
bst_ulong const ** | out_shape, | ||
bst_ulong * | out_dim, | ||
const float ** | out_result | ||
) |
XGB_DLL int XGBoosterPredictFromCudaArray | ( | BoosterHandle | handle, |
char const * | values, | ||
char const * | c_json_config, | ||
DMatrixHandle | m, | ||
bst_ulong const ** | out_shape, | ||
bst_ulong * | out_dim, | ||
const float ** | out_result | ||
) |
XGB_DLL int XGBoosterPredictFromCudaColumnar | ( | BoosterHandle | handle, |
char const * | values, | ||
char const * | c_json_config, | ||
DMatrixHandle | m, | ||
bst_ulong const ** | out_shape, | ||
bst_ulong * | out_dim, | ||
const float ** | out_result | ||
) |
XGB_DLL int XGBoosterPredictFromDense | ( | BoosterHandle | handle, |
char const * | values, | ||
char const * | c_json_config, | ||
DMatrixHandle | m, | ||
bst_ulong const ** | out_shape, | ||
bst_ulong * | out_dim, | ||
const float ** | out_result | ||
) |
XGB_DLL int XGBoosterPredictFromDMatrix | ( | BoosterHandle | handle, |
DMatrixHandle | dmat, | ||
char const * | c_json_config, | ||
bst_ulong const ** | out_shape, | ||
bst_ulong * | out_dim, | ||
float const ** | out_result | ||
) |
Make prediction from DMatrix, replacing XGBoosterPredict
.
handle | Booster handle |
dmat | DMatrix handle |
c_json_config | String encoded predict configuration in JSON format, with following available fields in the JSON object: |
"type": [0, 6]
Prediction can be run in 2 scenarios:
Example JSON input for running a normal prediction with strict output shape, 2 dim for softprob , 1 dim for others.
out_shape | Shape of output prediction (copy before use). |
out_dim | Dimension of output prediction. |
out_result | Buffer storing prediction value (copy before use). |
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.
handle | handle to Booster object. |
out_len | length of output string |
out_str | A valid pointer to array of characters. The characters array is allocated and managed by XGBoost, while pointer to that array needs to be managed by caller. |
XGB_DLL int XGBoosterSaveModel | ( | BoosterHandle | handle, |
const char * | fname | ||
) |
Save model into existing file.
handle | handle |
fname | File URI or file name. |
XGB_DLL int XGBoosterSaveModelToBuffer | ( | BoosterHandle | handle, |
char const * | json_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.
handle | handle |
json_config | JSON encoded string storing parameters for the function. Following keys are expected in the JSON document: |
"format": str
out_len | The argument to hold the output length |
out_dptr | The argument to hold the output data pointer |
XGB_DLL int XGBoosterSaveRabitCheckpoint | ( | BoosterHandle | handle | ) |
Save the current checkpoint to rabit.
handle | handle |
XGB_DLL int XGBoosterSerializeToBuffer | ( | BoosterHandle | handle, |
bst_ulong * | out_len, | ||
const char ** | out_dptr | ||
) |
Memory snapshot based serialization method. Saves everything states into buffer.
handle | handle |
out_len | the argument to hold the output length |
out_dptr | the argument to hold the output data pointer |
XGB_DLL int XGBoosterSetAttr | ( | BoosterHandle | handle, |
const char * | key, | ||
const char * | value | ||
) |
Set or delete string attribute.
handle | handle |
key | The key of the attribute. |
value | The value to be saved. If nullptr, the attribute would be deleted. |
XGB_DLL int XGBoosterSetParam | ( | BoosterHandle | handle, |
const char * | name, | ||
const char * | value | ||
) |
set parameters
handle | handle |
name | parameter name |
value | value of parameter |
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:
handle | An instance of Booster |
field | Field name |
features | Pointer to array of strings. |
size | Size of features pointer (number of strings passed in). |
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).
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. |
XGB_DLL int XGBoosterUnserializeFromBuffer | ( | BoosterHandle | handle, |
const void * | buf, | ||
bst_ulong | len | ||
) |
Memory snapshot based serialization method. Loads the buffer returned from ‘XGBoosterSerializeToBuffer’.
handle | handle |
buf | pointer to the buffer |
len | the length of the buffer |
XGB_DLL int XGBoosterUpdateOneIter | ( | BoosterHandle | handle, |
int | iter, | ||
DMatrixHandle | dtrain | ||
) |
update the model in one round using dtrain
handle | handle |
iter | current iteration rounds |
dtrain | training data |
XGB_DLL void XGBoostVersion | ( | int * | major, |
int * | minor, | ||
int * | patch | ||
) |
Return the version of the XGBoost library being currently used.
The output variable is only written if it's not NULL.
major | Store the major version number |
minor | Store the minor version number |
patch | Store the patch (revision) number |
XGB_DLL int XGBRegisterLogCallback | ( | void(*)(const char *) | callback | ) |
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 | ( | const char * | json_str | ) |
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.
json_str | a JSON string representing the list of key-value pairs. The JSON object shall be flat: no value can be a JSON object or an array. |
XGB_DLL int XGBuildInfo | ( | char const ** | out | ) |
Get compile information of shared library.
out | string encoded JSON object containing build flags and dependency version. |
XGB_DLL int XGDeviceQuantileDMatrixCreateFromCallback | ( | DataIterHandle | iter, |
DMatrixHandle | proxy, | ||
DataIterResetCallback * | reset, | ||
XGDMatrixCallbackNext * | next, | ||
float | missing, | ||
int | nthread, | ||
int | max_bin, | ||
DMatrixHandle * | out | ||
) |
Create a Quantile DMatrix with data iterator.
Short note for how to use the second set of callback for GPU Hist tree method:
reset
, and next
.XGProxyDMatrixCreate
and hold the handle.XGDeviceQuantileDMatrixCreateFromCallback
.next
functions.See test_iterative_device_dmatrix.cu or Python interface for examples.
iter | A handle to external data iterator. |
proxy | A DMatrix proxy handle created by XGProxyDMatrixCreate . |
reset | Callback function resetting the iterator state. |
next | Callback function yielding the next batch of data. |
missing | Which value to represent missing value |
nthread | Number of threads to use, 0 for default. |
max_bin | Maximum number of bins for building histogram. |
out | The created Device Quantile DMatrix |
XGB_EXTERN_C typedef int XGDMatrixCallbackNext | ( | DataIterHandle | iter | ) |
Callback function prototype for getting next batch of data.
iter | A handler to the user defined iterator. |
XGB_DLL int XGDMatrixCreateFromArrowCallback | ( | XGDMatrixCallbackNext * | next, |
char const * | json_config, | ||
DMatrixHandle * | out | ||
) |
Construct DMatrix from arrow using callbacks. Arrow related C API is not stable and subject to change in the future.
next | Callback function for fetching arrow records. |
json_config | JSON encoded configuration. Required values are: - missing - nthread |
out | The created DMatrix. |
XGB_DLL int XGDMatrixCreateFromCallback | ( | DataIterHandle | iter, |
DMatrixHandle | proxy, | ||
DataIterResetCallback * | reset, | ||
XGDMatrixCallbackNext * | next, | ||
char const * | c_json_config, | ||
DMatrixHandle * | out | ||
) |
Create an external memory DMatrix with data iterator.
Short note for how to use second set of callback for external memory data support:
reset
, and next
.XGProxyDMatrixCreate
and hold the handle.XGDMatrixCreateFromCallback
, along with other parameters encoded as a JSON object.next
functions.For example usage see demo/c-api/external-memory
iter | A handle to external data iterator. |
proxy | A DMatrix proxy handle created by XGProxyDMatrixCreate . |
reset | Callback function resetting the iterator state. |
next | Callback function yielding the next batch of data. |
c_json_config | JSON encoded parameters for DMatrix construction. Accepted fields are: |
[out] | out | The created external memory DMatrix |
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
col_ptr | pointer to col headers |
indices | findex |
data | fvalue |
nindptr | number of rows in the matrix + 1 |
nelem | number of nonzero elements in the matrix |
num_row | number of rows; when it's set to 0, then guess from data |
out | created dmatrix |
XGB_DLL int XGDMatrixCreateFromCSR | ( | char const * | indptr, |
char const * | indices, | ||
char const * | data, | ||
bst_ulong | ncol, | ||
char const * | json_config, | ||
DMatrixHandle * | out | ||
) |
Create a matrix from CSR matrix.
indptr | JSON encoded array_interface to row pointers in CSR. |
indices | JSON encoded array_interface to column indices in CSR. |
data | JSON encoded array_interface to values in CSR. |
num_col | Number of columns. |
json_config | JSON encoded configuration. Required values are: - missing - nthread |
out | created dmatrix |
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
indptr | pointer to row headers |
indices | findex |
data | fvalue |
nindptr | number of rows in the matrix + 1 |
nelem | number of nonzero elements in the matrix |
num_col | number of columns; when it's set to kAdapterUnknownSize, then guess from data |
out | created dmatrix |
XGB_DLL int XGDMatrixCreateFromCudaArrayInterface | ( | char const * | data, |
char const * | json_config, | ||
DMatrixHandle * | out | ||
) |
Create DMatrix from CUDA array.
data | JSON encoded cuda_array_interface for array data. |
json_config | JSON encoded configuration. Required values are: - missing - nthread |
out | created dmatrix |
XGB_DLL int XGDMatrixCreateFromCudaColumnar | ( | char const * | data, |
char const * | json_config, | ||
DMatrixHandle * | out | ||
) |
Create DMatrix from CUDA columnar format. (cuDF)
data | Array of JSON encoded cuda_array_interface for each column. |
json_config | JSON encoded configuration. Required values are: - missing - nthread |
out | created dmatrix |
XGB_DLL int XGDMatrixCreateFromDataIter | ( | DataIterHandle | data_handle, |
XGBCallbackDataIterNext * | callback, | ||
const char * | cache_info, | ||
DMatrixHandle * | out | ||
) |
Create a DMatrix from a data iterator.
data_handle | The handle to the data. |
callback | The callback to get the data. |
cache_info | Additional information about cache file, can be null. |
out | The created DMatrix |
XGB_DLL int XGDMatrixCreateFromDense | ( | char const * | data, |
char const * | json_config, | ||
DMatrixHandle * | out | ||
) |
Create a matrix from dense array.
data | JSON encoded array_interface to array values. |
json_config | JSON encoded configuration. Required values are: - missing - nthread |
out | created dmatrix |
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
data | pointer to pointer to column data |
feature_stypes | pointer to strings |
nrow | number of rows |
ncol | number columns |
out | created dmatrix |
nthread | number of threads (up to maximum cores available, if <=0 use all cores) |
XGB_DLL int XGDMatrixCreateFromFile | ( | const char * | fname, |
int | silent, | ||
DMatrixHandle * | out | ||
) |
load a data matrix
fname | the name of the file |
silent | whether print messages during loading |
out | a loaded data matrix |
XGB_DLL int XGDMatrixCreateFromMat | ( | const float * | data, |
bst_ulong | nrow, | ||
bst_ulong | ncol, | ||
float | missing, | ||
DMatrixHandle * | out | ||
) |
create matrix content from dense matrix
data | pointer to the data space |
nrow | number of rows |
ncol | number columns |
missing | which value to represent missing value |
out | created dmatrix |
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
data | pointer to the data space |
nrow | number of rows |
ncol | number columns |
missing | which value to represent missing value |
out | created dmatrix |
nthread | number of threads (up to maximum cores available, if <=0 use all cores) |
XGB_DLL int XGDMatrixFree | ( | DMatrixHandle | handle | ) |
free space in data 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.
handle | a instance of data matrix |
field | field name |
out_len | used to set result length |
out_dptr | pointer to the result |
XGB_DLL int XGDMatrixGetStrFeatureInfo | ( | DMatrixHandle | handle, |
const char * | field, | ||
bst_ulong * | size, | ||
const char *** | out_features | ||
) |
Get string encoded information of all features.
Accepted fields are:
Caller is responsible for copying out the data, before next call to any API function of XGBoost.
handle | An instance of data matrix |
field | Field name |
size | 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. |
XGB_DLL int XGDMatrixGetUIntInfo | ( | const DMatrixHandle | handle, |
const char * | field, | ||
bst_ulong * | out_len, | ||
const unsigned ** | out_dptr | ||
) |
get uint32 info vector from matrix
handle | a instance of data matrix |
field | field name |
out_len | The length of the field. |
out_dptr | pointer to the result |
XGB_DLL int XGDMatrixNumCol | ( | DMatrixHandle | handle, |
bst_ulong * | out | ||
) |
get number of columns
handle | the handle to the DMatrix |
out | The output of number of columns |
XGB_DLL int XGDMatrixNumRow | ( | DMatrixHandle | handle, |
bst_ulong * | out | ||
) |
get number of rows.
handle | the handle to the DMatrix |
out | The address to hold number of rows. |
XGB_DLL int XGDMatrixSaveBinary | ( | DMatrixHandle | handle, |
const char * | fname, | ||
int | silent | ||
) |
load a data matrix into binary file
handle | a instance of data matrix |
fname | file name |
silent | print statistics when saving |
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:
handle | An instance of data matrix |
field | Field name |
data | Pointer to consecutive memory storing data. |
size | Size of the data, this is relative to size of type. (Meaning NOT number of bytes.) |
type | Indicator of data type. This is defined in xgboost::DataType enum class. |
float = 1 double = 2 uint32_t = 3 uint64_t = 4
XGB_DLL int XGDMatrixSetFloatInfo | ( | DMatrixHandle | handle, |
const char * | field, | ||
const float * | array, | ||
bst_ulong | len | ||
) |
set float vector to a content in info
handle | a instance of data matrix |
field | field name, can be label, weight |
array | pointer to float vector |
len | length of array |
XGB_DLL int XGDMatrixSetGroup | ( | DMatrixHandle | handle, |
const unsigned * | group, | ||
bst_ulong | len | ||
) |
(deprecated) Use XGDMatrixSetUIntInfo instead. Set group of the training matrix
handle | a instance of data matrix |
group | pointer to group size |
len | length of array |
XGB_DLL int XGDMatrixSetInfoFromInterface | ( | DMatrixHandle | handle, |
char const * | field, | ||
char const * | c_interface_str | ||
) |
Set content in array interface to a content in info.
handle | a instance of data matrix |
field | field name. |
c_interface_str | JSON string representation of array interface. |
XGB_DLL int XGDMatrixSetStrFeatureInfo | ( | DMatrixHandle | handle, |
const char * | field, | ||
const char ** | features, | ||
const bst_ulong | size | ||
) |
Set string encoded information of all features.
Accepted fields are:
handle | An instance of data matrix |
field | Field name |
features | Pointer to array of strings. |
size | Size of features pointer (number of strings passed in). |
XGB_DLL int XGDMatrixSetUIntInfo | ( | DMatrixHandle | handle, |
const char * | field, | ||
const unsigned * | array, | ||
bst_ulong | len | ||
) |
set uint32 vector to a content in info
handle | a instance of data matrix |
field | field name |
array | pointer to unsigned int vector |
len | length of array |
XGB_DLL int XGDMatrixSliceDMatrix | ( | DMatrixHandle | handle, |
const int * | idxset, | ||
bst_ulong | len, | ||
DMatrixHandle * | out | ||
) |
create a new dmatrix from sliced content of existing matrix
handle | instance of data matrix to be sliced |
idxset | index set |
len | length of index set |
out | a sliced new 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
handle | instance of data matrix to be sliced |
idxset | index set |
len | length of index set |
out | a sliced new matrix |
allow_groups | allow slicing of an array with groups |
XGB_DLL int XGImportArrowRecordBatch | ( | DataIterHandle | data_handle, |
void * | ptr_array, | ||
void * | ptr_schema | ||
) |
XGB_DLL int XGProxyDMatrixCreate | ( | DMatrixHandle * | out | ) |
Create a DMatrix proxy for setting data, can be free by XGDMatrixFree.
Second set of callback functions, used by constructing Quantile DMatrix or external memory DMatrix using custom iterator.
out | The created Device Quantile DMatrix |
XGB_DLL int XGProxyDMatrixSetDataCSR | ( | DMatrixHandle | handle, |
char const * | indptr, | ||
char const * | indices, | ||
char const * | data, | ||
bst_ulong | ncol | ||
) |
Set data on a DMatrix proxy.
handle | A DMatrix proxy created by XGProxyDMatrixCreate |
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.. |
XGB_DLL int XGProxyDMatrixSetDataCudaArrayInterface | ( | DMatrixHandle | handle, |
const char * | c_interface_str | ||
) |
Set data on a DMatrix proxy.
handle | A DMatrix proxy created by XGProxyDMatrixCreate |
c_interface_str | Null terminated JSON document string representation of CUDA array interface. |
XGB_DLL int XGProxyDMatrixSetDataCudaColumnar | ( | DMatrixHandle | handle, |
const char * | c_interface_str | ||
) |
Set data on a DMatrix proxy.
handle | A DMatrix proxy created by XGProxyDMatrixCreate |
c_interface_str | Null terminated JSON document string representation of CUDA array interface, with an array of columns. |
XGB_DLL int XGProxyDMatrixSetDataDense | ( | DMatrixHandle | handle, |
char const * | c_interface_str | ||
) |
Set data on a DMatrix proxy.
handle | A DMatrix proxy created by XGProxyDMatrixCreate |
c_interface_str | Null terminated JSON document string representation of array interface. |