Treelite

The Treelite C API is organized into several functional interfaces depending on the task:

• Model loader interface: Functions to load decision tree ensemble models from various supported file formats.
• Model loader interface for scikit-learn models: Specialized functions to load models directly from scikit-learn model objects.
• Model builder interface: Functions to incrementally build decision tree ensemble models.
• Model manager interface: Functions for managing model lifecycles.
• Serializer: Functions for serializing and deserializing models.
• Getters and setters for the model object: Accessor functions to retrieve or modify model properties.
• General Tree Inference Library (GTIL): Interface for tree inference operations.

In v4, multi-target and multi-class models are handled using a specific shaping heuristic to ensure compatibility with vector-leaf outputs:

• Leaf Vector Shape: The shape is defined as (num_target, max(num_class)).
• Padding: If different targets have different numbers of classes, the leaf vectors and base_scores are shaped using the largest number of classes (max_num_class), and extra elements are padded with 0.
• Implication: If one target has significantly more classes than others, it may result in wasted space due to padding. This follows the same method used by sklearn.ensemble.RandomForestClassifier.

The Treelite Serialization Format v3 is a binary format used to represent tree-based models. A serialized model consists of a header, global model parameters, and a sequence of trees. Each tree contains a collection of nodes, leaf vectors, and optional categorical data.

Model Configuration Types The model's precision is determined by two template parameters:

• ThresholdType: The type used for split thresholds (e.g., float or double).
• LeafOutputType: The type used for leaf values (e.g., uint32_t or float).

Allowed combinations:

• float threshold / uint32_t leaf
• float threshold / float leaf
• double threshold / uint32_t leaf
• double threshold / double leaf

When predicting with tree ensemble models, Treelite sums the margin scores from individual trees. A postprocessor function (also known as a link function) is applied to this sum to transform the raw margin scores into the final prediction format (e.g., probabilities or raw values).

Postprocessors are categorized into two types:

1. Element-wise: Applied to each individual score in the margin score vector independently.
2. Row-wise: Applied across all scores in a single row (typically used for multiclass classification to ensure probabilities sum to 1).

For advanced users, Treelite provides HeaderAccessor and TreeAccessor to query and modify the internal fields of a treelite.Model object.

Warning: Unsafe Operation Modifying fields via accessors is an unsafe operation. Treelite does not validate the values assigned to fields, and setting invalid values (e.g., an array of incorrect length for num_nodes) may cause undefined behavior. Always verify field constraints against the model specification (e.g., serialization/v4) before modification.

The Treelite v4 serialization format is designed for high-performance model deployment with the following key features:

• Multi-target support: First-class support for models with multiple targets.
• Boosting from the average: Supports scikit-learn style initialization where a base estimator (fitted from class distribution or average label) is used as the initial learner.
• Fixed-width integer types: Uses explicit widths (e.g., int32_t) for predictable cross-platform serialization.

Important Implementation Note: Always use little-endian byte order when reading or writing scalars and arrays.