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 __attribute__ ((visibility ("default")))
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;
43 /* \brief number of columns in the minibatch. */
44 size_t columns;
46 #ifdef __APPLE__
47 /* Necessary as Java on MacOS defines jlong as long int
48 * and gcc defines int64_t as long long int. */
49 long* offset; // NOLINT(*)
50 #else
51 int64_t* offset; // NOLINT(*)
52 #endif // __APPLE__
53
54 float* label;
56 float* weight;
58 int* index;
60 float* value;
61 } XGBoostBatchCSR;
62
72 XGB_DLL void XGBoostVersion(int* major, int* minor, int* patch);
73
79 XGB_EXTERN_C typedef int XGBCallbackSetData( // NOLINT(*)
80 DataHolderHandle handle, XGBoostBatchCSR batch);
81
93 XGB_EXTERN_C typedef int XGBCallbackDataIterNext( // NOLINT(*)
94 DataIterHandle data_handle, XGBCallbackSetData *set_function,
95 DataHolderHandle set_function_handle);
96
107 XGB_DLL const char *XGBGetLastError(void);
108
116 XGB_DLL int XGBRegisterLogCallback(void (*callback)(const char*));
117
125 XGB_DLL int XGDMatrixCreateFromFile(const char *fname,
126 int silent,
127 DMatrixHandle *out);
128
137 XGB_DLL int XGDMatrixCreateFromDataIter(
138 DataIterHandle data_handle,
139 XGBCallbackDataIterNext* callback,
140 const char* cache_info,
141 DMatrixHandle *out);
142
154 XGB_DLL int XGDMatrixCreateFromCSREx(const size_t* indptr,
155 const unsigned* indices,
156 const float* data,
157 size_t nindptr,
158 size_t nelem,
159 size_t num_col,
160 DMatrixHandle* out);
172 XGB_DLL int XGDMatrixCreateFromCSCEx(const size_t* col_ptr,
173 const unsigned* indices,
174 const float* data,
175 size_t nindptr,
176 size_t nelem,
177 size_t num_row,
178 DMatrixHandle* out);
179
189 XGB_DLL int XGDMatrixCreateFromMat(const float *data,
190 bst_ulong nrow,
191 bst_ulong ncol,
192 float missing,
193 DMatrixHandle *out);
204 XGB_DLL int XGDMatrixCreateFromMat_omp(const float *data, // NOLINT
205 bst_ulong nrow, bst_ulong ncol,
206 float missing, DMatrixHandle *out,
207 int nthread);
218 XGB_DLL int XGDMatrixCreateFromDT(void** data,
219 const char ** feature_stypes,
220 bst_ulong nrow,
221 bst_ulong ncol,
222 DMatrixHandle* out,
223 int nthread);
232 XGB_DLL int XGDMatrixSliceDMatrix(DMatrixHandle handle,
233 const int *idxset,
234 bst_ulong len,
235 DMatrixHandle *out);
245 XGB_DLL int XGDMatrixSliceDMatrixEx(DMatrixHandle handle,
246 const int *idxset,
247 bst_ulong len,
248 DMatrixHandle *out,
249 int allow_groups);
254 XGB_DLL int XGDMatrixFree(DMatrixHandle handle);
262 XGB_DLL int XGDMatrixSaveBinary(DMatrixHandle handle,
263 const char *fname, int silent);
272 XGB_DLL int XGDMatrixSetFloatInfo(DMatrixHandle handle,
273 const char *field,
274 const float *array,
275 bst_ulong len);
284 XGB_DLL int XGDMatrixSetUIntInfo(DMatrixHandle handle,
285 const char *field,
286 const unsigned *array,
287 bst_ulong len);
288
296 XGB_DLL int XGDMatrixSetGroup(DMatrixHandle handle,
297 const unsigned *group,
298 bst_ulong len);
299
308 XGB_DLL int XGDMatrixGetFloatInfo(const DMatrixHandle handle,
309 const char *field,
310 bst_ulong* out_len,
311 const float **out_dptr);
320 XGB_DLL int XGDMatrixGetUIntInfo(const DMatrixHandle handle,
321 const char *field,
322 bst_ulong* out_len,
323 const unsigned **out_dptr);
330 XGB_DLL int XGDMatrixNumRow(DMatrixHandle handle,
331 bst_ulong *out);
338 XGB_DLL int XGDMatrixNumCol(DMatrixHandle handle,
339 bst_ulong *out);
340 // --- start XGBoost class
348 XGB_DLL int XGBoosterCreate(const DMatrixHandle dmats[],
349 bst_ulong len,
350 BoosterHandle *out);
356 XGB_DLL int XGBoosterFree(BoosterHandle handle);
357
365 XGB_DLL int XGBoosterSetParam(BoosterHandle handle,
366 const char *name,
367 const char *value);
368
376 XGB_DLL int XGBoosterUpdateOneIter(BoosterHandle handle,
377 int iter,
378 DMatrixHandle dtrain);
389 XGB_DLL int XGBoosterBoostOneIter(BoosterHandle handle,
390 DMatrixHandle dtrain,
391 float *grad,
392 float *hess,
393 bst_ulong len);
404 XGB_DLL int XGBoosterEvalOneIter(BoosterHandle handle,
405 int iter,
406 DMatrixHandle dmats[],
407 const char *evnames[],
408 bst_ulong len,
409 const char **out_result);
433 XGB_DLL int XGBoosterPredict(BoosterHandle handle,
434 DMatrixHandle dmat,
435 int option_mask,
436 unsigned ntree_limit,
437 int training,
438 bst_ulong *out_len,
439 const float **out_result);
440 /*
441 * Short note for serialization APIs. There are 3 different sets of serialization API.
442 *
443 * - Functions with the term "Model" handles saving/loading XGBoost model like trees or
444 * linear weights. Striping out parameters configuration like training algorithms or
445 * CUDA device ID helps user to reuse the trained model for different tasks, examples
446 * are prediction, training continuation or interpretation.
447 *
448 * - Functions with the term "Config" handles save/loading configuration. It helps user
449 * to study the internal of XGBoost. Also user can use the load method for specifying
450 * paramters in a structured way. These functions are introduced in 1.0.0, and are not
451 * yet stable.
452 *
453 * - Functions with the term "Serialization" are combined of above two. They are used in
454 * situations like check-pointing, or continuing training task in distributed
455 * environment. In these cases the task must be carried out without any user
456 * intervention.
457 */
458
465 XGB_DLL int XGBoosterLoadModel(BoosterHandle handle,
466 const char *fname);
473 XGB_DLL int XGBoosterSaveModel(BoosterHandle handle,
474 const char *fname);
482 XGB_DLL int XGBoosterLoadModelFromBuffer(BoosterHandle handle,
483 const void *buf,
484 bst_ulong len);
493 XGB_DLL int XGBoosterGetModelRaw(BoosterHandle handle, bst_ulong *out_len,
494 const char **out_dptr);
495
505 XGB_DLL int XGBoosterSerializeToBuffer(BoosterHandle handle, bst_ulong *out_len,
506 const char **out_dptr);
516 XGB_DLL int XGBoosterUnserializeFromBuffer(BoosterHandle handle,
517 const void *buf, bst_ulong len);
518
526 XGB_DLL int XGBoosterLoadRabitCheckpoint(BoosterHandle handle,
527 int* version);
528
534 XGB_DLL int XGBoosterSaveRabitCheckpoint(BoosterHandle handle);
535
536
549 XGB_DLL int XGBoosterSaveJsonConfig(BoosterHandle handle, bst_ulong *out_len,
550 char const **out_str);
560 XGB_DLL int XGBoosterLoadJsonConfig(BoosterHandle handle,
561 char const *json_parameters);
562
572 XGB_DLL int XGBoosterDumpModel(BoosterHandle handle,
573 const char *fmap,
574 int with_stats,
575 bst_ulong *out_len,
576 const char ***out_dump_array);
577
588 XGB_DLL int XGBoosterDumpModelEx(BoosterHandle handle,
589 const char *fmap,
590 int with_stats,
591 const char *format,
592 bst_ulong *out_len,
593 const char ***out_dump_array);
594
606 XGB_DLL int XGBoosterDumpModelWithFeatures(BoosterHandle handle,
607 int fnum,
608 const char **fname,
609 const char **ftype,
610 int with_stats,
611 bst_ulong *out_len,
612 const char ***out_models);
613
626 XGB_DLL int XGBoosterDumpModelExWithFeatures(BoosterHandle handle,
627 int fnum,
628 const char **fname,
629 const char **ftype,
630 int with_stats,
631 const char *format,
632 bst_ulong *out_len,
633 const char ***out_models);
634
643 XGB_DLL int XGBoosterGetAttr(BoosterHandle handle,
644 const char* key,
645 const char** out,
646 int *success);
656 XGB_DLL int XGBoosterSetAttr(BoosterHandle handle,
657 const char* key,
658 const char* value);
666 XGB_DLL int XGBoosterGetAttrNames(BoosterHandle handle,
667 bst_ulong* out_len,
668 const char*** out);
669 #endif // XGBOOST_C_API_H_
BoosterHandle
void * BoosterHandle
handle to Booster
Definition: c_api.h:33
XGBoosterSetParam
XGB_DLL int XGBoosterSetParam(BoosterHandle handle, const char *name, const char *value)
set parameters
XGBoosterGetModelRaw
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...
XGB_DLL
#define XGB_DLL
Definition: c_api.h:23
XGBoostBatchCSR::offset
int64_t * offset
row pointer to the rows in the data
Definition: c_api.h:51
DataIterHandle
void * DataIterHandle
handle to a data iterator
Definition: c_api.h:35
XGBoosterDumpModelEx
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
XGBoosterDumpModel
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
XGBoosterEvalOneIter
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
XGDMatrixCreateFromDataIter
XGB_DLL int XGDMatrixCreateFromDataIter(DataIterHandle data_handle, XGBCallbackDataIterNext *callback, const char *cache_info, DMatrixHandle *out)
Create a DMatrix from a data iterator.
DMatrixHandle
void * DMatrixHandle
handle to DMatrix
Definition: c_api.h:31
XGBoosterFree
XGB_DLL int XGBoosterFree(BoosterHandle handle)
free obj in handle
XGDMatrixSetUIntInfo
XGB_DLL int XGDMatrixSetUIntInfo(DMatrixHandle handle, const char *field, const unsigned *array, bst_ulong len)
set uint32 vector to a content in info
XGBoostBatchCSR
Mini batch used in XGBoost Data Iteration.
Definition: c_api.h:40
XGBoosterDumpModelWithFeatures
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
XGBoostVersion
XGB_DLL void XGBoostVersion(int *major, int *minor, int *patch)
Return the version of the XGBoost library being currently used.
XGDMatrixFree
XGB_DLL int XGDMatrixFree(DMatrixHandle handle)
free space in data matrix
XGDMatrixSetGroup
XGB_DLL int XGDMatrixSetGroup(DMatrixHandle handle, const unsigned *group, bst_ulong len)
(deprecated) Use XGDMatrixSetUIntInfo instead. Set group of the training matrix
bst_ulong
uint64_t bst_ulong
Definition: c_api.h:27
XGDMatrixCreateFromDT
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
XGBoostBatchCSR::size
size_t size
number of rows in the minibatch
Definition: c_api.h:42
DataHolderHandle
void * DataHolderHandle
handle to a internal data holder.
Definition: c_api.h:37
XGBCallbackSetData
XGB_EXTERN_C typedef int XGBCallbackSetData(DataHolderHandle handle, XGBoostBatchCSR batch)
Callback to set the data to handle,.
XGDMatrixSetFloatInfo
XGB_DLL int XGDMatrixSetFloatInfo(DMatrixHandle handle, const char *field, const float *array, bst_ulong len)
set float vector to a content in info
XGB_EXTERN_C
#define XGB_EXTERN_C
Definition: c_api.h:15
XGBoosterLoadModel
XGB_DLL int XGBoosterLoadModel(BoosterHandle handle, const char *fname)
Load model from existing file.
XGBoosterLoadJsonConfig
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...
XGDMatrixCreateFromFile
XGB_DLL int XGDMatrixCreateFromFile(const char *fname, int silent, DMatrixHandle *out)
load a data matrix
XGBoosterUpdateOneIter
XGB_DLL int XGBoosterUpdateOneIter(BoosterHandle handle, int iter, DMatrixHandle dtrain)
update the model in one round using dtrain
XGBoosterGetAttr
XGB_DLL int XGBoosterGetAttr(BoosterHandle handle, const char *key, const char **out, int *success)
Get string attribute from Booster.
XGDMatrixCreateFromCSREx
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
XGBoosterSaveJsonConfig
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...
XGBoostBatchCSR::weight
float * weight
weight of each instance, can be NULL
Definition: c_api.h:56
XGDMatrixSaveBinary
XGB_DLL int XGDMatrixSaveBinary(DMatrixHandle handle, const char *fname, int silent)
load a data matrix into binary file
XGDMatrixCreateFromCSCEx
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
XGDMatrixGetUIntInfo
XGB_DLL int XGDMatrixGetUIntInfo(const DMatrixHandle handle, const char *field, bst_ulong *out_len, const unsigned **out_dptr)
get uint32 info vector from matrix
XGBGetLastError
XGB_DLL const char * XGBGetLastError(void)
get string message of the last error
XGBoosterSaveModel
XGB_DLL int XGBoosterSaveModel(BoosterHandle handle, const char *fname)
Save model into existing file.
XGBoosterSetAttr
XGB_DLL int XGBoosterSetAttr(BoosterHandle handle, const char *key, const char *value)
Set or delete string attribute.
XGBoosterCreate
XGB_DLL int XGBoosterCreate(const DMatrixHandle dmats[], bst_ulong len, BoosterHandle *out)
create xgboost learner
XGBoostBatchCSR::label
float * label
labels of each instance
Definition: c_api.h:54
XGDMatrixSliceDMatrix
XGB_DLL int XGDMatrixSliceDMatrix(DMatrixHandle handle, const int *idxset, bst_ulong len, DMatrixHandle *out)
create a new dmatrix from sliced content of existing matrix
XGBoostBatchCSR::value
float * value
feature values
Definition: c_api.h:60
XGDMatrixGetFloatInfo
XGB_DLL int XGDMatrixGetFloatInfo(const DMatrixHandle handle, const char *field, bst_ulong *out_len, const float **out_dptr)
get float info vector from matrix.
XGBoosterSerializeToBuffer
XGB_DLL int XGBoosterSerializeToBuffer(BoosterHandle handle, bst_ulong *out_len, const char **out_dptr)
Memory snapshot based serialization method. Saves everything states into buffer.
XGDMatrixCreateFromMat
XGB_DLL int XGDMatrixCreateFromMat(const float *data, bst_ulong nrow, bst_ulong ncol, float missing, DMatrixHandle *out)
create matrix content from dense matrix
XGBRegisterLogCallback
XGB_DLL int XGBRegisterLogCallback(void(*callback)(const char *))
register callback function for LOG(INFO) messages – helpful messages that are not errors...
XGBoosterDumpModelExWithFeatures
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
XGBoosterLoadRabitCheckpoint
XGB_DLL int XGBoosterLoadRabitCheckpoint(BoosterHandle handle, int *version)
Initialize the booster from rabit checkpoint. This is used in distributed training API...
XGBoosterPredict
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
XGBoosterUnserializeFromBuffer
XGB_DLL int XGBoosterUnserializeFromBuffer(BoosterHandle handle, const void *buf, bst_ulong len)
Memory snapshot based serialization method. Loads the buffer returned from `XGBoosterSerializeToBuffe...
XGDMatrixNumRow
XGB_DLL int XGDMatrixNumRow(DMatrixHandle handle, bst_ulong *out)
get number of rows.
XGBoosterLoadModelFromBuffer
XGB_DLL int XGBoosterLoadModelFromBuffer(BoosterHandle handle, const void *buf, bst_ulong len)
load model from in memory buffer
XGDMatrixNumCol
XGB_DLL int XGDMatrixNumCol(DMatrixHandle handle, bst_ulong *out)
get number of columns
XGDMatrixSliceDMatrixEx
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
XGBoostBatchCSR::index
int * index
feature index
Definition: c_api.h:58
XGBCallbackDataIterNext
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...
XGBoostBatchCSR::columns
size_t columns
Definition: c_api.h:44
XGBoosterSaveRabitCheckpoint
XGB_DLL int XGBoosterSaveRabitCheckpoint(BoosterHandle handle)
Save the current checkpoint to rabit.
XGBoosterGetAttrNames
XGB_DLL int XGBoosterGetAttrNames(BoosterHandle handle, bst_ulong *out_len, const char ***out)
Get the names of all attribute from Booster.
XGDMatrixCreateFromMat_omp
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
XGBoosterBoostOneIter
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...