Treelite exposes a set of C functions to enable interfacing with a variety of languages. This page will be most useful for:
those writing a new language binding (glue code).
those wanting to incorporate functions of Treelite into their own native libraries.
We recommend the Python API for everyday uses.
Note
Use of C and C++ in Treelite
Core logic of Treelite are written in C++ to take advantage of higher abstractions. We provide C only interface here, as many more programming languages bind with C than with C++. See this page for more details.
Contents
Use the following functions to load and manipulate data from a variety of sources.
TreeliteDMatrixCreateFromCSR
(const void *data, const char *data_type, const uint32_t *col_ind, const size_t *row_ptr, size_t num_row, size_t num_col, DMatrixHandle *out)¶create DMatrix from a (in-memory) CSR matrix
0 for success, -1 for failure
data
: feature values
data_type
: Type of data elements
col_ind
: feature indices
row_ptr
: pointer to row headers
num_row
: number of rows
num_col
: number of columns
out
: the created DMatrix
TreeliteDMatrixCreateFromMat
(const void *data, const char *data_type, size_t num_row, size_t num_col, const void *missing_value, DMatrixHandle *out)¶create DMatrix from a (in-memory) dense matrix
0 for success, -1 for failure
data
: feature values
data_type
: Type of data elements
num_row
: number of rows
num_col
: number of columns
missing_value
: value to represent missing value
out
: the created DMatrix
TreeliteDMatrixGetDimension
(DMatrixHandle handle, size_t *out_num_row, size_t *out_num_col, size_t *out_nelem)¶get dimensions of a DMatrix
0 for success, -1 for failure
handle
: handle to DMatrix
out_num_row
: used to set number of rows
out_num_col
: used to set number of columns
out_nelem
: used to set number of nonzero entries
TreeliteDMatrixFree
(DMatrixHandle handle)¶delete DMatrix from memory
0 for success, -1 for failure
handle
: handle to DMatrix
Use the following functions to annotate branches in decision trees.
TreeliteAnnotateBranch
(ModelHandle model, DMatrixHandle dmat, int nthread, int verbose, AnnotationHandle *out)¶annotate branches in a given model using frequency patterns in the training data.
0 for success, -1 for failure
model
: model to annotate
dmat
: training data matrix
nthread
: number of threads to use
verbose
: whether to produce extra messages
out
: used to save handle for the created annotation
TreeliteAnnotationSave
(AnnotationHandle handle, const char *path)¶save branch annotation to a JSON file
0 for success, -1 for failure
handle
: annotation to save
path
: path to JSON file
TreeliteAnnotationFree
(AnnotationHandle handle)¶delete branch annotation from memory
0 for success, -1 for failure
handle
: annotation to remove
Use the following functions to produce optimize prediction subroutine (in C) from a given decision tree ensemble.
TreeliteCompilerCreateV2
(const char *name, const char *params_json_str, CompilerHandle *out)¶Create a compiler with a given name.
0 for success, -1 for failure
name
: name of compiler
params_json_str
: JSON string representing the parameters for the compiler
out
: created compiler
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).
Usage example:
TreeliteCompilerGenerateCodeV2(compiler, model, "./my/model");
// files to generate: ./my/model/header.h, ./my/model/main.c
// if parallel compilation is enabled:
// ./my/model/header.h, ./my/model/main.c, ./my/model/tu0.c,
// ./my/model/tu1.c, and so forth
0 for success, -1 for failure
compiler
: handle for compiler
model
: handle for tree ensemble model
dirpath
: directory to store header and source files
TreeliteCompilerFree
(CompilerHandle handle)¶delete compiler from memory
0 for success, -1 for failure
handle
: compiler to remove
Use the following functions to load decision tree ensemble models from a file. Treelite supports multiple model file formats.
TreeliteLoadLightGBMModel
(const char *filename, ModelHandle *out)¶load a model file generated by LightGBM (Microsoft/LightGBM). The model file must contain a decision tree ensemble.
0 for success, -1 for failure
filename
: name of model file
out
: loaded model
TreeliteLoadXGBoostModel
(const char *filename, ModelHandle *out)¶load a model file generated by XGBoost (dmlc/xgboost). The model file must contain a decision tree ensemble.
0 for success, -1 for failure
filename
: name of model file
out
: loaded model
TreeliteLoadXGBoostJSON
(const char *filename, ModelHandle *out)¶load a json model file generated by XGBoost (dmlc/xgboost). The model file must contain a decision tree ensemble.
0 for success, -1 for failure
filename
: name of model file
out
: loaded model
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 tree ensemble.
0 for success, -1 for failure
json_str
: the string containing the JSON model specification
length
: the length of the JSON string
out
: loaded model
TreeliteLoadXGBoostModelFromMemoryBuffer
(const void *buf, size_t len, ModelHandle *out)¶load an XGBoost model from a memory buffer.
0 for success, -1 for failure
buf
: memory buffer
len
: size of memory buffer
out
: loaded model
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 in LightGBM.
0 for success, -1 for failure
model_str
: the model string
out
: loaded model
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://scikit-learn.org/stable/auto_examples/tree/plot_unveil_tree_structure.html to learn the mearning of the arrays in detail. Note that this function can also be used to load an ensemble of extremely randomized trees (sklearn.ensemble.ExtraTreesRegressor).
0 for success, -1 for failure
n_estimators
: number of trees in the random forest
n_features
: number of features in the training data
node_count
: node_count[i] stores the number of nodes in the i-th tree
children_left
: children_left[i][k] stores the ID of the left child node of node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
children_right
: children_right[i][k] stores the ID of the right child node of node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
feature
: feature[i][k] stores the ID of the feature used in the binary tree split at node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
threshold
: threshold[i][k] stores the threshold used in the binary tree split at node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
value
: value[i][k] stores the leaf output of node k of the i-th tree. This is only defined if node k is a leaf node.
n_node_samples
: n_node_samples[i][k] stores the number of data samples associated with node k of the i-th tree.
weighted_n_node_samples
: weighted_n_node_samples[i][k] stores the sum of weighted data samples associated with node k of the i-th tree.
impurity
: impurity[i][k] stores the impurity measure (gini, entropy etc) associated with node k of the i-th tree.
out
: pointer to store the loaded model
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.org/stable/auto_examples/tree/plot_unveil_tree_structure.html to learn the mearning of the arrays in detail.
0 for success, -1 for failure
n_estimators
: number of trees in the random forest
n_features
: number of features in the training data
node_count
: node_count[i] stores the number of nodes in the i-th tree
children_left
: children_left[i][k] stores the ID of the left child node of node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
children_right
: children_right[i][k] stores the ID of the right child node of node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
feature
: feature[i][k] stores the ID of the feature used in the binary tree split at node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
threshold
: threshold[i][k] stores the threshold used in the binary tree split at node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
value
: value[i][k] stores the expected isolation depth of node k of the i-th tree. This is only defined if node k is a leaf node.
n_node_samples
: n_node_samples[i][k] stores the number of data samples associated with node k of the i-th tree.
weighted_n_node_samples
: weighted_n_node_samples[i][k] stores the sum of weighted data samples associated with node k of the i-th tree.
impurity
: not used, but must be passed as array of arrays for each tree and node.
ratio_c
: standardizing constant to use for calculation of the anomaly score.
out
: pointer to store the loaded model
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://scikit-learn.org/stable/auto_examples/tree/plot_unveil_tree_structure.html to learn the mearning of the arrays in detail. Note that this function can also be used to load an ensemble of extremely randomized trees (sklearn.ensemble.ExtraTreesClassifier).
0 for success, -1 for failure
n_estimators
: number of trees in the random forest
n_features
: number of features in the training data
n_classes
: number of classes in the target variable
node_count
: node_count[i] stores the number of nodes in the i-th tree
children_left
: children_left[i][k] stores the ID of the left child node of node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
children_right
: children_right[i][k] stores the ID of the right child node of node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
feature
: feature[i][k] stores the ID of the feature used in the binary tree split at node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
threshold
: threshold[i][k] stores the threshold used in the binary tree split at node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
value
: value[i][k] stores the leaf output of node k of the i-th tree. This is only defined if node k is a leaf node.
n_node_samples
: n_node_samples[i][k] stores the number of data samples associated with node k of the i-th tree.
weighted_n_node_samples
: weighted_n_node_samples[i][k] stores the sum of weighted data samples associated with node k of the i-th tree.
impurity
: impurity[i][k] stores the impurity measure (gini, entropy etc) associated with node k of the i-th tree.
out
: pointer to store the loaded model
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.
0 for success, -1 for failure
n_estimators
: number of trees in the random forest
n_features
: number of features in the training data
node_count
: node_count[i] stores the number of nodes in the i-th tree
children_left
: children_left[i][k] stores the ID of the left child node of node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
children_right
: children_right[i][k] stores the ID of the right child node of node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
feature
: feature[i][k] stores the ID of the feature used in the binary tree split at node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
threshold
: threshold[i][k] stores the threshold used in the binary tree split at node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
value
: value[i][k] stores the leaf output of node k of the i-th tree. This is only defined if node k is a leaf node.
n_node_samples
: n_node_samples[i][k] stores the number of data samples associated with node k of the i-th tree.
weighted_n_node_samples
: weighted_n_node_samples[i][k] stores the sum of weighted data samples associated with node k of the i-th tree.
impurity
: impurity[i][k] stores the impurity measure (gini, entropy etc) associated with node k of the i-th tree.
out
: pointer to store the loaded model
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.
0 for success, -1 for failure
n_estimators
: number of trees in the random forest
n_features
: number of features in the training data
n_classes
: number of classes in the target variable
node_count
: node_count[i] stores the number of nodes in the i-th tree
children_left
: children_left[i][k] stores the ID of the left child node of node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
children_right
: children_right[i][k] stores the ID of the right child node of node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
feature
: feature[i][k] stores the ID of the feature used in the binary tree split at node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
threshold
: threshold[i][k] stores the threshold used in the binary tree split at node k of the i-th tree. This is only defined if node k is an internal (non-leaf) node.
value
: value[i][k] stores the leaf output of node k of the i-th tree. This is only defined if node k is a leaf node.
n_node_samples
: n_node_samples[i][k] stores the number of data samples associated with node k of the i-th tree.
weighted_n_node_samples
: weighted_n_node_samples[i][k] stores the sum of weighted data samples associated with node k of the i-th tree.
impurity
: impurity[i][k] stores the impurity measure (gini, entropy etc) associated with node k of the i-th tree.
out
: pointer to store the loaded model
TreeliteQueryNumTree
(ModelHandle handle, size_t *out)¶Query the number of trees in the model.
0 for success, -1 for failure
handle
: model to query
out
: number of trees
TreeliteQueryNumFeature
(ModelHandle handle, size_t *out)¶Query the number of features used in the model.
0 for success, -1 for failure
handle
: model to query
out
: number of features
TreeliteQueryNumClass
(ModelHandle handle, size_t *out)¶Query the number of classes of the model. (1 if the model is binary classifier or regressor)
0 for success, -1 for failure
handle
: model to query
out
: number of output groups
TreeliteSetTreeLimit
(ModelHandle handle, size_t limit)¶keep first N trees of model, limit must smaller than number of trees.
0 for success, -1 for failure
handle
: model
limit
: number of trees to keep
TreeliteSerializeModel
(const char *filename, ModelHandle handle)¶Serialize (persist) a model object to disk.
0 for success, -1 for failure
filename
: name of the file to which to serialize the model. The file will be using a binary format that’s optimized to store the Treelite model object efficiently.
handle
: handle to the model object
TreeliteDeserializeModel
(const char *filename, ModelHandle *out)¶Deserialize (load) a model object from disk.
0 for success, -1 for failure
filename
: name of the file from which to deserialize the model. The file should be created by a call to TreeliteSerializeModel().
handle
: handle to the model object
TreeliteDumpAsJSON
(ModelHandle handle, int pretty_print, const char **out_json_str)¶Dump a model object as a JSON string.
0 for success, -1 for failure
handle
: The handle to the model object
pretty_print
: Whether to pretty-print JSON string (0 for false, != 0 for true)
out_json_str
: The JSON string
TreeliteFreeModel
(ModelHandle handle)¶delete model from memory
0 for success, -1 for failure
handle
: model to remove
Use the following functions to incrementally build decisio n tree ensemble models.
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 values of multiple types.
0 for success; -1 for failure
init_value
: pointer to the value to be stored
type
: Type of the value to be stored
out
: newly created Value object
TreeliteTreeBuilderDeleteValue
(ValueHandle handle)¶Delete a Value object from memory.
0 for success; -1 for failure
handle
: pointer to the Value object to be deleted
TreeliteCreateTreeBuilder
(const char *threshold_type, const char *leaf_output_type, TreeBuilderHandle *out)¶Create a new tree builder.
0 for success; -1 for failure
threshold_type
: Type of thresholds in numerical splits. All thresholds in a given model must have the same type.
leaf_output_type
: Type of leaf outputs. All leaf outputs in a given model must have the same type.
out
: newly created tree builder
TreeliteDeleteTreeBuilder
(TreeBuilderHandle handle)¶Delete a tree builder from memory.
0 for success; -1 for failure
handle
: tree builder to remove
TreeliteTreeBuilderCreateNode
(TreeBuilderHandle handle, int node_key)¶Create an empty node within a tree.
0 for success; -1 for failure
handle
: tree builder
node_key
: unique integer key to identify the new node
TreeliteTreeBuilderDeleteNode
(TreeBuilderHandle handle, int node_key)¶Remove a node from a tree.
0 for success; -1 for failure
handle
: tree builder
node_key
: unique integer key to identify the node to be removed
TreeliteTreeBuilderSetRootNode
(TreeBuilderHandle handle, int node_key)¶Set a node as the root of a tree.
0 for success; -1 for failure
handle
: tree builder
node_key
: unique integer key to identify the root node
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 [threshold]. Depending on the result of the test, either left or right child would be taken.
0 for success; -1 for failure
handle
: tree builder
node_key
: unique integer key to identify the node being modified; this node needs to be empty
feature_id
: id of feature
opname
: binary operator to use in the test
threshold
: threshold value
default_left
: default direction for missing values
left_child_key
: unique integer key to identify the left child node
right_child_key
: unique integer key to identify the right child node
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 be classified as the left side. Categories are integers ranging from 0 to (n-1), where n is the number of categories in that particular feature. Let’s assume n <= 64.
0 for success; -1 for failure
handle
: tree builder
node_key
: unique integer key to identify the node being modified; this node needs to be empty
feature_id
: id of feature
left_categories
: list of categories belonging to the left child
left_categories_len
: length of left_cateogries
default_left
: default direction for missing values
left_child_key
: unique integer key to identify the left child node
right_child_key
: unique integer key to identify the right child node
TreeliteTreeBuilderSetLeafNode
(TreeBuilderHandle handle, int node_key, ValueHandle leaf_value)¶Turn an empty node into a leaf node.
0 for success; -1 for failure
handle
: tree builder
node_key
: unique integer key to identify the node being modified; this node needs to be empty
leaf_value
: leaf value (weight) of the leaf node
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 leaf node) is useful for multi-class random forest classifier.
0 for success; -1 for failure
handle
: tree builder
node_key
: unique integer key to identify the node being modified; this node needs to be empty
leaf_vector
: leaf vector of the leaf node
leaf_vector_len
: length of leaf_vector
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.
0 for success; -1 for failure
num_feature
: number of features used in model being built. We assume that all feature indices are between 0 and (num_feature - 1).
num_class
: number of output groups. Set to 1 for binary classification and regression; >1 for multiclass classification
average_tree_output
: whether the outputs from the trees should be averaged (!=0 yes, =0 no)
threshold_type
: Type of thresholds in numerical splits. All thresholds in a given model must have the same type.
leaf_output_type
: Type of leaf outputs. All leaf outputs in a given model must have the same type.
out
: newly created model builder
TreeliteModelBuilderSetModelParam
(ModelBuilderHandle handle, const char *name, const char *value)¶Set a model parameter.
0 for success; -1 for failure
handle
: model builder
name
: name of parameter
value
: value of parameter
TreeliteDeleteModelBuilder
(ModelBuilderHandle handle)¶Delete a model builder from memory.
0 for success; -1 for failure
handle
: model builder to remove
TreeliteModelBuilderInsertTree
(ModelBuilderHandle handle, TreeBuilderHandle tree_builder, int index)¶Insert a tree at specified location.
index of the new tree within the ensemble; -1 for failure
handle
: model builder
tree_builder
: builder for the tree to be inserted. The tree must not be part of any other existing tree ensemble. Note: The tree_builder argument will become unusuable after the tree insertion. Should you want to modify the tree afterwards, use GetTree(*) method to get a fresh handle to the tree.
index
: index of the element before which to insert the tree; use -1 to insert at the end
TreeliteModelBuilderGetTree
(ModelBuilderHandle handle, int index, TreeBuilderHandle *out)¶Get a reference to a tree in the ensemble.
0 for success; -1 for failure
handle
: model builder
index
: index of the tree in the ensemble
out
: used to save reference to the tree
TreeliteModelBuilderDeleteTree
(ModelBuilderHandle handle, int index)¶Remove a tree from the ensemble.
0 for success; -1 for failure
handle
: model builder
index
: index of the tree that would be removed
TreeliteModelBuilderCommitModel
(ModelBuilderHandle handle, ModelHandle *out)¶finalize the model and produce the in-memory representation
0 for success; -1 for failure
handle
: model builder
out
: used to save handle to in-memory representation of the finished model
Use the following functions to load compiled prediction subroutines from shared libraries and to make predictions.
TreelitePredictorLoad
(const char *library_path, int num_worker_thread, PredictorHandle *out)¶load prediction code into memory. This function assumes that the prediction code has been already compiled into a dynamic shared library object (.so/.dll/.dylib).
0 for success, -1 for failure
library_path
: path to library object file containing prediction code
num_worker_thread
: number of worker threads (-1 to use max number)
out
: handle to predictor
TreelitePredictorPredictBatch
(PredictorHandle handle, DMatrixHandle batch, int verbose, int pred_margin, PredictorOutputHandle out_result, size_t *out_result_size)¶Make predictions on a batch of data rows (synchronously). This function internally divides the workload among all worker threads.
Note. This function does not allocate the result vector. Use TreeliteCreatePredictorOutputVector() convenience function to allocate the vector of the right length and type.
Note. To access the element values from the output vector, you should cast the opaque handle (PredictorOutputHandle type) to an appropriate pointer LeafOutputType*, where the type is either float, double, or uint32_t. So carry out the following steps:
Call TreelitePredictorQueryLeafOutputType() to obtain the type of the leaf output. It will return a string (“float32”, “float64”, or “uint32”) representing the type.
Depending on the type string, cast the output handle to float*, double*, or uint32_t*.
Now access the array with the casted pointer. The array’s length is given by TreelitePredictorQueryResultSize().
0 for success, -1 for failure
handle
: predictor
batch
: the data matrix containing a batch of rows
verbose
: whether to produce extra messages
pred_margin
: whether to produce raw margin scores instead of transformed probabilities
out_result
: Resulting output vector. This pointer must point to an array of length TreelitePredictorQueryResultSize() and of type TreelitePredictorQueryLeafOutputType().
out_result_size
: used to save length of the output vector, which is guaranteed to be less than or equal to TreelitePredictorQueryResultSize()
TreeliteCreatePredictorOutputVector
(PredictorHandle handle, DMatrixHandle batch, PredictorOutputHandle *out_output_vector)¶Convenience function to allocate an output vector that is able to hold the prediction result for a given data matrix. The vector’s length will be identical to TreelitePredictorQueryResultSize() and its type will be identical to TreelitePredictorQueryLeafOutputType(). To prevent memory leak, make sure to de-allocate the vector with TreeliteDeletePredictorOutputVector().
Note. To access the element values from the output vector, you should cast the opaque handle (PredictorOutputHandle type) to an appropriate pointer LeafOutputType*, where the type is either float, double, or uint32_t. So carry out the following steps:
Call TreelitePredictorQueryLeafOutputType() to obtain the type of the leaf output. It will return a string (“float32”, “float64”, or “uint32”) representing the type.
Depending on the type string, cast the output handle to float*, double*, or uint32_t*.
Now access the array with the casted pointer. The array’s length is given by TreelitePredictorQueryResultSize().
0 for success, -1 for failure
handle
: predictor
batch
: the data matrix containing a batch of rows
out_output_vector
: Handle to the newly allocated output vector.
TreeliteDeletePredictorOutputVector
(PredictorHandle handle, PredictorOutputHandle output_vector)¶De-allocate an output vector.
0 for success, -1 for failure
handle
: predictor
output_vector
: Output vector to delete from memory
TreelitePredictorQueryResultSize
(PredictorHandle handle, DMatrixHandle batch, size_t *out)¶Given a batch of data rows, query the necessary size of array to hold predictions for all data points.
0 for success, -1 for failure
handle
: predictor
batch
: the data matrix containing a batch of rows
out
: used to store the length of prediction array
TreelitePredictorQueryNumClass
(PredictorHandle handle, size_t *out)¶Get the number classes in the loaded model The number is 1 for most tasks; it is greater than 1 for multiclass classification.
0 for success, -1 for failure
handle
: predictor
out
: length of prediction array
TreelitePredictorQueryNumFeature
(PredictorHandle handle, size_t *out)¶Get the width (number of features) of each instance used to train the loaded model.
0 for success, -1 for failure
handle
: predictor
out
: number of features
TreelitePredictorQueryPredTransform
(PredictorHandle handle, const char **out)¶Get name of post prediction transformation used to train the loaded model.
0 for success, -1 for failure
handle
: predictor
out
: name of post prediction transformation
TreelitePredictorQuerySigmoidAlpha
(PredictorHandle handle, float *out)¶Get alpha value of sigmoid transformation used to train the loaded model.
0 for success, -1 for failure
handle
: predictor
out
: alpha value of sigmoid transformation
TreelitePredictorQueryRatioC
(PredictorHandle handle, float *out)¶Get c value of exponential standard ratio transformation used to train the loaded model.
0 for success, -1 for failure
handle
: predictor
out
: C value of transformation
TreelitePredictorQueryGlobalBias
(PredictorHandle handle, float *out)¶Get global bias which adjusting predicted margin scores.
0 for success, -1 for failure
handle
: predictor
out
: global bias value
TreelitePredictorQueryThresholdType
(PredictorHandle handle, const char **out)¶TreelitePredictorQueryLeafOutputType
(PredictorHandle handle, const char **out)¶TreelitePredictorFree
(PredictorHandle handle)¶delete predictor from memory
0 for success, -1 for failure
handle
: predictor to remove
Treelite uses C++ classes to define its internal data structures. In order to
pass C++ objects to C functions, opaque handles are used. Opaque handles
are void*
pointers that store raw memory addresses.
ModelHandle
¶handle to a decision tree ensemble model
TreeBuilderHandle
¶handle to tree builder class
ModelBuilderHandle
¶handle to ensemble builder class
AnnotationHandle
¶handle to branch annotation data
CompilerHandle
¶handle to compiler class
ValueHandle
¶handle to a polymorphic value type, used in the model builder API
PredictorHandle
¶handle to predictor class
PredictorOutputHandle
¶handle to output from predictor