supertree API完整参考：SuperTree、Node与TreeData三大核心类详解

supertree 是一个在 Jupyter 中实现交互式决策树可视化的 Python 库，支持 scikit-learn、LightGBM、XGBoost 和 ONNX 模型，让决策树可视化支持缩放、折叠、动态深度调节与单样本路径追踪。本文完整解析 supertree 的 API：SuperTree、Node、TreeData 三大核心类的参数、方法与数据流转机制，帮助你快速掌握决策树可视化 API。

🧭 三大核心类一图看懂

supertree 的核心代码集中在supertree/目录，三个类的分工非常清晰：

数据流转路径：SuperTree.__init__接收训练好的模型 →convert_model_to_dict_array()把模型解析为节点字典列表 → 每个字典构建一个Node对象 → 用 DFS 算法 _create_node_dfs() 组织成树 → 最终与TreeData合并为 JSON，交给前端 D3.js 渲染成可交互的决策树。

🌳 SuperTree：决策树可视化主类

构造参数详解

SuperTree构造函数在 supertree/supertree.py 中定义，负责全部参数校验：

💡 注意：构造时会自动调用 is_model_fitted() 检查模型是否已fit()，未训练会直接抛出Model is not fitted异常；which_model()会自动识别这是分类还是回归模型。

常用方法速查

show_tree()的参数是日常使用中最常打交道的部分：

支持的模型清单

SuperTree内部通过 valid_model_classes 白名单校验模型，目前支持：

• scikit-learn：DecisionTree*、ExtraTree*、ExtraTrees*、RandomForest*、GradientBoosting*、HistGradientBoosting*
• LightGBM：LGBMClassifier、LGBMRegressor、Booster
• XGBoost：XGBClassifier、XGBRegressor、XGBRF*、Booster
• ONNX：ModelProto树模型
• 自定义：通过 ModelLoader 手动传入节点字典列表，可视化任意框架的树

🪴 Node：决策树节点数据结构

Node类（supertree/node.py）描述树中的每一个节点，由SuperTree在解析模型时自动创建，一般不需要手动实例化。

两个关键方法：

• to_dict()：把节点递归转换为可 JSON 序列化的字典，并自动处理 numpy 标量、ndarray、pandas Series 类型转换；
• add_left() / add_right()：在 DFS 遍历 _create_node_dfs() 过程中，把子节点挂到父节点，同时累积每个特征上的样本区间（如petal_width < 0.8且> 0.6），这就是悬停节点时能展示直方图/散点图的数据基础。

🗂️ TreeData：样本数据与可视化配置容器

TreeData类（supertree/treedata.py）由SuperTree.__init__自动构建，保存"数据侧"的所有信息，与Node的"结构侧"互补。

核心属性：

常用方法：to_dict() 生成tree_data部分 JSON；set_show_sample() 校验样本长度后设置高亮样本；convert_target_strings() 把字符串标签自动映射为类别索引。

📦 最终输出：两部分 JSON 结构

渲染时 _get_combined_data() 会把两部分合并成一个 JSON 传给前端：

{ "node_data": {...}, # Node.to_dict() 递归生成的树结构 "tree_data": {...} # TreeData.to_dict() 生成的数据与配置 }

save_html()与save_json_tree()的区别就在于：前者把该 JSON 嵌入 templatehtml.py 的 D3.js 模板，后者仅导出纯 JSON 供二次开发使用。

⚠️ 常见报错速查

📚 相关源码与文档

• 主类实现：supertree/supertree.py
• 节点结构：supertree/node.py
• 数据容器：supertree/treedata.py
• 自定义模型加载器：supertree/model_loader.py
• 完整 API 文档：docs/python_docs.md
• 官方示例 Notebook：examples/MainExample.ipynb、examples/GradientBoostExample.ipynb

掌握 SuperTree 的参数校验、Node 的树形组织与 TreeData 的数据封装这三块，你就理解了 supertree 决策树可视化的全部 API 骨架——剩下的缩放、路径高亮、SVG 导出等交互能力，都由前端自动接管。