obliquetree.utils

obliquetree.utils.export_tree(tree, out_file=None)

Serialize a decision tree model to a dictionary or JSON file.

This function converts a trained decision tree into a portable format that can be saved to disk or transmitted. The serialized format preserves all necessary information to reconstruct the tree using load_tree().

Parameters:

  • tree (Union[Classifier, Regressor]) – The trained decision tree model to export. Must be an instance of either Classifier or Regressor and must have been fitted.

  • out_file (str, optional) – If provided, the path where the serialized tree should be saved as a JSON file. If None, the function returns the dictionary representation instead of saving to disk.

Returns:

If out_file is None:

Returns a dictionary containing the serialized tree structure and parameters

If out_file is provided:

Returns None after saving the tree to the specified JSON file

Return type:

Union[None, dict]

obliquetree.utils.export_tree_to_onnx(tree)

Convert an oblique decision tree (Classifier or Regressor) into an ONNX model.

Important

  • This implementation currently does not support batch processing. Only a single row (1D NumPy array) and np.float64 dtype can be passed as input.

  • The input variable name must be “X” and its shape should be (n_features,).

  • In binary classification, the output is a single-dimensional value representing the probability of belonging to the positive class.

Parameters:

tree (Union[Classifier, Regressor]) – The oblique decision tree (classifier or regressor) to be converted to ONNX.

Returns:

The constructed ONNX model.

Return type:

onnx.ModelProto

Examples

>>> # Suppose we have a 2D NumPy array X of shape (num_samples, num_features).
>>> # We only take a single row for prediction:
>>> X_sample = X[0, :]
>>>
>>> # Create an inference session using onnxruntime:
>>> import onnxruntime
>>> session = onnxruntime.InferenceSession("tree.onnx")
>>>
>>> # Retrieve the output name of the model
>>> out_name = session.get_outputs()[0].name
>>>
>>> # Perform inference on the sample
>>> y_pred = session.run([out_name], {"X": X_sample})[0]
>>> print(y_pred)
obliquetree.utils.load_tree(tree_data)

Load a decision tree model from a JSON file or dictionary representation.

This function reconstructs a trained decision tree from its serialized form, either from a JSON file on disk or a dictionary containing the tree structure and parameters.

Parameters:

tree_data (Union[str, Dict]) – Either: - A string containing the file path to a JSON file containing the tree data - A dictionary containing the serialized tree structure and parameters

Returns:

A reconstructed decision tree object. The specific type (Classifier or Regressor) is determined by the ‘task’ parameter in the tree data.

Return type:

Union[Classifier, Regressor]

obliquetree.utils.visualize_tree(tree, feature_names=None, max_cat=None, max_oblique=None, save_path=None, dpi=600, figsize=(20, 10), show_gini=True, show_n_samples=True, show_node_value=True)

Generate a visual representation of a decision tree model.

Creates a graphical visualization of the tree structure showing decision nodes, leaf nodes, and split criteria. The visualization can be customized to show various node statistics and can be displayed or saved to a file.

Parameters:

  • tree (Union[Classifier, Regressor]) – The trained decision tree model to visualize. Must be fitted before visualization.

  • feature_names (List[str], optional) – Human-readable names for the features used in the tree. If provided, these names will be used in split conditions instead of generic feature indices (e.g., “age <= 30” instead of “f0 <= 30”).

  • max_cat (int, optional) – For categorical splits, limits the number of categories shown in the visualization. If there are more categories than this limit, they will be truncated with an ellipsis. Useful for splits with many categories.

  • max_oblique (int, optional) – For oblique splits (those involving multiple features), limits the number of features shown in the split condition. Helps manage complex oblique splits in the visualization.

  • save_path (str, optional) – If provided, saves the visualization to this file path. The file format is determined by the file extension (e.g., ‘.png’, ‘.pdf’).

  • dpi (int, default 600) – The resolution (dots per inch) of the saved image. Only relevant if save_path is provided.

  • figsize (tuple, default (20, 10)) – The width and height of the figure in inches.

  • show_gini (bool, default True) – Whether to display Gini impurity values in the nodes.

  • show_n_samples (bool, default True) – Whether to display the number of samples that reach each node.

  • show_node_value (bool, default True) – Whether to display the predicted value/class distributions in each node.

Returns:

The function displays the visualization and optionally saves it to disk.

Return type:

None