Source code for neural_trees.decision_trees.numpy_soft_tree

"""
A fitted soft decision tree as plain numpy: predict, serialise, ship.

`to_hard_tree()` gives readable rules at the price of being a different model.
This is the other export: the *same* model, the mixture over leaves included,
with no PyTorch in the prediction path and a JSON form that round-trips. Use
it to deploy a fitted tree where torch is not installed, or to freeze one for
audit. Predictions agree with the torch model to float32 precision.
"""
from __future__ import annotations

import json
from typing import Any, Dict, List, Optional, Sequence

import numpy as np

from neural_trees._missing import augment


def _log_sigmoid(z: np.ndarray) -> np.ndarray:
    # stable log(sigmoid(z)) = -softplus(-z)
    return -np.logaddexp(0.0, -z)


def _log_softmax(a: np.ndarray) -> np.ndarray:
    m = a.max(axis=1, keepdims=True)
    return a - m - np.log(np.exp(a - m).sum(axis=1, keepdims=True))



[docs] class NumpySoftTree: """ Torch-free copy of a fitted :class:`~neural_trees.SoftDecisionTree` or :class:`~neural_trees.SoftDecisionTreeRegressor` (``kind``). Parameters are the tree's own: gate weights ``(n_internal, n_features)``, gate biases, per-gate log temperatures, node logits ``(n_nodes, n_classes)`` and the ``is_split`` flags that say which internal nodes act as leaves. """ def __init__(self, depth: int, weights, biases, log_beta, node_logits, is_split, classes: Sequence[Any], feature_names: Optional[Sequence[str]] = None, kind: str = "classifier", y_mean=None, y_scale=None, single_output: bool = True, missing_columns: Optional[Sequence[int]] = None): if kind not in ("classifier", "regressor"): raise ValueError(f"kind must be 'classifier' or 'regressor', got {kind!r}") self.kind = kind # For a regressor `node_logits` holds standardised leaf values and the # two arrays below map them back to target units. self.y_mean_ = None if y_mean is None else np.asarray(y_mean, dtype=np.float64) self.y_scale_ = None if y_scale is None else np.asarray(y_scale, dtype=np.float64) self.single_output_ = bool(single_output) self.depth = int(depth) self.weights_ = np.asarray(weights, dtype=np.float64) self.biases_ = np.asarray(biases, dtype=np.float64) self.log_beta_ = np.asarray(log_beta, dtype=np.float64) self.node_logits_ = np.asarray(node_logits, dtype=np.float64) self.is_split_ = np.asarray(is_split, dtype=bool) self.classes_ = np.asarray(list(classes)) self.feature_names_ = list(feature_names) if feature_names is not None else None self.n_internal_ = 2 ** self.depth - 1 self.n_leaves_ = 2 ** self.depth # features with missing values in training: their indicators are the # last len(missing_columns) gate inputs (see neural_trees._missing) self.missing_columns_ = np.asarray(missing_columns if missing_columns is not None else [], dtype=np.int64) self.n_features_in_ = self.weights_.shape[1] - len(self.missing_columns_) if self.weights_.shape[0] != self.n_internal_: raise ValueError(f"expected {self.n_internal_} gates for depth {self.depth}, got {self.weights_.shape[0]}") # ── prediction · only the gates that split, in log space ── def _compiled(self): """ Gates that split, and for every acting leaf the signs of its path. A depth-8 tree has 255 gates, but after growth or pruning usually far fewer of them split. Computing only those, and summing each leaf's path as one matrix product, gives the same numbers as the full walk at a fraction of the cost. """ cached = getattr(self, "_paths_cache", None) if cached is not None: return cached from neural_trees.decision_trees.onnx_export import _paths leaves = _paths(self.depth, self.is_split_) gates = np.array(sorted({g for _, path in leaves for g, _ in path}), dtype=np.int64) col = {int(g): i for i, g in enumerate(gates)} # path matrix over [log sigmoid(z) for each gate, log sigmoid(-z) for each gate] P = np.zeros((2 * len(gates), len(leaves))) for t, (_, path) in enumerate(leaves): for g, right in path: P[col[g] + (0 if right else len(gates)), t] = 1.0 nodes = np.array([node for node, _ in leaves], dtype=np.int64) self._paths_cache = (gates, P, nodes) return self._paths_cache def _arrival(self, X): """(terms, log_mu) for every acting leaf: node index and log arrival mass.""" X = np.asarray(X, dtype=np.float64) if X.ndim != 2 or X.shape[1] != self.n_features_in_: raise ValueError(f"X must have shape (n_samples, {self.n_features_in_})") X = augment(X, self.missing_columns_) gates, P, nodes = self._compiled() if len(gates) == 0: return nodes, np.zeros((X.shape[0], 1)) z = np.exp(self.log_beta_[gates]) * (X @ self.weights_[gates].T + self.biases_[gates]) right = _log_sigmoid(z) return nodes, np.hstack([right, right - z]) @ P # log sigmoid(-z) = log sigmoid(z) - z
[docs] def predict_values(self, X) -> np.ndarray: """Regressor only: arrival-weighted leaf values, in target units.""" if self.kind != "regressor": raise AttributeError("predict_values is for a regressor export; use predict_proba") nodes, log_mu = self._arrival(X) mu = np.exp(log_mu) # (n, terms) out = mu @ self.node_logits_[nodes] # (n, n_outputs), standardised out = out * self.y_scale_ + self.y_mean_ return out[:, 0] if self.single_output_ else out
def predict_log_proba(self, X) -> np.ndarray: if self.kind != "classifier": raise AttributeError("predict_log_proba is for a classifier export; use predict_values") nodes, log_mu = self._arrival(X) # (n, terms) log_dist = _log_softmax(self.node_logits_)[nodes] # (terms, K) # log sum_t mu_t * p_t, both factors scaled by their maxima first m = log_mu.max(axis=1, keepdims=True) k = log_dist.max(axis=0, keepdims=True) with np.errstate(divide="ignore"): out = m + k + np.log(np.exp(log_mu - m) @ np.exp(log_dist - k)) bad = ~np.isfinite(out).all(axis=1) if bad.any(): # underflow: exact sum allp = log_mu[bad][:, :, None] + log_dist[None, :, :] mm = allp.max(axis=1, keepdims=True) out[bad] = (mm + np.log(np.exp(allp - mm).sum(axis=1, keepdims=True)))[:, 0, :] return out def predict_proba(self, X) -> np.ndarray: return np.exp(self.predict_log_proba(X)) def predict(self, X) -> np.ndarray: if self.kind == "regressor": return self.predict_values(X) return self.classes_[self.predict_proba(X).argmax(axis=1)] # ── ONNX ──
[docs] def to_onnx(self, opset: int = 17): """The same model as an ``onnx.ModelProto``; see :mod:`neural_trees.decision_trees.onnx_export`.""" from neural_trees.decision_trees.onnx_export import to_onnx return to_onnx(self, opset=opset)
[docs] def save_onnx(self, path: str, opset: int = 17) -> None: """Write :meth:`to_onnx` to a file.""" from neural_trees.decision_trees.onnx_export import save_onnx save_onnx(self, path, opset=opset)
# ── serialisation ── def to_dict(self) -> Dict[str, Any]: return { "format": "neural-trees/soft-tree/1", "depth": self.depth, "weights": self.weights_.tolist(), "biases": self.biases_.tolist(), "log_beta": self.log_beta_.tolist(), "node_logits": self.node_logits_.tolist(), "is_split": self.is_split_.tolist(), "classes": self.classes_.tolist(), "feature_names": self.feature_names_, "kind": self.kind, "y_mean": None if self.y_mean_ is None else self.y_mean_.tolist(), "y_scale": None if self.y_scale_ is None else self.y_scale_.tolist(), "single_output": self.single_output_, "missing_columns": self.missing_columns_.tolist(), } def to_json(self, path: Optional[str] = None) -> str: text = json.dumps(self.to_dict()) if path is not None: with open(path, "w", encoding="utf-8") as f: f.write(text) return text @classmethod def from_dict(cls, d: Dict[str, Any]) -> NumpySoftTree: if d.get("format") != "neural-trees/soft-tree/1": raise ValueError(f"unknown format {d.get('format')!r}") return cls(d["depth"], d["weights"], d["biases"], d["log_beta"], d["node_logits"], d["is_split"], d["classes"], d.get("feature_names"), kind=d.get("kind", "classifier"), y_mean=d.get("y_mean"), y_scale=d.get("y_scale"), single_output=d.get("single_output", True), missing_columns=d.get("missing_columns")) @classmethod def from_json(cls, text_or_path: str) -> NumpySoftTree: s = text_or_path if not s.lstrip().startswith("{"): with open(s, encoding="utf-8") as f: s = f.read() return cls.from_dict(json.loads(s))