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... | |
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 | 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_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 reseting external 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 device DMatrix with data iterator. More... | |
XGB_DLL int | XGDeviceQuantileDMatrixSetDataCudaArrayInterface (DMatrixHandle handle, const char *c_interface_str) |
Set data on a DMatrix proxy. More... | |
XGB_DLL int | XGDeviceQuantileDMatrixSetDataCudaColumnar (DMatrixHandle handle, const char *c_interface_str) |
Set data on a DMatrix proxy. 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 *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 | XGBoosterGetModelRaw (BoosterHandle handle, bst_ulong *out_len, const char **out_dptr) |
save model into binary raw bytes, return header of the array user must copy the result out, before next xgboost call 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... | |
C API of XGBoost, used for interfacing to other languages.
Copyright (c) 2015~2020 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
typedef void* DMatrixHandle |
handle to DMatrix
XGB_EXTERN_C typedef void DataIterResetCallback | ( | DataIterHandle | handle | ) |
Callback function prototype for reseting 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 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 | ||
) |
save model into binary raw bytes, return header of the array user must copy the result out, before next xgboost call
handle | handle |
out_len | the argument to hold the output length |
out_dptr | the argument to hold the output data pointer |
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 | Feild 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] 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:
Run 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 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 | Feild 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 XGDeviceQuantileDMatrixCreateFromCallback | ( | DataIterHandle | iter, |
DMatrixHandle | proxy, | ||
DataIterResetCallback * | reset, | ||
XGDMatrixCallbackNext * | next, | ||
float | missing, | ||
int | nthread, | ||
int | max_bin, | ||
DMatrixHandle * | out | ||
) |
Create a device DMatrix with data iterator.
iter | A handle to external data iterator. |
proxy | A DMatrix proxy handle created by XGProxyDMatrixCreate . |
reset | Callback function reseting the iterator state. |
next | Callback function yieling 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_DLL int XGDeviceQuantileDMatrixSetDataCudaArrayInterface | ( | 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 XGDeviceQuantileDMatrixSetDataCudaColumnar | ( | 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_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 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 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 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 | Feild 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 * | data, | ||
bst_ulong | size, | ||
int | type | ||
) |
Set meta info from dense matrix. Valid field names are:
handle | An instance of data matrix |
field | Feild 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 | Feild 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 XGProxyDMatrixCreate | ( | DMatrixHandle * | out | ) |
Create a DMatrix proxy for setting data, can be free by XGDMatrixFree.
out | The created Device Quantile DMatrix |