Treelite
c_api.h
Go to the documentation of this file.
1 
9 /* Note: Make sure to use slash-asterisk form of comments in this file
10  (like this one). Do not use double-slash (//). */
11 
12 #ifndef TREELITE_C_API_H_
13 #define TREELITE_C_API_H_
14 
15 #include "c_api_common.h"
16 
23 typedef void* ModelHandle;
25 typedef void* TreeBuilderHandle;
27 typedef void* ModelBuilderHandle;
29 typedef void* AnnotationHandle;
31 typedef void* CompilerHandle;
33 typedef void* ValueHandle;
51 TREELITE_DLL int TreeliteAnnotateBranch(
52  ModelHandle model, DMatrixHandle dmat, int nthread, int verbose, AnnotationHandle* out);
59 TREELITE_DLL int TreeliteAnnotationSave(AnnotationHandle handle,
60  const char* path);
66 TREELITE_DLL int TreeliteAnnotationFree(AnnotationHandle handle);
81 TREELITE_DLL int TreeliteCompilerCreateV2(const char* name, const char* params_json_str,
82  CompilerHandle* out);
101 TREELITE_DLL int TreeliteCompilerGenerateCodeV2(CompilerHandle compiler,
102  ModelHandle model,
103  const char* dirpath);
109 TREELITE_DLL int TreeliteCompilerFree(CompilerHandle handle);
124 TREELITE_DLL int TreeliteLoadLightGBMModel(const char* filename, ModelHandle* out);
132 TREELITE_DLL int TreeliteLoadXGBoostModel(const char* filename, ModelHandle* out);
140 TREELITE_DLL int TreeliteLoadXGBoostJSON(const char* filename,
141  ModelHandle* out);
150 TREELITE_DLL int TreeliteLoadXGBoostJSONString(const char* json_str,
151  size_t length,
152  ModelHandle* out);
160 TREELITE_DLL int TreeliteLoadXGBoostModelFromMemoryBuffer(const void* buf,
161  size_t len,
162  ModelHandle* out);
163 
171 TREELITE_DLL int TreeliteLoadLightGBMModelFromString(const char* model_str,
172  ModelHandle* out);
173 
202  int n_estimators, int n_features, const int64_t* node_count, const int64_t** children_left,
203  const int64_t** children_right, const int64_t** feature, const double** threshold,
204  const double** value, const int64_t** n_node_samples, const double** weighted_n_node_samples,
205  const double** impurity, ModelHandle* out);
206 
233 TREELITE_DLL int TreeliteLoadSKLearnIsolationForest(
234  int n_estimators, int n_features, const int64_t* node_count, const int64_t** children_left,
235  const int64_t** children_right, const int64_t** feature, const double** threshold,
236  const double** value, const int64_t** n_node_samples, const double** weighted_n_node_samples,
237  const double** impurity, const double ratio_c, ModelHandle* out);
238 
268  int n_estimators, int n_features, int n_classes, const int64_t* node_count,
269  const int64_t** children_left, const int64_t** children_right, const int64_t** feature,
270  const double** threshold, const double** value, const int64_t** n_node_samples,
271  const double** weighted_n_node_samples, const double** impurity, ModelHandle* out);
272 
300  int n_estimators, int n_features, const int64_t* node_count, const int64_t** children_left,
301  const int64_t** children_right, const int64_t** feature, const double** threshold,
302  const double** value, const int64_t** n_node_samples, const double** weighted_n_node_samples,
303  const double** impurity, ModelHandle* out);
304 
333  int n_estimators, int n_features, int n_classes, const int64_t* node_count,
334  const int64_t** children_left, const int64_t** children_right, const int64_t** feature,
335  const double** threshold, const double** value, const int64_t** n_node_samples,
336  const double** weighted_n_node_samples, const double** impurity, ModelHandle* out);
337 
344 TREELITE_DLL int TreeliteQueryNumTree(ModelHandle handle, size_t* out);
351 TREELITE_DLL int TreeliteQueryNumFeature(ModelHandle handle, size_t* out);
359 TREELITE_DLL int TreeliteQueryNumClass(ModelHandle handle, size_t* out);
360 
367 TREELITE_DLL int TreeliteSetTreeLimit(ModelHandle handle, size_t limit);
368 
376 TREELITE_DLL int TreeliteSerializeModel(const char* filename, ModelHandle handle);
377 
385 TREELITE_DLL int TreeliteDeserializeModel(const char* filename, ModelHandle* out);
386 
394 TREELITE_DLL int TreeliteDumpAsJSON(ModelHandle handle, int pretty_print,
395  const char** out_json_str);
396 
402 TREELITE_DLL int TreeliteFreeModel(ModelHandle handle);
421 TREELITE_DLL int TreeliteGTILGetPredictOutputSize(ModelHandle model, size_t num_row, size_t* out);
422 
437 TREELITE_DLL int TreeliteGTILPredict(ModelHandle model, const float* input, size_t num_row,
438  float* output, int nthread, int pred_transform,
439  size_t* out_result_size);
440 
456 TREELITE_DLL int TreeliteTreeBuilderCreateValue(const void* init_value, const char* type,
457  ValueHandle* out);
463 TREELITE_DLL int TreeliteTreeBuilderDeleteValue(ValueHandle handle);
473 TREELITE_DLL int TreeliteCreateTreeBuilder(const char* threshold_type, const char* leaf_output_type,
474  TreeBuilderHandle* out);
480 TREELITE_DLL int TreeliteDeleteTreeBuilder(TreeBuilderHandle handle);
487 TREELITE_DLL int TreeliteTreeBuilderCreateNode(TreeBuilderHandle handle, int node_key);
494 TREELITE_DLL int TreeliteTreeBuilderDeleteNode(TreeBuilderHandle handle, int node_key);
501 TREELITE_DLL int TreeliteTreeBuilderSetRootNode(TreeBuilderHandle handle, int node_key);
518  TreeBuilderHandle handle, int node_key, unsigned feature_id, const char* opname,
519  ValueHandle threshold, int default_left, int left_child_key, int right_child_key);
537  TreeBuilderHandle handle, int node_key, unsigned feature_id,
538  const unsigned int* left_categories, size_t left_categories_len, int default_left,
539  int left_child_key, int right_child_key);
548 TREELITE_DLL int TreeliteTreeBuilderSetLeafNode(
549  TreeBuilderHandle handle, int node_key, ValueHandle leaf_value);
561 TREELITE_DLL int TreeliteTreeBuilderSetLeafVectorNode(
562  TreeBuilderHandle handle, int node_key, const ValueHandle* leaf_vector, size_t leaf_vector_len);
578 TREELITE_DLL int TreeliteCreateModelBuilder(
579  int num_feature, int num_class, int average_tree_output, const char* threshold_type,
580  const char* leaf_output_type, ModelBuilderHandle* out);
589  const char* name,
590  const char* value);
596 TREELITE_DLL int TreeliteDeleteModelBuilder(ModelBuilderHandle handle);
610 TREELITE_DLL int TreeliteModelBuilderInsertTree(ModelBuilderHandle handle,
611  TreeBuilderHandle tree_builder,
612  int index);
620 TREELITE_DLL int TreeliteModelBuilderGetTree(ModelBuilderHandle handle,
621  int index,
622  TreeBuilderHandle *out);
629 TREELITE_DLL int TreeliteModelBuilderDeleteTree(ModelBuilderHandle handle,
630  int index);
639  ModelHandle* out);
642 #endif /* TREELITE_C_API_H_ */
int TreeliteQueryNumClass(ModelHandle handle, size_t *out)
Query the number of classes of the model. (1 if the model is binary classifier or regressor) ...
Definition: c_api.cc:288
int TreeliteModelBuilderSetModelParam(ModelBuilderHandle handle, const char *name, const char *value)
Set a model parameter.
Definition: c_api.cc:423
int TreeliteModelBuilderGetTree(ModelBuilderHandle handle, int index, TreeBuilderHandle *out)
Get a reference to a tree in the ensemble.
Definition: c_api.cc:449
int TreeliteLoadXGBoostModel(const char *filename, ModelHandle *out)
load a model file generated by XGBoost (dmlc/xgboost). The model file must contain a decision tree en...
Definition: c_api.cc:123
int TreeliteDumpAsJSON(ModelHandle handle, int pretty_print, const char **out_json_str)
Dump a model object as a JSON string.
Definition: c_api.cc:243
int TreeliteFreeModel(ModelHandle handle)
delete model from memory
Definition: c_api.cc:252
int TreeliteAnnotationSave(AnnotationHandle handle, const char *path)
save branch annotation to a JSON file
Definition: c_api.cc:53
int TreeliteQueryNumTree(ModelHandle handle, size_t *out)
Query the number of trees in the model.
Definition: c_api.cc:274
int TreeliteModelBuilderDeleteTree(ModelBuilderHandle handle, int index)
Remove a tree from the ensemble.
Definition: c_api.cc:459
int TreeliteDeserializeModel(const char *filename, ModelHandle *out)
Deserialize (load) a model object from disk.
Definition: c_api.cc:233
int TreeliteLoadXGBoostJSON(const char *filename, ModelHandle *out)
load a json model file generated by XGBoost (dmlc/xgboost). The model file must contain a decision tr...
Definition: c_api.cc:130
int TreeliteDeleteModelBuilder(ModelBuilderHandle handle)
Delete a model builder from memory.
Definition: c_api.cc:432
int TreeliteTreeBuilderSetCategoricalTestNode(TreeBuilderHandle handle, int node_key, unsigned feature_id, const unsigned int *left_categories, size_t left_categories_len, int default_left, int left_child_key, int right_child_key)
Turn an empty node into a test node with categorical split. A list defines all categories that would ...
Definition: c_api.cc:372
int TreeliteAnnotationFree(AnnotationHandle handle)
delete branch annotation from memory
Definition: c_api.cc:62
int TreeliteLoadSKLearnIsolationForest(int n_estimators, int n_features, const int64_t *node_count, const int64_t **children_left, const int64_t **children_right, const int64_t **feature, const double **threshold, const double **value, const int64_t **n_node_samples, const double **weighted_n_node_samples, const double **impurity, const double ratio_c, ModelHandle *out)
Load a scikit-learn isolation forest model from a collection of arrays. Refer to https://scikit-learn...
Definition: c_api.cc:171
int TreeliteTreeBuilderSetNumericalTestNode(TreeBuilderHandle handle, int node_key, unsigned feature_id, const char *opname, ValueHandle threshold, int default_left, int left_child_key, int right_child_key)
Turn an empty node into a test node with numerical split. The test is in the form [feature value] OP ...
Definition: c_api.cc:360
int TreeliteLoadSKLearnRandomForestClassifier(int n_estimators, int n_features, int n_classes, const int64_t *node_count, const int64_t **children_left, const int64_t **children_right, const int64_t **feature, const double **threshold, const double **value, const int64_t **n_node_samples, const double **weighted_n_node_samples, const double **impurity, ModelHandle *out)
Load a scikit-learn random forest classifier model from a collection of arrays. Refer to https://scik...
Definition: c_api.cc:184
int TreeliteAnnotateBranch(ModelHandle model, DMatrixHandle dmat, int nthread, int verbose, AnnotationHandle *out)
annotate branches in a given model using frequency patterns in the training data. ...
Definition: c_api.cc:41
int TreeliteTreeBuilderCreateValue(const void *init_value, const char *type, ValueHandle *out)
Create a new Value object. Some model builder API functions accept this Value type to accommodate val...
Definition: c_api.cc:305
int TreeliteSetTreeLimit(ModelHandle handle, size_t limit)
keep first N trees of model, limit must smaller than number of trees.
Definition: c_api.cc:295
void * ValueHandle
handle to a polymorphic value type, used in the model builder API
Definition: c_api.h:33
int TreeliteModelBuilderInsertTree(ModelBuilderHandle handle, TreeBuilderHandle tree_builder, int index)
Insert a tree at specified location.
Definition: c_api.cc:438
void * DMatrixHandle
handle to a data matrix
Definition: c_api_common.h:30
int TreeliteLoadLightGBMModelFromString(const char *model_str, ModelHandle *out)
Load a LightGBM model from a string. The string should be created with the model_to_string() method i...
Definition: c_api.cc:151
int TreeliteTreeBuilderSetRootNode(TreeBuilderHandle handle, int node_key)
Set a node as the root of a tree.
Definition: c_api.cc:352
int TreeliteLoadSKLearnGradientBoostingClassifier(int n_estimators, int n_features, int n_classes, const int64_t *node_count, const int64_t **children_left, const int64_t **children_right, const int64_t **feature, const double **threshold, const double **value, const int64_t **n_node_samples, const double **weighted_n_node_samples, const double **impurity, ModelHandle *out)
Load a scikit-learn gradient boosting classifier model from a collection of arrays. Refer to https://scikit-learn.org/stable/auto_examples/tree/plot_unveil_tree_structure.html to learn the mearning of the arrays in detail.
Definition: c_api.cc:210
int TreeliteCompilerCreateV2(const char *name, const char *params_json_str, CompilerHandle *out)
Create a compiler with a given name.
Definition: c_api.cc:68
void * TreeBuilderHandle
handle to tree builder class
Definition: c_api.h:25
int TreeliteDeleteTreeBuilder(TreeBuilderHandle handle)
Delete a tree builder from memory.
Definition: c_api.cc:330
int TreeliteCreateTreeBuilder(const char *threshold_type, const char *leaf_output_type, TreeBuilderHandle *out)
Create a new tree builder.
Definition: c_api.cc:319
void * AnnotationHandle
handle to branch annotation data
Definition: c_api.h:29
int TreeliteModelBuilderCommitModel(ModelBuilderHandle handle, ModelHandle *out)
finalize the model and produce the in-memory representation
Definition: c_api.cc:467
int TreeliteTreeBuilderSetLeafNode(TreeBuilderHandle handle, int node_key, ValueHandle leaf_value)
Turn an empty node into a leaf node.
Definition: c_api.cc:389
int TreeliteCompilerGenerateCodeV2(CompilerHandle compiler, ModelHandle model, const char *dirpath)
Generate prediction code from a tree ensemble model. The code will be C99 compliant. One header file (.h) will be generated, along with one or more source files (.c).
Definition: c_api.cc:75
int TreeliteCreateModelBuilder(int num_feature, int num_class, int average_tree_output, const char *threshold_type, const char *leaf_output_type, ModelBuilderHandle *out)
Create a new model builder.
Definition: c_api.cc:412
int TreeliteLoadXGBoostModelFromMemoryBuffer(const void *buf, size_t len, ModelHandle *out)
load an XGBoost model from a memory buffer.
Definition: c_api.cc:144
int TreeliteLoadSKLearnGradientBoostingRegressor(int n_estimators, int n_features, const int64_t *node_count, const int64_t **children_left, const int64_t **children_right, const int64_t **feature, const double **threshold, const double **value, const int64_t **n_node_samples, const double **weighted_n_node_samples, const double **impurity, ModelHandle *out)
Load a scikit-learn gradient boosting regressor model from a collection of arrays. Refer to https://scikit-learn.org/stable/auto_examples/tree/plot_unveil_tree_structure.html to learn the mearning of the arrays in detail.
Definition: c_api.cc:197
void * ModelHandle
handle to a decision tree ensemble model
Definition: c_api.h:23
int TreeliteLoadLightGBMModel(const char *filename, ModelHandle *out)
load a model file generated by LightGBM (Microsoft/LightGBM). The model file must contain a decision ...
Definition: c_api.cc:116
C API of Treelite, used for interfacing with other languages This header is used by both the runtime ...
int TreeliteTreeBuilderDeleteValue(ValueHandle handle)
Delete a Value object from memory.
Definition: c_api.cc:313
int TreeliteTreeBuilderDeleteNode(TreeBuilderHandle handle, int node_key)
Remove a node from a tree.
Definition: c_api.cc:344
int TreeliteLoadSKLearnRandomForestRegressor(int n_estimators, int n_features, const int64_t *node_count, const int64_t **children_left, const int64_t **children_right, const int64_t **feature, const double **threshold, const double **value, const int64_t **n_node_samples, const double **weighted_n_node_samples, const double **impurity, ModelHandle *out)
Load a scikit-learn random forest regressor model from a collection of arrays. Refer to https://sciki...
Definition: c_api.cc:158
int TreeliteQueryNumFeature(ModelHandle handle, size_t *out)
Query the number of features used in the model.
Definition: c_api.cc:281
int TreeliteGTILPredict(ModelHandle model, const float *input, size_t num_row, float *output, int nthread, int pred_transform, size_t *out_result_size)
Predict with a 2D dense array.
Definition: c_api.cc:265
void * ModelBuilderHandle
handle to ensemble builder class
Definition: c_api.h:27
int TreeliteSerializeModel(const char *filename, ModelHandle handle)
Serialize (persist) a model object to disk.
Definition: c_api.cc:223
int TreeliteTreeBuilderSetLeafVectorNode(TreeBuilderHandle handle, int node_key, const ValueHandle *leaf_vector, size_t leaf_vector_len)
Turn an empty node into a leaf vector node The leaf vector (collection of multiple leaf weights per l...
Definition: c_api.cc:397
void * CompilerHandle
handle to compiler class
Definition: c_api.h:31
int TreeliteLoadXGBoostJSONString(const char *json_str, size_t length, ModelHandle *out)
load a model stored as JSON stringby XGBoost (dmlc/xgboost). The model json must contain a decision t...
Definition: c_api.cc:137
int TreeliteGTILGetPredictOutputSize(ModelHandle model, size_t num_row, size_t *out)
Given a batch of data rows, query the necessary size of array to hold predictions for all data points...
Definition: c_api.cc:258
int TreeliteCompilerFree(CompilerHandle handle)
delete compiler from memory
Definition: c_api.cc:110
int TreeliteTreeBuilderCreateNode(TreeBuilderHandle handle, int node_key)
Create an empty node within a tree.
Definition: c_api.cc:336