Treelite
Functions
Predictor

Functions

int 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). More...
 
int 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. More...
 
int 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(). More...
 
int TreeliteDeletePredictorOutputVector (PredictorHandle handle, PredictorOutputHandle output_vector)
 De-allocate an output vector. More...
 
int 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. More...
 
int 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. More...
 
int TreelitePredictorQueryNumFeature (PredictorHandle handle, size_t *out)
 Get the width (number of features) of each instance used to train the loaded model. More...
 
int TreelitePredictorQueryPredTransform (PredictorHandle handle, const char **out)
 Get name of post prediction transformation used to train the loaded model. More...
 
int TreelitePredictorQuerySigmoidAlpha (PredictorHandle handle, float *out)
 Get alpha value of sigmoid transformation used to train the loaded model. More...
 
int TreelitePredictorQueryRatioC (PredictorHandle handle, float *out)
 Get c value of exponential standard ratio transformation used to train the loaded model. More...
 
int TreelitePredictorQueryGlobalBias (PredictorHandle handle, float *out)
 Get global bias which adjusting predicted margin scores. More...
 
int TreelitePredictorQueryThresholdType (PredictorHandle handle, const char **out)
 
int TreelitePredictorQueryLeafOutputType (PredictorHandle handle, const char **out)
 
int TreelitePredictorFree (PredictorHandle handle)
 delete predictor from memory More...
 

Detailed Description

Predictor interface

Function Documentation

◆ TreeliteCreatePredictorOutputVector()

int 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:

  1. Call TreelitePredictorQueryLeafOutputType() to obtain the type of the leaf output. It will return a string ("float32", "float64", or "uint32") representing the type.
  2. Depending on the type string, cast the output handle to float*, double*, or uint32_t*.
  3. Now access the array with the casted pointer. The array's length is given by TreelitePredictorQueryResultSize().
    Parameters
    handlepredictor
    batchthe data matrix containing a batch of rows
    out_output_vectorHandle to the newly allocated output vector.
    Returns
    0 for success, -1 for failure

Definition at line 53 of file c_api_runtime.cc.

◆ TreeliteDeletePredictorOutputVector()

int TreeliteDeletePredictorOutputVector ( PredictorHandle  handle,
PredictorOutputHandle  output_vector 
)

De-allocate an output vector.

Parameters
handlepredictor
output_vectorOutput vector to delete from memory
Returns
0 for success, -1 for failure

Definition at line 62 of file c_api_runtime.cc.

◆ TreelitePredictorFree()

int TreelitePredictorFree ( PredictorHandle  handle)

delete predictor from memory

Parameters
handlepredictor to remove
Returns
0 for success, -1 for failure

Definition at line 141 of file c_api_runtime.cc.

◆ TreelitePredictorLoad()

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

Parameters
library_pathpath to library object file containing prediction code
num_worker_threadnumber of worker threads (-1 to use max number)
outhandle to predictor
Returns
0 for success, -1 for failure

Definition at line 30 of file c_api_runtime.cc.

◆ TreelitePredictorPredictBatch()

int 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:

  1. Call TreelitePredictorQueryLeafOutputType() to obtain the type of the leaf output. It will return a string ("float32", "float64", or "uint32") representing the type.
  2. Depending on the type string, cast the output handle to float*, double*, or uint32_t*.
  3. Now access the array with the casted pointer. The array's length is given by TreelitePredictorQueryResultSize().
    Parameters
    handlepredictor
    batchthe data matrix containing a batch of rows
    verbosewhether to produce extra messages
    pred_marginwhether to produce raw margin scores instead of transformed probabilities
    out_resultResulting output vector. This pointer must point to an array of length TreelitePredictorQueryResultSize() and of type TreelitePredictorQueryLeafOutputType().
    out_result_sizeused to save length of the output vector, which is guaranteed to be less than or equal to TreelitePredictorQueryResultSize()
    Returns
    0 for success, -1 for failure

Definition at line 38 of file c_api_runtime.cc.

◆ TreelitePredictorQueryGlobalBias()

int TreelitePredictorQueryGlobalBias ( PredictorHandle  handle,
float *  out 
)

Get global bias which adjusting predicted margin scores.

Parameters
handlepredictor
outglobal bias value
Returns
0 for success, -1 for failure

Definition at line 116 of file c_api_runtime.cc.

◆ TreelitePredictorQueryNumClass()

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

Parameters
handlepredictor
outlength of prediction array
Returns
0 for success, -1 for failure

Definition at line 78 of file c_api_runtime.cc.

◆ TreelitePredictorQueryNumFeature()

int TreelitePredictorQueryNumFeature ( PredictorHandle  handle,
size_t *  out 
)

Get the width (number of features) of each instance used to train the loaded model.

Parameters
handlepredictor
outnumber of features
Returns
0 for success, -1 for failure

Definition at line 85 of file c_api_runtime.cc.

◆ TreelitePredictorQueryPredTransform()

int TreelitePredictorQueryPredTransform ( PredictorHandle  handle,
const char **  out 
)

Get name of post prediction transformation used to train the loaded model.

Parameters
handlepredictor
outname of post prediction transformation
Returns
0 for success, -1 for failure

Definition at line 92 of file c_api_runtime.cc.

◆ TreelitePredictorQueryRatioC()

int TreelitePredictorQueryRatioC ( PredictorHandle  handle,
float *  out 
)

Get c value of exponential standard ratio transformation used to train the loaded model.

Parameters
handlepredictor
outC value of transformation
Returns
0 for success, -1 for failure

Definition at line 109 of file c_api_runtime.cc.

◆ TreelitePredictorQueryResultSize()

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

Parameters
handlepredictor
batchthe data matrix containing a batch of rows
outused to store the length of prediction array
Returns
0 for success, -1 for failure

Definition at line 70 of file c_api_runtime.cc.

◆ TreelitePredictorQuerySigmoidAlpha()

int TreelitePredictorQuerySigmoidAlpha ( PredictorHandle  handle,
float *  out 
)

Get alpha value of sigmoid transformation used to train the loaded model.

Parameters
handlepredictor
outalpha value of sigmoid transformation
Returns
0 for success, -1 for failure

Definition at line 102 of file c_api_runtime.cc.