# 00_README —— 第一性原理文档包入口

> 本文件是 `docs_first_principles/` 文档包的总入口与导航地图。所有数字与 `docs_first_principles/_fact_sheet.md`(权威事实表,状态日期 2026-06-18)保持一致;叙述性结论若与事实表冲突,以事实表为准。

---

## 1. 这个文档包解决什么问题

`code/` 下有 30+ 个 Python 脚本,它们通过运行时 `importlib` 互相加载、共享约定(如 `--split-seed 202`、`rank cutoff`)而非显式接口,新读者很难从单点切入。`reports/` 里的报告则偏向"结果叙事",对"为什么这样设计、为什么这个数字可信"讲得不够。

本文档包用**第一性原理**的方式,把整套方法拆成可独立理解的小单元,每篇文档回答一个"为什么":

- 任务怎么定义、数据集有多稀疏?(01)
- 整体两阶段架构长什么样?(02)
- 数据从 txt 怎么流到 submission、中间产物怎么读?(03)
- LightGCN 为什么"轻"、为什么用 BPR + 硬负采样、为什么是主分数?(04)
- 为什么单一 LightGCN 分数不够、要手工图特征 + LightGBM 堆叠?(05)
- 随机游走(DeepWalk/Node2Vec)补的是什么尺度信息?(06)
- 高阶有向引用传播为什么是最终核心增益?(07)
- 为什么验证最优阈值不能搬到测试、要用 rank cutoff?(08)
- 方法是怎么一步步演进到 0.966 的?(09)
- 30+ 脚本怎么导航、入口在哪?(10)
- 实验结果对应论文哪些图表?(11)
- 怎么复现?(12)
- 答辩/审稿会被问什么?(13)
- 哪些可直接写进 ACM 中文论文?(SUMMARY)

目标读者:**懂一点 ML、但不完全熟悉图推荐系统**的人。每篇先讲"为什么",再给"是什么",最后给代码定位与可迁移表述。

---

## 2. 本项目一句话概括

> CS3319 Project 2 —— 在异构学术网络(6,611 作者 / 79,937 论文;author↔paper 二部、author↔author 合著、paper→paper 引用三类边)上的 author-paper **阅读推荐(二部图链路预测)**,对 ~2.05M(2,047,262)测试对输出 0/1,公开榜仅评 50% 测试集,评估指标为 **F1**。

## 3. 最终方法一句话概括

> **两阶段 stacking**:Stage-1 由 LightGCN 集成、BPR-MF、DeepWalk/Node2Vec(7 块)、内容画像、显式图/meta-path、**高阶引用传播** 等多源生产 raw 分数与嵌入;Stage-2 由 **259 维 LightGBM 二级 meta-learner** 融合,测试决策用 **rank-cutoff top 50% + 强制训练已知正边为 1**。

## 4. 最终公开 F1 与最重要技术点

- **最终公开 LB F1 = 0.96626**,提交文件
  `validation_runs/dynamic_seed202/high_order_graph_stack/submissions/submission_rich_rw7_highorder_directed_r0.500000.csv`(对应验证 1:1 OOF F1 = 0.966874,AUC = 0.994918)。
- **最关键技术点 —— 高阶有向引用传播**:作者历史论文经 k 步引用扩散到候选 $H_k = R\cdot C^k$,合著者历史论文扩散到候选 $G_k = S\cdot R\cdot C^k$,分别取 forward / backward / undirected 三向。其中 $S$=合著邻接、$R$=作者-论文邻接、$C$=引用邻接。实现见 `code/high_order_graph_stack.py` 的 `build_high_order*`。在 7-RW 集成(0.9649)之上叠加它,验证 F1 0.9649 → 0.9669、公开 F1 0.96252 → 0.96626,是最终阶段的核心增益来源。

---

## 5. 推荐阅读顺序

文档不是平的,有依赖关系。建议按下方链顺序读,每篇都为下一篇铺垫概念:

```
01 (任务定义 / 数据集规模与难度)
  └─► 02 (两阶段 stacking 架构总览)        ← 先有全局图,再钻细节
        └─► 03 (数据流与产物:txt → .npy → submission,怎么读中间文件)
              └─► 04 (LightGCN 第一性原理:主分数生产者)
                    └─► 05 (手工图特征 + LightGBM 二阶段堆叠:为何单分数不够)
                          ├─► 06 (随机游走 DeepWalk/Node2Vec:全局接近度)
                          └─► 07 (高阶有向引用传播:最终核心增益)
                                └─► 08 (校准与 rank cutoff:为何验证阈值不能搬测试)
                                      └─► 09 (实验演进时间线:0.885 → 0.966 怎么来的)
                                            ├─► 10 (代码地图与入口脚本)
                                            ├─► 11 (图表与论文章节映射)
                                            └─► 12 (复现指南)
                                                  └─► 13 (答辩 / 审稿常见问题)
                                                        └─► SUMMARY (论文级总览 + 可迁移 TeX)
```

简化为单链:**01 → 02 → 03 → 04 → 05 → 06 → 07 → 08 → 09 → 10 → 11 → 12 → 13 → SUMMARY**。

理由:01 给任务与数据;02 给两阶段架构全局;03 给数据/产物的工程机制(读后续文档前先懂"分数文件怎么对齐");04 是主分数来源;05 解释为何单一分数不够、要堆叠;06/07 是 Stage-1 两个互补特征源(游走全局接近度 / 高阶引用传播);08 解释测试决策的特殊设计(rank cutoff);09 把全流程串成结果时间线;10/11/12 是工程导航、图表映射与复现;13 是答辩问答;SUMMARY 是可迁移论文产出。

> `docs_first_principles/_fact_sheet.md`(权威事实表)是全部文档的数字真相源,不进论文正文,但写任何文档前应先查它。

---

## 6. 每篇文档一句话用途

| 文档 | 文件名 | 一句话用途 |
|---|---|---|
| **00** | `00_README.md` | 本文件:文档包入口、导航与全局数字索引。 |
| **01** | `01_problem_and_dataset.md` | 任务定义与数据集:异构图三类边、规模、F1 评测、稀疏/长尾难度。 |
| **02** | `02_architecture_overview.md` | 两阶段 stacking 架构总览:Stage-1 多源 + Stage-2 LightGBM + rank-cutoff。 |
| **03** | `03_data_flow_and_artifacts.md` | 数据流与产物:txt → 切分 → `.npy` 分数 → OOF → submission,文件名约定与缓存。 |
| **04** | `04_lightgcn_from_first_principles.md` | LightGCN 第一性原理:为何"轻"、BPR + 硬负采样、点积解码、主分数生产者。 |
| **05** | `05_feature_stacking_and_lightgbm.md` | 手工图/meta-path 特征 + LightGBM 二阶段融合:为何 stacking 是单阶段最大增益(+0.0174)。 |
| **06** | `06_random_walk_features.md` | 随机游走(DeepWalk / Node2Vec,7 块):补全局接近度信息。 |
| **07** | `07_high_order_citation_propagation.md` | 高阶引用传播:$H_k=R\cdot C^k$ / $G_k=S\cdot R\cdot C^k$,fwd/bwd/undir,最终核心增益。 |
| **08** | `08_calibration_and_rank_cutoff.md` | 校准与 rank cutoff:验证 1:1 → 测试分布漂移(阈值 0.4617 vs 迁移漂移 0.5242)。 |
| **09** | `09_experiment_timeline.md` | 实验演进时间线:baseline 0.8850 → 最终 0.9669 / 0.96626 的结果表与三段跃迁解读。 |
| **10** | `10_code_map_and_entrypoints.md` | 代码地图与入口:30+ 脚本分类、两大共享库、legacy、三条核心命令。 |
| **11** | `11_figures_and_paper_mapping.md` | 图表与论文章节映射:11 张图 caption + 与正文小节的对应。 |
| **12** | `12_reproduction_guide.md` | 复现指南:环境、最短/从零路径、快速验证、常见坑。 |
| **13** | `13_common_questions_for_the_author.md` | 答辩 / 审稿视角常见问题与回答(Q1–Qn)。 |
| **SUMMARY** | `SUMMARY_FOR_PAPER.md` | 论文级总览:可直接进 TeX 的正式表述 + 图表素材清单。 |
| — | `_fact_sheet.md` | 权威事实表(数字真相源,内部参考,不直接进正文)。 |

---

## 7. 哪些内容适合直接进论文(简版,详见 SUMMARY)

- **方法演进表**:验证 F1(1:1 OOF,seed=202)baseline 0.8850 → 0.9386(LightGCN)→ 0.9560(meta-path stacking)→ 0.95711(Post95 变体)→ 0.95763(content mean-cos)→ 0.95931(BPR-MF)→ 0.95990(rich content)→ 0.9621(DeepWalk/Node2Vec)→ 0.9649(7-RW)→ **0.9669(高阶有向)**;公开 F1 链 0.93044 → 0.95760 → 0.95996 → 0.96252 → **0.96626**。
- **259 维特征构成表**:细分 12 项(rich rank4 / explicit18 / neg8 / topk3 / variant43 / content_mean4 / bpr4 / rich18 / 7×RW77 / RW-agg11 / 高阶无向24 / 高阶有向45),论文常按 10 大族归并。详见 `SUMMARY_FOR_PAPER.md` §6 与 `_fact_sheet.md` §2.5。
- **高阶传播公式与消融**:$H_k=R\cdot C^k$、$G_k=S\cdot R\cdot C^k$;108→190→214→259 维消融,验证 F1 0.964270 → 0.964947 → 0.966556 → 0.966874(无向高阶 +0.001609,有向高阶再 +0.000318)。
- **决策规则**:rank cutoff top 50% + `test_known_mask.npy` 强制已知正边,及其与验证最优概率阈值(0.4617)的对比论证。
- **数据集难度**:二部密度 ≈ 1.29e-3、56% 作者度=1、三类异构边规模。

## 8. 哪些是帮助理解代码的(不进论文)

- **代码定位表**:脚本↔函数↔行号(见 `_fact_sheet.md` 第 6 节,如 `train_val_lgcn_ensemble.py:132-165` 切分、`high_order_graph_stack.py` 的 `build_high_order*`);系统级导航见 `10_code_map_and_entrypoints.md`。
- **运行时加载机制**:无 `utils.py`,`load_module()` 用 `importlib.util` 把同目录脚本当库加载,`train_val_lgcn_ensemble.py` 与 `stack_rank_calibration.py` 是两大事实共享库。
- **缓存约定**:`.npy`(分数,`val_*`/`test_*`)、`.npz`(RW pair 特征)、`feature_cache/` 的 cache-or-compute 文件名约定;详见 `03_data_flow_and_artifacts.md`。
- **`--split-seed` 负载**:切分种子 baked 进每个分数文件,换 seed 必须端到端重跑。
- **不一致台账**:见 `_fact_sheet.md` 第 5 节(如列名 `Index,Predicted` vs "Id and Probability"、F1 系数、sparse-matrix 归属等),写论文时务必避开被裁决为"残留措辞/笔误"的版本。

---

## 9. 全部文档总表

| 文件名 | 用途(一句话) | 面向谁 | 可直接进论文 |
|---|---|---|---|
| `00_README.md` | 文档包入口、导航、全局数字索引 | 所有人(先读) | 部分(数据集/方法一句话) |
| `01_problem_and_dataset.md` | 任务定义与数据集规模/难度 | 想了解任务背景者 | 是(Introduction/数据集节) |
| `02_architecture_overview.md` | 两阶段 stacking 架构总览 | 理解整体方法者 | 是(方法架构图说明) |
| `03_data_flow_and_artifacts.md` | 数据流与产物文件机制 | 理解中间产物/复现者 | 是(实验设置节) |
| `04_lightgcn_from_first_principles.md` | LightGCN 第一性原理(主分数) | 想懂主模型者 | 是(方法核心节) |
| `05_feature_stacking_and_lightgbm.md` | 手工图特征 + LightGBM 堆叠 | 理解两阶段融合者 | 是(方法/特征工程节) |
| `06_random_walk_features.md` | DeepWalk/Node2Vec(7 块) | 理解游走特征者 | 是(特征工程节) |
| `07_high_order_citation_propagation.md` | 高阶引用传播(核心增益) | 想懂最终贡献者 | 是(方法/贡献亮点) |
| `08_calibration_and_rank_cutoff.md` | 校准与 rank cutoff 决策动机 | 理解决策设计者 | 是(分析/讨论节) |
| `09_experiment_timeline.md` | 实验演进时间线与结果表 | 拿结果数据/讲故事者 | 是(实验/结果节) |
| `10_code_map_and_entrypoints.md` | 代码地图与入口脚本 | 导航 code/ 者 | 部分(实现概述节) |
| `11_figures_and_paper_mapping.md` | 图表与论文章节映射 | 整理图表者 | 是(caption + 映射) |
| `12_reproduction_guide.md` | 复现指南 | 复现者 | 部分(复现节) |
| `13_common_questions_for_the_author.md` | 答辩/审稿常见问题 | 答辩准备者 | 部分(讨论/局限节) |
| `SUMMARY_FOR_PAPER.md` | 论文级总览 + 可迁移 TeX 表述 | 论文写作者 | 是(整篇均可) |
| `_fact_sheet.md` | 权威事实表(数字真相源) | 全部文档作者 | 否(内部参考,不直接进正文) |

---

## 可迁移到论文中的写法

下面给出可直接进 TeX 的正式表述(中文,保留英文术语):

> **任务定义(Introduction 节草稿)**
> 本文研究异构学术网络上的 author-paper 阅读推荐,形式化为二部图链路预测问题。网络包含 6,611 名作者与 79,937 篇论文,以及三类边:author↔paper 二部边(共 682,421 条)、author↔author 无向合著边(9,663 条)、paper→paper 有向引用边(327,113 条)。给定 2,047,262 个待预测 author-paper 对,任务为对每对输出 0/1,以 F1 为评估指标(公开榜仅评测 50% 测试集)。该图二部正边密度仅约 $1.29\times10^{-3}$,且约 56% 的作者度数为 1,呈现显著的稀疏与长尾特性。

> **方法概述(Method 节草稿)**
> 我们提出两阶段 stacking 架构。Stage-1 由多个互补模型生产原始分数与嵌入,包括异构协同过滤(LightGCN 集成)、矩阵分解(BPR-MF)、随机游走表示(7 个 DeepWalk/Node2Vec 块)、内容语义画像(基于 512 维 Universal Sentence Encoder 嵌入)以及高阶引用传播特征。Stage-2 由一个 259 维特征上的 LightGBM 二级 meta-learner 进行融合。核心贡献是高阶有向引用传播:令 $R$ 为作者-论文邻接、$S$ 为合著邻接、$C$ 为引用邻接,则 $H_k=R\cdot C^k$ 将作者历史论文经 $k$ 步引用扩散到候选,$G_k=S\cdot R\cdot C^k$ 进一步纳入合著者历史论文,并分别计算 forward、backward、undirected 三向得分。

> **决策规则(Experiment 节草稿)**
> 由于验证集为人工 1:1 正负采样,LightGBM 输出概率在验证→测试分布漂移下无法直接迁移(验证最优阈值 0.4617,迁移到测试后正例率漂移至约 0.5242),因此测试阶段采用 rank cutoff 决策:按最终分数对测试对排序,预测 top 50% 为正,并强制出现在训练正边中的测试对为正。该方法在公开榜取得 F1 = 0.96626。