xgboost

Classes | Macros | Typedefs | Functions
c_api.h File Reference

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

`#include <stdio.h>`
`#include <stdint.h>`
Include dependency graph for c_api.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 | 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 | 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 | 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 More...
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...

## Detailed Description

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

Copyright (c) 2015~2020 by Contributors

Author
  Tianqi Chen

## Macro Definition Documentation

## ◆ XGB_DLL

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

## ◆ XGB_EXTERN_C

#define XGB_EXTERN_C

## Typedef Documentation

## ◆ BoosterHandle

typedef void* BoosterHandle

handle to Booster

## ◆ bst_ulong

typedef uint64_t bst_ulong

## ◆ DataHolderHandle

typedef void* DataHolderHandle

handle to a internal data holder.

## ◆ DataIterHandle

typedef void* DataIterHandle

handle to a external data iterator

## ◆ DMatrixHandle

typedef void* DMatrixHandle

handle to DMatrix

## Function Documentation

## ◆ DataIterResetCallback()

XGB_EXTERN_C typedef void DataIterResetCallback | ( | DataIterHandle | handle | ) |

Callback function prototype for reseting external iterator.

## ◆ 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.

If there is data, the function will call set_function to set the data.

Parameters

  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.

Returns
  0 if we are reaching the end and batch is not returned.

## ◆ XGBCallbackSetData()

XGB_EXTERN_C typedef int XGBCallbackSetData | ( | DataHolderHandle | handle,
|  | XGBoostBatchCSR | batch
| ) |  |

Callback to set the data to handle,.

Parameters

  handle | The handle to the callback.
  batch | The data content to be set.

## ◆ XGBGetLastError()

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

Returns
  const char* error information

## ◆ 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 UpdateOneIter, to support customized loss function

Parameters

  handle | handle
  dtrain | training data
  grad | gradient statistics
  hess | second order gradient statistics
  len | length of grad/hess array

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterCreate()

XGB_DLL int XGBoosterCreate | ( | const DMatrixHandle | dmats[],
|  | bst_ulong | len,
|  | BoosterHandle * | out
| ) |  |

create xgboost learner

Parameters

  dmats | matrices that are set to be cached
  len | length of dmats
  out | handle to the result booster

Returns
  0 when success, -1 when failure happens

## ◆ 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

Parameters

  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

Returns
  0 when success, -1 when failure happens

## ◆ 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

Parameters

  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

Returns
  0 when success, -1 when failure happens

## ◆ 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

Parameters

  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

Returns
  0 when success, -1 when failure happens

## ◆ 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

Parameters

  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

Returns
  0 when success, -1 when failure happens

## ◆ 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

Parameters

  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

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterFree()

XGB_DLL int XGBoosterFree | ( | BoosterHandle | handle | ) |

free obj in handle

Parameters

  handle | handle to be freed

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterGetAttr()

XGB_DLL int XGBoosterGetAttr | ( | BoosterHandle | handle,
|  | const char * | key,
|  | const char ** | out,
|  | int * | success
| ) |  |

Get string attribute from Booster.

Parameters

  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.

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterGetAttrNames()

XGB_DLL int XGBoosterGetAttrNames | ( | BoosterHandle | handle,
|  | bst_ulong * | out_len,
|  | const char *** | out
| ) |  |

Get the names of all attribute from Booster.

Parameters

  handle | handle
  out_len | the argument to hold the output length
  out | pointer to hold the output attribute stings

Returns
  0 when success, -1 when failure happens

## ◆ 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, before next xgboost call

Parameters

  handle | handle
  out_len | the argument to hold the output length
  out_dptr | the argument to hold the output data pointer

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterGetNumFeature()

XGB_DLL int XGBoosterGetNumFeature | ( | BoosterHandle | handle,
|  | bst_ulong * | out
| ) |  |

get number of features

Parameters

  out | number of features

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterLoadJsonConfig()

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.

Parameters

  handle | handle to Booster object.
  json_parameters | string representation of a JSON document.

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterLoadModel()

XGB_DLL int XGBoosterLoadModel | ( | BoosterHandle | handle,
|  | const char * | fname
| ) |  |

Load model from existing file.

Parameters

  handle | handle
  fname | File URI or file name.

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterLoadModelFromBuffer()

XGB_DLL int XGBoosterLoadModelFromBuffer | ( | BoosterHandle | handle,
|  | const void * | buf,
|  | bst_ulong | len
| ) |  |

load model from in memory buffer

Parameters

  handle | handle
  buf | pointer to the buffer
  len | the length of the buffer

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterLoadRabitCheckpoint()

XGB_DLL int XGBoosterLoadRabitCheckpoint | ( | BoosterHandle | handle,
|  | int * | version
| ) |  |

Initialize the booster from rabit checkpoint. This is used in distributed training API.

Parameters

  handle | handle
  version | The output version of the model.

Returns
  0 when success, -1 when failure happens

## ◆ 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

Parameters

  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: Given data matrix X, obtain prediction y_pred from the model. Obtain the prediction for computing gradients. For example, DART booster performs dropout during training, and the prediction result will be different from the one obtained by normal inference step due to dropped trees. Set training=false for the first scenario. Set training=true for the second scenario. The second scenario applies when you are defining a custom objective function.
  out_len | used to store length of returning result
  out_result | used to set a pointer to array

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterSaveJsonConfig()

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.

Parameters

  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.

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterSaveModel()

XGB_DLL int XGBoosterSaveModel | ( | BoosterHandle | handle,
|  | const char * | fname
| ) |  |

Save model into existing file.

Parameters

  handle | handle
  fname | File URI or file name.

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterSaveRabitCheckpoint()

XGB_DLL int XGBoosterSaveRabitCheckpoint | ( | BoosterHandle | handle | ) |

Save the current checkpoint to rabit.

Parameters

  handle | handle

Returns
  0 when success, -1 when failure happens

## ◆ 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.

Parameters

  handle | handle
  out_len | the argument to hold the output length
  out_dptr | the argument to hold the output data pointer

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterSetAttr()

XGB_DLL int XGBoosterSetAttr | ( | BoosterHandle | handle,
|  | const char * | key,
|  | const char * | value
| ) |  |

Set or delete string attribute.

Parameters

  handle | handle
  key | The key of the attribute.
  value | The value to be saved. If nullptr, the attribute would be deleted.

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterSetParam()

XGB_DLL int XGBoosterSetParam | ( | BoosterHandle | handle,
|  | const char * | name,
|  | const char * | value
| ) |  |

set parameters

Parameters

  handle | handle
  name | parameter name
  value | value of parameter

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterSlice()

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).

Parameters

  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.

Returns
  0 when success, -1 when failure happens, -2 when index is out of bound.

## ◆ XGBoosterUnserializeFromBuffer()

XGB_DLL int XGBoosterUnserializeFromBuffer | ( | BoosterHandle | handle,
|  | const void * | buf,
|  | bst_ulong | len
| ) |  |

Memory snapshot based serialization method. Loads the buffer returned from ‘XGBoosterSerializeToBuffer’.

Parameters

  handle | handle
  buf | pointer to the buffer
  len | the length of the buffer

Returns
  0 when success, -1 when failure happens

## ◆ XGBoosterUpdateOneIter()

XGB_DLL int XGBoosterUpdateOneIter | ( | BoosterHandle | handle,
|  | int | iter,
|  | DMatrixHandle | dtrain
| ) |  |

update the model in one round using dtrain

Parameters

  handle | handle
  iter | current iteration rounds
  dtrain | training data

Returns
  0 when success, -1 when failure happens

## ◆ XGBoostVersion()

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.

Parameters

  major | Store the major version number
  minor | Store the minor version number
  patch | Store the patch (revision) number

## ◆ XGBRegisterLogCallback()

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

Returns
  0 for success, -1 for failure

## ◆ XGDeviceQuantileDMatrixCreateFromCallback()

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.

Parameters

  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

Returns
  0 when success, -1 when failure happens

## ◆ XGDeviceQuantileDMatrixSetDataCudaArrayInterface()

XGB_DLL int XGDeviceQuantileDMatrixSetDataCudaArrayInterface | ( | DMatrixHandle | handle,
|  | const char * | c_interface_str
| ) |  |

Set data on a DMatrix proxy.

Parameters

  handle | A DMatrix proxy created by XGProxyDMatrixCreate
  c_interface_str | Null terminated JSON document string representation of CUDA array interface.

Returns
  0 when success, -1 when failure happens

## ◆ XGDeviceQuantileDMatrixSetDataCudaColumnar()

XGB_DLL int XGDeviceQuantileDMatrixSetDataCudaColumnar | ( | DMatrixHandle | handle,
|  | const char * | c_interface_str
| ) |  |

Set data on a DMatrix proxy.

Parameters

  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.

Returns
  0 when success, -1 when failure happens

## ◆ XGDMatrixCallbackNext()

XGB_EXTERN_C typedef int XGDMatrixCallbackNext | ( | DataIterHandle | iter | ) |

Callback function prototype for getting next batch of data.

Parameters

  iter | A handler to the user defined iterator.

Returns
  0 when success, -1 when failure happens

## ◆ 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

Parameters

  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

Returns
  0 when success, -1 when failure happens

## ◆ 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

Parameters

  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 0, then guess from data
  out | created dmatrix

Returns
  0 when success, -1 when failure happens

## ◆ XGDMatrixCreateFromDataIter()

XGB_DLL int XGDMatrixCreateFromDataIter | ( | DataIterHandle | data_handle,
|  | XGBCallbackDataIterNext * | callback,
|  | const char * | cache_info,
|  | DMatrixHandle * | out
| ) |  |

Create a DMatrix from a data iterator.

Parameters

  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

Returns
  0 when success, -1 when failure happens.

## ◆ 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

Parameters

  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)

Returns
  0 when success, -1 when failure happens

## ◆ XGDMatrixCreateFromFile()

XGB_DLL int XGDMatrixCreateFromFile | ( | const char * | fname,
|  | int | silent,
|  | DMatrixHandle * | out
| ) |  |

load a data matrix

Parameters

  fname | the name of the file
  silent | whether print messages during loading
  out | a loaded data matrix

Returns
  0 when success, -1 when failure happens

## ◆ XGDMatrixCreateFromMat()

XGB_DLL int XGDMatrixCreateFromMat | ( | const float * | data,
|  | bst_ulong | nrow,
|  | bst_ulong | ncol,
|  | float | missing,
|  | DMatrixHandle * | out
| ) |  |

create matrix content from dense matrix

Parameters

  data | pointer to the data space
  nrow | number of rows
  ncol | number columns
  missing | which value to represent missing value
  out | created dmatrix

Returns
  0 when success, -1 when failure happens

## ◆ 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

Parameters

  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)

Returns
  0 when success, -1 when failure happens

## ◆ XGDMatrixFree()

XGB_DLL int XGDMatrixFree | ( | DMatrixHandle | handle | ) |

free space in data matrix

Returns
  0 when success, -1 when failure happens

## ◆ 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.

Parameters

  handle | a instance of data matrix
  field | field name
  out_len | used to set result length
  out_dptr | pointer to the result

Returns
  0 when success, -1 when failure happens

## ◆ XGDMatrixGetStrFeatureInfo()

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:

- feature_name
- feature_type

Caller is responsible for copying out the data, before next call to any API function of XGBoost.

Parameters

  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.

Returns
  0 when success, -1 when failure happens

char const **c_out_features = NULL;
bst_ulong out_size = 0;
// Asumming the feature names are already set by `XGDMatrixSetStrFeatureInfo`.
XGDMatrixGetStrFeatureInfo(handle, "feature_name", &out_size,
&c_out_features)
for (bst_ulong i = 0; i < out_size; ++i) {
// Here we are simply printing the string. Copy it out if the feature name is
// useful after printing.
printf("feature %lu: %s\n", i, c_out_features[i]);
}

## ◆ 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

Parameters

  handle | a instance of data matrix
  field | field name
  out_len | The length of the field.
  out_dptr | pointer to the result

Returns
  0 when success, -1 when failure happens

## ◆ XGDMatrixNumCol()

XGB_DLL int XGDMatrixNumCol | ( | DMatrixHandle | handle,
|  | bst_ulong * | out
| ) |  |

get number of columns

Parameters

  handle | the handle to the DMatrix
  out | The output of number of columns

Returns
  0 when success, -1 when failure happens

## ◆ XGDMatrixNumRow()

XGB_DLL int XGDMatrixNumRow | ( | DMatrixHandle | handle,
|  | bst_ulong * | out
| ) |  |

get number of rows.

Parameters

  handle | the handle to the DMatrix
  out | The address to hold number of rows.

Returns
  0 when success, -1 when failure happens

## ◆ XGDMatrixSaveBinary()

XGB_DLL int XGDMatrixSaveBinary | ( | DMatrixHandle | handle,
|  | const char * | fname,
|  | int | silent
| ) |  |

load a data matrix into binary file

Parameters

  handle | a instance of data matrix
  fname | file name
  silent | print statistics when saving

Returns
  0 when success, -1 when failure happens

## ◆ XGDMatrixSetDenseInfo()

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:

- label
- weight
- base_margin
- group
- label_lower_bound
- label_upper_bound
- feature_weights

Parameters

  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

Returns
  0 when success, -1 when failure happens

## ◆ XGDMatrixSetFloatInfo()

XGB_DLL int XGDMatrixSetFloatInfo | ( | DMatrixHandle | handle,
|  | const char * | field,
|  | const float * | array,
|  | bst_ulong | len
| ) |  |

set float vector to a content in info

Parameters

  handle | a instance of data matrix
  field | field name, can be label, weight
  array | pointer to float vector
  len | length of array

Returns
  0 when success, -1 when failure happens

## ◆ XGDMatrixSetGroup()

XGB_DLL int XGDMatrixSetGroup | ( | DMatrixHandle | handle,
|  | const unsigned * | group,
|  | bst_ulong | len
| ) |  |

(deprecated) Use XGDMatrixSetUIntInfo instead. Set group of the training matrix

Parameters

  handle | a instance of data matrix
  group | pointer to group size
  len | length of array

Returns
  0 when success, -1 when failure happens

## ◆ XGDMatrixSetInfoFromInterface()

XGB_DLL int XGDMatrixSetInfoFromInterface | ( | DMatrixHandle | handle,
|  | char const * | field,
|  | char const * | c_interface_str
| ) |  |

Set content in array interface to a content in info.

Parameters

  handle | a instance of data matrix
  field | field name.
  c_interface_str | JSON string representation of array interface.

Returns
  0 when success, -1 when failure happens

## ◆ XGDMatrixSetStrFeatureInfo()

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:

- feature_name
- feature_type

Parameters

  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).

Returns
  0 when success, -1 when failure happens

char const* feat_names [] {"feat_0", "feat_1"};
XGDMatrixSetStrFeatureInfo(handle, "feature_name", feat_names, 2);
// i for integer, q for quantitive. Similarly "int" and "float" are also recognized.
char const* feat_types [] {"i", "q"};
XGDMatrixSetStrFeatureInfo(handle, "feature_type", feat_types, 2);

## ◆ XGDMatrixSetUIntInfo()

XGB_DLL int XGDMatrixSetUIntInfo | ( | DMatrixHandle | handle,
|  | const char * | field,
|  | const unsigned * | array,
|  | bst_ulong | len
| ) |  |

set uint32 vector to a content in info

Parameters

  handle | a instance of data matrix
  field | field name
  array | pointer to unsigned int vector
  len | length of array

Returns
  0 when success, -1 when failure happens

## ◆ 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

Parameters

  handle | instance of data matrix to be sliced
  idxset | index set
  len | length of index set
  out | a sliced new matrix

Returns
  0 when success, -1 when failure happens

## ◆ 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

Parameters

  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

Returns
  0 when success, -1 when failure happens

## ◆ XGProxyDMatrixCreate()

XGB_DLL int XGProxyDMatrixCreate | ( | DMatrixHandle * | out | ) |

Create a DMatrix proxy for setting data, can be free by XGDMatrixFree.

Parameters

  out | The created Device Quantile DMatrix

Returns
  0 when success, -1 when failure happens

XGDMatrixSetStrFeatureInfo
XGB_DLL int XGDMatrixSetStrFeatureInfo(DMatrixHandle handle, const char *field, const char **features, const bst_ulong size)
Set string encoded information of all features.
bst_ulong
uint64_t bst_ulong
Definition: c_api.h:27
XGDMatrixGetStrFeatureInfo
XGB_DLL int XGDMatrixGetStrFeatureInfo(DMatrixHandle handle, const char *field, bst_ulong *size, const char ***out_features)
Get string encoded information of all features.