xgboost
c_api.h
Go to the documentation of this file.
1 
7 #ifndef XGBOOST_C_API_H_
8 #define XGBOOST_C_API_H_
9 
10 #ifdef __cplusplus
11 #define XGB_EXTERN_C extern "C"
12 #include <cstdio>
13 #include <cstdint>
14 #else
15 #define XGB_EXTERN_C
16 #include <stdio.h>
17 #include <stdint.h>
18 #endif // __cplusplus
19 
20 #if defined(_MSC_VER) || defined(_WIN32)
21 #define XGB_DLL XGB_EXTERN_C __declspec(dllexport)
22 #else
23 #define XGB_DLL XGB_EXTERN_C
24 #endif // defined(_MSC_VER) || defined(_WIN32)
25 
26 // manually define unsigned long
27 typedef uint64_t bst_ulong; // NOLINT(*)
28 
29 
31 typedef void *DMatrixHandle; // NOLINT(*)
33 typedef void *BoosterHandle; // NOLINT(*)
35 typedef void *DataIterHandle; // NOLINT(*)
37 typedef void *DataHolderHandle; // NOLINT(*)
38 
40 typedef struct { // NOLINT(*)
42  size_t size;
44 #ifdef __APPLE__
45  /* Necessary as Java on MacOS defines jlong as long int
46  * and gcc defines int64_t as long long int. */
47  long* offset; // NOLINT(*)
48 #else
49  int64_t* offset; // NOLINT(*)
50 #endif // __APPLE__
51 
52  float* label;
54  float* weight;
56  int* index;
58  float* value;
60 
70 XGB_DLL void XGBoostVersion(int* major, int* minor, int* patch);
71 
77 XGB_EXTERN_C typedef int XGBCallbackSetData( // NOLINT(*)
78  DataHolderHandle handle, XGBoostBatchCSR batch);
79 
91 XGB_EXTERN_C typedef int XGBCallbackDataIterNext( // NOLINT(*)
92  DataIterHandle data_handle, XGBCallbackSetData *set_function,
93  DataHolderHandle set_function_handle);
94 
105 XGB_DLL const char *XGBGetLastError(void);
106 
114 XGB_DLL int XGBRegisterLogCallback(void (*callback)(const char*));
115 
123 XGB_DLL int XGDMatrixCreateFromFile(const char *fname,
124  int silent,
125  DMatrixHandle *out);
126 
136  DataIterHandle data_handle,
137  XGBCallbackDataIterNext* callback,
138  const char* cache_info,
139  DMatrixHandle *out);
140 
152 XGB_DLL int XGDMatrixCreateFromCSREx(const size_t* indptr,
153  const unsigned* indices,
154  const float* data,
155  size_t nindptr,
156  size_t nelem,
157  size_t num_col,
158  DMatrixHandle* out);
170 XGB_DLL int XGDMatrixCreateFromCSCEx(const size_t* col_ptr,
171  const unsigned* indices,
172  const float* data,
173  size_t nindptr,
174  size_t nelem,
175  size_t num_row,
176  DMatrixHandle* out);
177 
187 XGB_DLL int XGDMatrixCreateFromMat(const float *data,
188  bst_ulong nrow,
189  bst_ulong ncol,
190  float missing,
191  DMatrixHandle *out);
202 XGB_DLL int XGDMatrixCreateFromMat_omp(const float *data, // NOLINT
203  bst_ulong nrow, bst_ulong ncol,
204  float missing, DMatrixHandle *out,
205  int nthread);
216 XGB_DLL int XGDMatrixCreateFromDT(void** data,
217  const char ** feature_stypes,
218  bst_ulong nrow,
219  bst_ulong ncol,
220  DMatrixHandle* out,
221  int nthread);
231  const int *idxset,
232  bst_ulong len,
233  DMatrixHandle *out);
244  const int *idxset,
245  bst_ulong len,
246  DMatrixHandle *out,
247  int allow_groups);
261  const char *fname, int silent);
271  const char *field,
272  const float *array,
273  bst_ulong len);
283  const char *field,
284  const unsigned *array,
285  bst_ulong len);
286 
295  const unsigned *group,
296  bst_ulong len);
297 
307  const char *field,
308  bst_ulong* out_len,
309  const float **out_dptr);
319  const char *field,
320  bst_ulong* out_len,
321  const unsigned **out_dptr);
329  bst_ulong *out);
337  bst_ulong *out);
338 // --- start XGBoost class
346 XGB_DLL int XGBoosterCreate(const DMatrixHandle dmats[],
347  bst_ulong len,
348  BoosterHandle *out);
355 
364  const char *name,
365  const char *value);
366 
375  int iter,
376  DMatrixHandle dtrain);
388  DMatrixHandle dtrain,
389  float *grad,
390  float *hess,
391  bst_ulong len);
403  int iter,
404  DMatrixHandle dmats[],
405  const char *evnames[],
406  bst_ulong len,
407  const char **out_result);
425  DMatrixHandle dmat,
426  int option_mask,
427  unsigned ntree_limit,
428  int training,
429  bst_ulong *out_len,
430  const float **out_result);
431 /*
432  * Short note for serialization APIs. There are 3 different sets of serialization API.
433  *
434  * - Functions with the term "Model" handles saving/loading XGBoost model like trees or
435  * linear weights. Striping out parameters configuration like training algorithms or
436  * CUDA device ID helps user to reuse the trained model for different tasks, examples
437  * are prediction, training continuation or interpretation.
438  *
439  * - Functions with the term "Config" handles save/loading configuration. It helps user
440  * to study the internal of XGBoost. Also user can use the load method for specifying
441  * paramters in a structured way. These functions are introduced in 1.0.0, and are not
442  * yet stable.
443  *
444  * - Functions with the term "Serialization" are combined of above two. They are used in
445  * situations like check-pointing, or continuing training task in distributed
446  * environment. In these cases the task must be carried out without any user
447  * intervention.
448  */
449 
457  const char *fname);
465  const char *fname);
474  const void *buf,
475  bst_ulong len);
485  const char **out_dptr);
486 
497  const char **out_dptr);
508  const void *buf, bst_ulong len);
509 
518  int* version);
519 
526 
527 
540  char const **out_str);
551  char const *json_parameters);
552 
563  const char *fmap,
564  int with_stats,
565  bst_ulong *out_len,
566  const char ***out_dump_array);
567 
579  const char *fmap,
580  int with_stats,
581  const char *format,
582  bst_ulong *out_len,
583  const char ***out_dump_array);
584 
597  int fnum,
598  const char **fname,
599  const char **ftype,
600  int with_stats,
601  bst_ulong *out_len,
602  const char ***out_models);
603 
617  int fnum,
618  const char **fname,
619  const char **ftype,
620  int with_stats,
621  const char *format,
622  bst_ulong *out_len,
623  const char ***out_models);
624 
634  const char* key,
635  const char** out,
636  int *success);
647  const char* key,
648  const char* value);
657  bst_ulong* out_len,
658  const char*** out);
659 #endif // XGBOOST_C_API_H_
void * BoosterHandle
handle to Booster
Definition: c_api.h:33
XGB_DLL int XGBoosterSetParam(BoosterHandle handle, const char *name, const char *value)
set parameters
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...
#define XGB_DLL
Definition: c_api.h:23
int64_t * offset
row pointer to the rows in the data
Definition: c_api.h:49
void * DataIterHandle
handle to a data iterator
Definition: c_api.h:35
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 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 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 XGDMatrixCreateFromDataIter(DataIterHandle data_handle, XGBCallbackDataIterNext *callback, const char *cache_info, DMatrixHandle *out)
Create a DMatrix from a data iterator.
void * DMatrixHandle
handle to DMatrix
Definition: c_api.h:31
XGB_DLL int XGBoosterFree(BoosterHandle handle)
free obj in handle
XGB_DLL int XGDMatrixSetUIntInfo(DMatrixHandle handle, const char *field, const unsigned *array, bst_ulong len)
set uint32 vector to a content in info
Mini batch used in XGBoost Data Iteration.
Definition: c_api.h:40
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 void XGBoostVersion(int *major, int *minor, int *patch)
Return the version of the XGBoost library being currently used.
XGB_DLL int XGDMatrixFree(DMatrixHandle handle)
free space in data matrix
XGB_DLL int XGDMatrixSetGroup(DMatrixHandle handle, const unsigned *group, bst_ulong len)
(deprecated) Use XGDMatrixSetUIntInfo instead. Set group of the training matrix
uint64_t bst_ulong
Definition: c_api.h:27
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
size_t size
number of rows in the minibatch
Definition: c_api.h:42
void * DataHolderHandle
handle to a internal data holder.
Definition: c_api.h:37
XGB_EXTERN_C typedef int XGBCallbackSetData(DataHolderHandle handle, XGBoostBatchCSR batch)
Callback to set the data to handle,.
XGB_DLL int XGDMatrixSetFloatInfo(DMatrixHandle handle, const char *field, const float *array, bst_ulong len)
set float vector to a content in info
#define XGB_EXTERN_C
Definition: c_api.h:15
XGB_DLL int XGBoosterLoadModel(BoosterHandle handle, const char *fname)
Load model from existing file.
XGB_DLL int XGBoosterLoadJsonConfig(BoosterHandle handle, char const *json_parameters)
Load XGBoost&#39;s internal configuration from a JSON document. Currently the support is experimental...
XGB_DLL int XGDMatrixCreateFromFile(const char *fname, int silent, DMatrixHandle *out)
load a data matrix
XGB_DLL int XGBoosterUpdateOneIter(BoosterHandle handle, int iter, DMatrixHandle dtrain)
update the model in one round using dtrain
XGB_DLL int XGBoosterGetAttr(BoosterHandle handle, const char *key, const char **out, int *success)
Get string attribute from Booster.
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 XGBoosterSaveJsonConfig(BoosterHandle handle, bst_ulong *out_len, char const **out_str)
Save XGBoost&#39;s internal configuration into a JSON document. Currently the support is experimental...
float * weight
weight of each instance, can be NULL
Definition: c_api.h:54
XGB_DLL int XGDMatrixSaveBinary(DMatrixHandle handle, const char *fname, int silent)
load a data matrix into binary file
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 XGDMatrixGetUIntInfo(const DMatrixHandle handle, const char *field, bst_ulong *out_len, const unsigned **out_dptr)
get uint32 info vector from matrix
XGB_DLL const char * XGBGetLastError(void)
get string message of the last error
XGB_DLL int XGBoosterSaveModel(BoosterHandle handle, const char *fname)
Save model into existing file.
XGB_DLL int XGBoosterSetAttr(BoosterHandle handle, const char *key, const char *value)
Set or delete string attribute.
XGB_DLL int XGBoosterCreate(const DMatrixHandle dmats[], bst_ulong len, BoosterHandle *out)
create xgboost learner
float * label
labels of each instance
Definition: c_api.h:52
XGB_DLL int XGDMatrixSliceDMatrix(DMatrixHandle handle, const int *idxset, bst_ulong len, DMatrixHandle *out)
create a new dmatrix from sliced content of existing matrix
float * value
feature values
Definition: c_api.h:58
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 XGBoosterSerializeToBuffer(BoosterHandle handle, bst_ulong *out_len, const char **out_dptr)
Memory snapshot based serialization method. Saves everything states into buffer.
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 XGBRegisterLogCallback(void(*callback)(const char *))
register callback function for LOG(INFO) messages – helpful messages that are not errors...
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 XGBoosterLoadRabitCheckpoint(BoosterHandle handle, int *version)
Initialize the booster from rabit checkpoint. This is used in distributed training API...
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
XGB_DLL int XGBoosterUnserializeFromBuffer(BoosterHandle handle, const void *buf, bst_ulong len)
Memory snapshot based serialization method. Loads the buffer returned from `XGBoosterSerializeToBuffe...
XGB_DLL int XGDMatrixNumRow(DMatrixHandle handle, bst_ulong *out)
get number of rows.
XGB_DLL int XGBoosterLoadModelFromBuffer(BoosterHandle handle, const void *buf, bst_ulong len)
load model from in memory buffer
XGB_DLL int XGDMatrixNumCol(DMatrixHandle handle, bst_ulong *out)
get number of columns
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
int * index
feature index
Definition: c_api.h:56
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 XGBoosterSaveRabitCheckpoint(BoosterHandle handle)
Save the current checkpoint to rabit.
XGB_DLL int XGBoosterGetAttrNames(BoosterHandle handle, bst_ulong *out_len, const char ***out)
Get the names of all attribute from Booster.
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 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...