path_boost: 一个基于路径梯度提升的可解释图级别预测Python包

# path_boost: 一个基于路径梯度提升的可解释图级别预测Python包

来源: https://arxiv.org/html/2607.07935

\[1,\\]\\fnmClaudio\\surMeggio 1\]\\orgdiv数学系,\\orgname奥斯陆大学,\\orgaddress\\city奥斯陆,\\postcode0371,\\state奥斯陆,\\country挪威

###### 摘要

我们提出 `path_boost`，这是一个用于图结构输入数据上的可解释监督学习的 Python 包。该包实现了 PathBoost 算法，一种梯度提升算法，能够在学习过程中自动发现图内具有预测能力的标记路径。与通常难以解释的图神经网络不同，PathBoost 生成一个基于路径特征的加性预测模型，明确揭示了哪些子结构驱动了预测。为了避免穷举所有可能的路径，该算法在学习过程中根据预测能力迭代地选择和扩展路径，利用提升方法将弱学习器组合成强集成模型。该包支持回归和二分类。关键特性包括：与 `scikit-learn` 工作流的兼容性、支持自定义基学习器和选择器、自动起始节点选择、跨锚节点的并行训练，以及内置的变量重要性计算。我们通过过渡金属化合物的分子性质预测展示了 PathBoost，其中原子作为节点，键作为边，并进一步在六个分子数据集上将 PathBoost 与已建立的图神经网络和图核方法进行了基准测试。该包在 PyPI 和 GitHub 上以开源许可证提供。

###### 关键词: 图级别预测, 梯度提升, 可解释机器学习, 分子性质预测, 开源软件, networkx

## 1 引言

图结构化数据在科学和工业领域中日益普遍，包括分子化学、材料科学和社会网络分析。与传统的表格数据不同，图捕捉实体之间的关系和交互，使其成为机器学习中一种强大但具有挑战性的数据结构。特别是，从图中学习预测模型需要能够从其结构中提取有意义特征的方法，并且理想情况下应以可解释的方式完成。在此预测任务的现有方法中，最常见的是图神经网络（GNN）和图核方法。GNN 已成为从图数据学习的主流范式，在许多基准测试上取得了强大的实证结果[gilmer2017neural, hu2020ogb]。然而，GNN 存在一些实际局限性：它们通常被认为难以解释[Wu2021]，并且常常需要大量训练数据才能有效泛化[Ding2024]。经典的图核方法与支持向量机相结合，在小规模数据集上仍然具有竞争力[Kriege2020]，但依赖于固定的特征表示，在学习过程中不会自适应，而且得到的模型在实践中可解释性有限。

先前的工作 [meggio2024pathboost] 介绍了一种基于路径的提升框架，用于过渡金属化合物的分子图回归，其中使用指定的金属中心节点（称为锚节点）作为路径探索的起始点。[meggio_2nd] 在几个方向上扩展了该框架：通过一个两步基学习器（将路径选择与路径拟合分离）将多个节点和边属性纳入路径特征空间；引入基于分类属性多样性的自动锚节点选择；以及通过逻辑损失将该算法适应于二分类。这些工作还形式化了路径级变量重要性的绝对和相对变体，并在十二个 TUDataset 基准测试上展示了与图神经网络和核方法相比具有竞争力的性能。

在本文中，我们介绍 `path_boost`，一个开源 Python 包，实现了 [meggio2024pathboost] 和 [meggio_2nd] 中开发的 PathBoost 算法。此外，`path_boost` 引入了两个方法论扩展：一个多锚点并行架构，为每个锚点标签训练独立的子模型并聚合其预测；以及一个增强的变量重要性框架，其中包括一个相关性调整，以考虑嵌套路径之间的结构依赖关系。该实现遵循 `scikit-learn` 约定，实现了 `fit()`、`predict()`、`get_params()` 和 `set_params()` 方法，从而兼容标准工具（如 `GridSearchCV`）进行超参数调优。图使用 `networkx` 库表示[hagberg2008exploring]。

本文的其余部分组织如下：第2节 (https://arxiv.org/html/2607.07935#S2) 介绍关键术语并定义问题设置。第3节 (https://arxiv.org/html/2607.07935#S3) 描述算法，包括带逐步说明的提升过程和变量重要性度量。第4节 (https://arxiv.org/html/2607.07935#S4) 涵盖软件设计和实现细节。第5节 (https://arxiv.org/html/2607.07935#S5) 提供教程，使用 tmQMg 数据集在分子性质预测任务上演示该包。第6节 (https://arxiv.org/html/2607.07935#S6) 报告在六个分子数据集上与 GINE 和 WL + SVR 的基准比较。第7节 (https://arxiv.org/html/2607.07935#S7) 以关于该包性能的一些评论作为结论。

## 2 预备知识

### 2.1 术语

我们介绍本文使用的关键术语：

- •**标记路径**: 一个有序的锚点属性值序列 \(l_1, l_2, \ldots, l_m\)，对应于图中通过边连接的连续节点的一次游走。
- •**提升矩阵 (BM)**: 一个频率矩阵，其中每列对应一条标记路径，每行对应一个图。条目 \(i, u\) 记录标记路径 \(u\) 在图 \(G_i\) 中出现的次数。
- •**扩展提升矩阵 (EBM)**: BM 的扩展版本，对于每条标记路径，沿着该路径及其所有前缀，包括平均数值节点和边属性。
- •**前缀**: 如果 \(k \leq m\) 且对于所有 \(j = 1, \ldots, k\) 有 \(q_j = p_j\)，则标记路径 \(q = (q_1, \ldots, q_k)\) 是标记路径 \(p = (p_1, \ldots, p_m)\) 的一个前缀。
- •**锚点节点**: 一个指定为路径探索起点的节点。锚点通常由用户选择，或者基于其分类属性多样性的启发式规则自动选择（第3.3.1节）。
- •**锚点标签**: 锚点节点的分类属性值。它唯一标识图中的一个起始节点类别。
- •**候选路径**: 一条在特定提升迭代中被视为潜在添加的标记路径。候选路径是通过扩展从先前迭代中选出的路径的前缀生成的。
- •**基学习器**: 一个弱学习器，在给定迭代中被拟合到与所选路径及其前缀对应的 EBM 列上。
- •**选择器**: 一个学习器，通过识别特征重要性最高的BM列来选择路径。
- •**未探索节点**: 一个图 \(G_i\) 中的一个节点，其类别属性带有标签 \(l\)，但尚未被包含在该迭代的任何候选路径中。

> **注意（多锚点训练）。** 在并行多锚点设置中，上述所有术语均适用于每个锚点标签的子模型。每个子模型维护自己的 BM、EBM 和候选路径集，继承其起始锚点标签的标记。

### 2.2 问题设置

让 \(\mathcal{G} = \{G_1, G_2, \ldots, G_n\}\) 是一个有 \(n\) 个图的集合。每个图 \(G_i\) 是一个带有属性的图，由以下内容给出：

- 节点集 \(V_i\)，其中每个节点 \(v \in V_i\) 与一个分类属性（例如原子符号）和一个或多个数值属性（例如原子电荷）相关联。
- 边集 \(E_i\)，其中每条边 \(e \in E_i\) 可能与一个或多个数值属性（例如键长）相关联。

我们考虑**图级别回归**问题：给定 \(\{(G_i, y_i)\}_{i=1}^n\)，其中 \(y_i \in \mathbb{R}\)，学习一个函数 \(f: \mathcal{G} \to \mathbb{R}\) 来预测未见图的响应变量。该包也支持**二分类**，其中 \(y_i \in \{0, 1\}\)。目标是构建一个可解释的模型，该模型利用图中出现的有向标记路径作为特征。该算法自动发现这些路径并学习它们的联合预测贡献。

### 2.3 路径与变量表示法

令 \(P\) 表示为学习过程中发现的一组标记路径。每条路径 \(p \in P\) 是一个标记元组 \(p = (l_1, l_2, \ldots, l_m)\)。对于节点属性，我们考虑一个数值节点属性 \(x_v\)（例如原子电荷），对于边属性，我们考虑一个数值边属性 \(w_e\)（例如键长）。沿着路径 \(p\) 的平均节点属性定义为

\[
\bar{x}_p = \frac{1}{|p|} \sum_{v \in p} x_v,
\]

其中 \(|p|\) 是路径中的节点数。类似地，平均边属性为

\[
\bar{w}_p = \frac{1}{|p|-1} \sum_{e \in p} w_e,
\]

其中求和对路径中连续的边进行。这些平均值是重要的特征，因为它们捕获了路径级上下文。除了这些平均值之外，路径在 BM 中的频率计数也是一个关键特征：它们告诉路径在整个图中出现的多次，从而捕获结构模式。

## 3 算法

### 3.1 总体提升过程

该算法（算法1）构建一个加权和形式的加性模型

\[
F(G) = \sum_{t=1}^T f_t(G),
\]

其中每个基学习器 \(f_t\) 是一个弱学习器，拟合到由路径选择器从 BM 中选择的路径对应的 EBM 列上。该过程以贪心分层方式进行。从空模型开始，在每次迭代中，算法：

1. 计算当前模型的负梯度（对于最小二乘回归，即残差）。
2. 使用选择器从 BM 中选择具有最高预测能力的候选路径（基于特征重要性）。
3. 将选择的路径添加到活动路径集中。
4. 构建一个基学习器，拟合到所选路径及其前缀的 EBM 列以及残差上。
5. 将基学习器的预测以收缩率 \(\nu \in (0, 1]\) 添加到整体模型中（学习率）。
6. 通过考虑其所有可能扩展来生成新的候选路径。

**路径空间探索。** 该算法不会预先生成所有可能的标记路径；相反，它会主动探索路径空间。它从集合 \(P = \{\}\) 开始，候选路径集为空，并逐步扩展已选择路径的前缀。关键是在任何时候，路径集 \(P\) 被隐式地定义为一个前缀闭合集——如果一条路径在 \(P\) 中，那么它的所有前缀也在 \(P\) 中。这个属性确保 EBM 包含嵌套的路径表示，使基学习器能够根据统计信息在一般和特定模式之间进行选择。

**变量重要性。** 在拟合后，该包提供两个互补的变量重要性度量（第3.4节）：
- **绝对重要性**: 通过对所有基学习器中使用的路径的权重求和，有效地衡量每条路径的总预测贡献。
- **相对重要性**: 标准化绝对重要性，以量化每条路径在模型预测方差中的相对贡献。

**早期停止和迭代次数。** 迭代次数 \(T\) 是一种关键的复杂度参数。该包支持两种停止准则：基于验证集的耐心（patience）参数和基于精确误差阈值的目标误差（第4.9节）。默认情况下，不使用早期停止，并且如果没有提供验证集，模型会训练满 \(n\_iter\) 次迭代。

> **算法1 PathBoost 框架**
>
> **输入**: 数据集 \(\{G_i, y_i\}_{i=1}^n\)，锚点节点集 \(A\)，路径迭代次数 \(T\)，收缩率 \(\nu\)，最大路径长度 \(L_{\max}\)，维度 d
> **输出**: 集成模型 \(F(G)\)
>
> 1: 对于每个锚点标签 \(l_a \in A\):
> 2:    初始化 \(P_{l_a} \leftarrow \{\}\)， \(P_{l_a}^{\text{cand}} \leftarrow \{(l_a)\}\)， \(F_{l_a}(G) \leftarrow 0\)
> 3:    对于 \(t = 1\) 到 \(T\):
> 4:        计算残差 \(r_i = y_i - F_{l_a}(G_i)\) 对于所有 \(i\)
> 5:        使用选择器从 \(P_{l_a}^{\text{cand}}\) 中选择路径 \(p_t\)
> 6:        更新 \(P_{l_a} \leftarrow P_{l_a} \cup \{p_t\}\)
> 7:        构建基学习器 \(f_t\)，拟合到 \(p_t\) 的 EBM 列及其前缀以及 \(r_i\) 上
> 8:        更新 \(F_{l_a}(G) \leftarrow F_{l_a}(G) + \nu f_t(G)\)
> 9:        将新的候选路径添加到 \(P_{l_a}^{\text{cand}}\) 中（长度不超过 \(L_{\max}\) 的扩展）
> 10:   t 循环结束
> 11: 锚点标签循环结束
> 12: 返回 \(F(G) = \sum_{l_a \in A} F_{l_a}(G)\)

### 3.2 逐步说明

为了在收敛性论证之前给出算法的直观理解，我们展示一个有三个图的简单示例的逐步说明。

**设置。** 考虑三个分子图 \(G_1\)、\(G_2\) 和 \(G_3\)，节点（原子）具有分类标签：O（氧）、C（碳）和 H（氢）。边（键）是未标记的。每个图恰好包含一个锚点节点，由标签“C_anchor”（一种特殊碳）标识。响应变量是沸点，使得 \(y_1 = 80\) 和 \(y_2 = y_3 = 70\)。初始模型是 \(F(G) = 0\)，收缩率 \(\nu = 1\)。

**迭代 1。**
- 负梯度（残差）等于 \(y_i\)，因为所有预测都为零：\(r_1 = 80\)，\(r_2 = 70\)，\(r_3 = 70\)。
- 候选路径集包含长度为1的路径（从锚点节点开始）：\(\{(C\_锚点)\}\)，\(\{(C\_锚点, O)\}\)，\(\{(C\_锚点, C)\}\)，\(\{(C\_锚点, H)\}\)。
- 选择器（决策桩）检查 BM 列：
  - BM 列“C_锚点”在所有图中都计为1（每个图恰好有一个锚点）。
  - BM 列“(C_锚点, O)”在 \(G_1\) 中计为1，但在 \(G_2\) 和 \(G_3\) 中计为0。
  - BM 列“(C_锚点, C)”在 \(G_1\) 和 \(G_2\) 中计为1，在 \(G_3\) 中计为0。
  - BM 列“(C_锚点, H)”在 \(G_1\) 和 \(G_2\) 中计为7，在 \(G_3\) 中计为1。
- 选择器发现“(C_锚点, H)”列与残差相关性最强（因为 \(r_1 = 80\)，\(r_2 = 70\)，\(r_3 = 70\)，而该列具有不同的模式）。它选择路径“(C_锚点, H)”。
- 基学习器拟合到“C_锚点”和“(C_锚点, H)”的 EBM 列上。在这个简化示例中，基学习器预测两个图中该路径出现的差值的平均值：当 \(count \geq 7\) 时预测为 75，否则预测为 70。
- 模型更新：\(F(G_1) = 75\)，\(F(G_2) = 75\)，\(F(G_3) = 70\)。
- 候选路径集通过扩展“(C_锚点, H)”扩展到长度为2的路径来更新：“(C_锚点, H, O)”、“(C_锚点, H, C)”、“(C_锚点, H, H)”。

**迭代 2。**
- 残差现在是：\(r_1 = 5\)，\(r_2 = -5\)，\(r_3 = 0\)。
- 选择器选择路径“(C_锚点, H, H)”，它出现在两个图中（在 \(G_1\) 中出现 3 次，在 \(G_2\) 中出现 7 次，在 \(G_3\) 中出现 0 次）。
- 基学习器拟合到“(C_锚点, H, H)”的 EBM 列及其前缀上，将残差建模为出现次数的函数。
- 最终模型：\(F(G_1) = 75 + 5 = 80\)，\(F(G_2) = 75 - 5 = 70\)，\(F(G_3) = 70 + 0 = 70\)。

### 3.3 收敛性论证

对于回归，该算法最小化平方误差损失，是经典梯度提升的一个实例。每个基学习器 \(f_t\) 是一个回归器，拟合到由选择器选择的路径对应的 EBM 列上。平方误差损失的负梯度是残差 \(y_i - F(G_i)\)，并且拟合步骤最小化这些残差的加权平方和。由于 EBM 列是从有限的候选集中选择的，并且基学习器是作为最小二乘学习器实现的，因此该算法继承了 Friedman 的梯度提升机 (GBM) 的收敛性质：在固定特征集上，损失函数随着每次迭代而单调递减，前提是基学习器完全消除残差。这里的区别在于，特征集（路径）随着迭代而增长。然而，每轮路径选择步骤相当于在候选特征集上执行软特征选择，候选特征集是有限的，因此只要候选集中存在相关路径，该算法就保证收敛到局部最优。

对于分类，使用逻辑损失 \(L(y, F) = \log(1 + \exp(-2yF))\)，其中 \(y \in \{-1, 1\}^n\)，并且用 LogisticPathBoost 类实现。基学习器预测对数几率，并且该算法采用一个专门的内部学习器，该学习器直接优化逻辑损失，遵循 Friedman 的方法。与标准 GBM 的收敛性论证类似，只要每次迭代进行适当的行搜索，该算法就会收敛到局部最优解。

#### 3.3.1 路径选择

路径选择组件对于算法的成功至关重要，因为错误的路径选择可能导致包含噪声特征并降低泛化能力。选择器在路径的 BM 频率列上操作，而不考虑 EBM 中与属性相关的列。选择过程正式描述如下：

给定：
- 一个包含来自当前迭代 \(t\) 的候选路径的集合 \(C_t \subset \mathbb{N}^m\)。
- 一个 BM 频率矩阵 \(B \in \mathbb{N}^{n \times |C_t|}\)，其中 \(B_{i, p}\) 表示路径 \(p\) 在图 \(G_i\) 中出现的频率。
- 负梯度向量 \(r \in \mathbb{R}^n\)。

选择器是一个函数 \(S: (B, r) \to C_t\)，它通过最大化 BM 列和负梯度之间的相关性（在均方误差意义上）来选择一个路径 \(p^* \in C_t\)：

\[
p^* = \arg\max_{p \in C_t} \text{Importance}(B_{\cdot, p}, r),
\]

其中 \(\text{Importance}\) 是一个度量，例如在用作选择器的决策桩中通过 `feature_importances_` 获得的值。所选路径 \(p^*\) 被添加到活动路径集中，并传递到拟合步骤。

该组件是算法的可自定义部分，作为 `SelectorClass` 暴露给用户。虽然默认选择器是一个深度为 1 的决策树（决策桩），但用户可以自定义选择器以满足特定需求。该设计选择是有意的：在拟合基学习器之前预选择路径显著减少了基学习器的输入维度，并保证了探索的标记路径保持良好的结构。通常，每轮只会选择一到两条路径，即使提供了带有多个属性的 EBM。

#### 3.3.2 路径特征

一旦一条路径被选择，由基学习器拟合的扩展特征矩阵包含以下特征：

- **BM 特征**: 所选路径 \(p_t\)（其本身及其所有前缀 \(q \preceq p_t\)）在 BM 中的频率。正式地，对于每条前缀路径 \(q\)，我们有一个特征 \(f_q(G_i) = B_{i, q}\)。
- **平均节点属性**: 沿路径 \(p_t\) 及其每个前缀的节点属性平均值，如第2.3节所定义。
- **平均边属性（如果存在）**: 沿路径 \(p_t\) 及其每个前缀的边属性平均值，如第2.3节所定义。

这些特征被堆叠到 EBM 列中，并且基学习器在这些列上进行拟合。这种结构使模型能够访问路径长度的层次结构：由于每个基学习器使用沿所选路径捕获的所有信息，因此它可以在统计上丰富的较长路径和统计上更稳健的较短前缀之间进行选择。

#### 3.3.3 并行训练：多锚点架构

多锚点架构同时训练多个独立的子模型，每个锚点标签对应一个子模型（第4.2节）。每个子模型共享相同的算法结构（BM、EBM、选择器、基学习器），但使用不同的起始锚点标签。训练可以顺序或跨核心分布进行（第4.7节）。这种并行化不会改变预测模型的结构，因为预测是通过汇总所有子模型的输出计算的（对于回归是求和，对于分类是平均对数几率）。形式上，令 \(A\) 为锚点标签集，令 \(F_{l_a}\) 为锚点标签 \(l_a \in A\) 对应的子模型。最终预测由下式给出：

\[
F(G) = \sum_{l_a \in A} F_{l_a}(G).
\]

这种分解提供了额外的可解释性：用户不仅可以检查哪些路径重要，还可以检查每个锚点标签对整体预测的相对贡献。

在 `SequentialPathBoost` 类（在后端使用）和 `PathBoost` 类（最终用户类）内部，每个锚点标签的训练按顺序执行，但 `PathBoost` 类通过将锚点标签分配给工作线程来支持跨锚点标签的实际并行化（第4.7节）。

##### 多锚点训练的动机

自动锚点选择（第3.3.1节）识别出图内具有分类属性多样性的节点。最终，每个唯一的锚点标签都会创建一个子模型。每个子模型可以发现以该特定标签开始的路径。这提供了几个实际优势：
- **提高覆盖范围**: 不同的锚点标签促使探索图的不同结构部分。
- **模块化**: 每个子模型是独立的，可以单独检查以进行解释。
- **并行能力**: 子模型的计算可以分布到多个核心。

### 3.4 变量重要性

该包提供两个变量重要性度量：绝对重要性和相对重要性。两种度量都在 `PathBoost` 和 `SequentialPathBoost` 类中实现。

令 \(T\) 为提升迭代次数，令 \(p_t\) 为第 \(t\) 次迭代选择的路径。令 \(f_t\) 为第 \(t\) 次迭代拟合的基学习器。对于回归，使用平方误差损失，\(f_t\) 的缩放因子 \(\rho_t\) 是步长（学习率）。对于分类，使用逻辑损失，缩放因子是在基学习器拟合期间计算并由步长加权的。

**绝对重要性**。每个基学习器在训练集上预测的方差被计算并归一化为1。这给出了每条路径 \(p_t\) 的绝对重要性分数 \(I_{\text{abs}}(p_t)\)：

\[
I_{\text{abs}}(p_t) = \frac{\text{Var}(f_t(G))}{\sum_{s=1}^T \text{Var}(f_s(G))}.
\]

归一化确保所有绝对重要性分数的总和为1。绝对重要性衡量每条路径对模型预测方差的贡献，独立于其他路径。

**相对重要性（相关性调整）**。由于路径是嵌套的（一条路径包含其前缀），绝对重要性可能会低估较长（嵌套）路径的贡献，因为它们与较短路径相关。为了解决这个问题，我们引入了一个相关性调整。令 \(C\) 为所有活动中路径的相关矩阵。调整后的重要性向量 \(v_{\text{adj}}\) 是 \(v_{\text{abs}}\) 和 \(C^{-1}\) 的乘积：

\[
v_{\text{adj}} = C^{-1} v_{\text{abs}}.
\]

调整在数学上确保路径没有共享的相关性，这反过来又使相对重要性排名与其嵌套结构解耦。在实践中，相关性调整防止了由共享方差引起的伪排名，突出了每条路径提供的独特信息。相关性调整仅在模型已完全训练且路径集稳定时计算。

**变量重要性属性**。在拟合后，变量重要性可以通过 `variable_importance_` 属性访问，该属性返回一个包含列 `Path`、`Absolute_Importance` 和 `Relative_Importance` 的 DataFrame（如果可用）。对于多锚点训练，还会包含一个 `Anchor_Label` 列。

## 4 软件设计与实现

### 4.1 包架构

`path_boost` 包围绕三个主要类构建：

- `PathBoost`：最终用户的主要类。它包装了一个或多个 `SequentialPathBoost` 实例（每个锚点标签一个），并处理跨锚点标签的并行化（使用多处理）。
- `SequentialPathBoost`：核心算法实现。它管理提升矩阵（BM，一个 `pd.DataFrame`）、扩展提升矩阵（EBM，一个更大的 `pd.DataFrame`，包含 BM 列加上沿所选路径及其前缀的平均节点和边属性）、选择器和基学习器。
- `SequentialPathBoostClassifier`：`SequentialPathBoost` 的变体，用于二分类。它使用逻辑损失而不是平方误差损失，并使用一个专门的基学习器（通过 `use_tree_boost` 标志）来优化逐叶值的逻辑损失。

**设计原则**。包的设计遵循 `scikit-learn` 约定：实现一个通用的 `fit(X, y)` 方法，支持 `predict()`，并暴露 `get_params()` 和 `set_params()` 以便与 `GridSearchCV` 兼容。图表示为 `networkx.Graph` 对象，具有预定义的节点和边属性命名约定。

**数据类型**。所有 EBM 列都是 `np.float64` 类型的。NaN 用于指示路径缺失。所有节点和边属性都被转换为 `np.float64`。

### 4.2 锚点选择

锚点节点是路径探索的起点。该包支持两种锚点选择模式：

- **显式锚点选择**: 用户在图中指定一个节点作为锚点，通常通过一个特定的节点属性（例如，过渡金属原子）来标识。
- **自动锚点选择**: 该包通过 `auto_anchor_label` 参数自动确定锚点标签。它选择具有最高分类属性多样性的节点标签，由熵或类别计数度量，如第3.3.1节所述。

对于多锚点训练，自动锚点选择选择所有标签，为每个标签创建一个子模型。

### 4.3 扩展提升矩阵的列命名约定

`train_ebm_dataframe_` 属性包含拟合后所有 EBM 列的可读列名，这对于理解和解释模型非常有价值。列名的模式是 `(<path_representation>, <attribute>)`，其中 `<path_representation>` 是路径标记的元组，`<attribute>` 是属性名称。例如：

```python
# 训练模型后示例列名
>>> print(model.train_ebm_dataframe_.columns[:5])
Index(['(25,)_n_times_present', '(25,)_atomic_number',
       '(25,)_n_hydrogens', '(25,7)_n_times_present',
       '(25,7)_bond_strength'], dtype='object')
```

### 4.4 路径长度与特征空间增长

对训练成本影响最大的参数是 `max_path_length`。可发现的独特标记路径的数量随路径长度和节点标签的多样性呈组合增长：在每一步，路径可能分支成与不同相邻标签一样多的扩展，因此候选路径空间大致随 `max_path_length` 和标签集的分支因子呈指数增长。由于每条发现的路径都会对扩展提升矩阵（EBM）贡献若干列（路径及其前缀的每个节点和边属性各一列），因此 EBM 的宽度，以及构建和拟合它所需的内存和时间，会随着训练过程中实际实现的路径数量而缩放。

两种机制使这种增长可控。首先，路径是*惰性*扩展的：提升矩阵仅在选择路径时才会扩展，因此实际特征空间远小于完整的组合枚举，并且集中在结构上有信息的路径上（第3.1节）。其次，`max_path_length` 直接限制了探索深度。训练后可以通过 `train_ebm_dataframe_` 属性（第4.3节）检查实际的 EBM，这对于诊断在给定数据集上实际特征空间变得有多大非常有用。在实践中，我们建议将 `max_path_length` 作为主要超参数，并通过交叉验证进行调优，从小值（例如 3–4）开始，直到验证误差停止改善。较短的路径可能会错过长距离结构信号，而过长的路径会膨胀 EBM，增加训练时间和内存，并添加许多弱信息特征，增加过拟合风险。适当的值取决于数据集：具有多样节点标签（例如涵盖许多化学元素的分子数据集）的图比只有少数不同标签的图分支更快，并且在较小的路径长度下就能达到较大的 EBM。

### 4.5 选择器

回归和分类的默认选择器是 `sklearn.tree.DecisionTreeRegressor`，其中 `max_depth=1`（决策桩），通过 `SelectorClass` 构造参数传递。选择器的唯一目的是路径选择：在每个提升迭代中，它识别 BM 中哪个候选路径与当前负梯度最相关。具体来说，它是在 BM 的仅频率列上拟合的（每列对应一条已知路径，记录该路径在每个图中出现的次数），并且选择对应于 `feature_importances_` 中最高条目的路径。选择器在预测期间永远不会被调用。这种设计是有意的：让选择器专注于结构频率计数而不是属性值，可以使路径选择快速且对过拟合具有鲁棒性，如第3.1节所述。

##### 自定义选择器。

选择器接口通过 `SelectorClassInterface` 进行鸭子类型化：不需要显式继承，任何实现预期方法的类都会自动被识别为兼容的。自定义选择器必须实现 `fit(X, y)`、`predict(X)`（接口需要，但在训练期间从未调用），并在拟合后暴露一个 `feature_importances_` 属性，即一个非负分数数组，每个对应 `X` 的一列。只有分数的顺序重要，而不是它们的尺度。原则上，任何暴露 `feature_importances_` 的 `scikit-learn` 估计器都可以直接用作选择器。

### 4.6 可用的基学习器

`SequentialPathBoost` 和 `PathBoost`（见第3.3.3节）的默认基学习器是 `sklearn.tree.DecisionTreeRegressor`，其中 `max_depth=3`，通过 `BaseLearnerClass` 构造参数传递。浅层决策树可以原生处理 NaN 值，当图中不存在路径时，EBM 中会出现 NaN 值，并且它们非常适合基学习器在每次迭代中接收的少量列（通常为 3–10 列），这些列对应于所选路径及其前缀的 EBM 特征。

##### 自定义基学习器。

与选择器一样，基学习器使用鸭子类型接口，在 `BaseLearnerClassInterface` 中定义：不需要显式继承，任何实现 `fit(X, y)` 和 `predict(X)` 的类都会自动被识别为兼容的。`X` 参数始终是一个 `pd.DataFrame`，仅包含当前所选路径的 EBM 列；它并不是完整的特征矩阵。任何具有 `fit` 和 `predict` 的 `scikit-learn` 估计器（例如，`LinearRegression`、`XGBRegressor`）都可以直接工作，无需修改。表1 (https://arxiv.org/html/2607.07935#S4.T1) 总结了已测试与包兼容的基学习器。

表1: 基学习器兼容性。已测试的学习器已在包的测试套件中验证。

| 库 | 类 | 备注 |
|---|---|---|
| scikit-learn | DecisionTreeRegressor | 默认 (max_depth=3) |
| scikit-learn | LinearRegression | 需要 replace_nan_with |
| XGBoost | XGBRegressor | 也可用作选择器 |
| scikit-learn | Ridge, Lasso, ElasticNet | 需要 replace_nan_with |
| scikit-learn | Pipeline(SplineTransformer, Ridge) | 需要 replace_nan_with; 平滑目标 |
| scikit-learn | SVR | 不能用作选择器 |

##### NaN 处理。

默认情况下，当路径在图中不存在时，EBM 条目为 `np.nan`。基于树的模型可以原生处理此问题。线性模型则不行：在使用 `LinearRegression`、`Ridge` 或类似模型时，必须将 `replace_nan_with` 参数设置为一个数值：

```python
path_boost = PathBoost(
    BaseLearnerClass=LinearRegression,
    replace_nan_with=0,
    ...
)
```

替换值的选择很重要：`0` 是中性的默认值，而像 `-100` 这样的大负值会向模型明确指示路径缺失。对于大多数用例，`0` 是更安全的选择，除非需要将缺失路径与具有真实零属性值的路径区分开。

##### 分类变体。

`SequentialPathBoostClassifier` 类通过 `use_tree_boost` 标志提供了一个额外选项，它激活一个内部基学习器，该学习器通过直接最小化逻辑损失来优化逐叶值，遵循 [friedman2001greedy] 的方法：

```python
from path_boost import SequentialPathBoostClassifier
model = SequentialPathBoostClassifier(
    use_tree_boost=True,
    ...
)
```

当 `use_tree_boost=True` 时，`BaseLearnerClass` 参数被忽略。

### 4.7 并行化

`PathBoost` 类通过设置 `n_of_cores > 1` 来支持跨锚点标签的并行训练。线程限制在模块加载时配置，以防止过度订阅。为了跨平台兼容性，主脚本应使用以下包装：

```python
if __name__ == "__main__":
    path_boost = PathBoost(n_of_cores=4)
    path_boost.fit(X, y, ...)
```

### 4.8 模型持久化

训练好的模型可以保存和加载以实现可重复性：

```python
>>> path_boost.save('trained_model.joblib')
>>> from path_boost import PathBoost
>>> loaded_model = PathBoost.load('trained_model.joblib')
>>> predictions = loaded_model.predict(X_test)
```

### 4.