File size: 24,725 Bytes

f28d994

# CS3319 推荐系统代码库 — 权威事实表 (fact_sheet)

> 本表是后续 15 篇文档的**唯一共同真相来源**。所有数字均带来源;冲突项已在「不一致台账」中裁决;无法核验者标注"未明确确认"。维护规则:有更高优先级来源时,以更可信来源覆盖次要来源。
> 状态日期: 2026-06-18。优先级: 已核验种子事实 > 代码/CSV 实测 > README/CLAUDE.md > reports 叙述。

---

## 1. 一句话总览

- **项目一句话**: CS3319 Project 2 —— 在异构学术网络(6,611 作者 / 79,937 论文;author↔paper 二部 / author↔author 合著 / paper→paper 引用三类边)上的 author-paper **阅读推荐(二部图链路预测)**,对 ~2.05M 测试对输出 0/1,评估指标为 F1(公开榜仅评 50% 测试集)。
- **最终方法一句话**: 两阶段 stacking —— Stage-1 由 LightGCN 集成、BPR-MF、DeepWalk/Node2Vec(7 块)、内容画像、显式图/meta-path、**高阶引用传播** 等多源生产 raw 分数/嵌入;Stage-2 由 **259 维 LightGBM 二级 meta-learner** 融合,测试决策用 **rank-cutoff top 50% + 强制训练已知正边为 1**。
- **最终公开 F1**: **0.96626**(`submission_rich_rw7_highorder_directed_r0.500000.csv`)。
- **最关键技术点**: 高阶有向引用传播 `H_k = R·C^k`(作者历史论文经 k 步引用扩散到候选)、`G_k = S·R·C^k`(合著者历史论文扩散到候选),fwd/bwd/undir 三向,在 LightGCN 上叠加把验证 F1 从 0.9649 → 0.9669、公开 F1 0.96252 → 0.96626。

---

## 2. 权威数字表

### 2.1 图与数据集规模(实测 `wc -l`)

| 指标 | 值 | 来源 | 可信度 |
|---|---|---|---|
| author 节点数 | 6,611 (id 0–6610) | dataset.md L16; project_description.md L7 | 高 |
| paper 节点数 | 79,937 (id 0–79936) | dataset.md L21; project_description.md L7 | 高 |
| bipartite_train_ann.txt 行数(训练正边) | **682,421** | 实测 wc -l | 高 |
| bipartite_test_ann.txt 行数(待预测对) | **2,047,262** (≈2.05M) | 实测 wc -l; CLAUDE.md "~2.05M" | 高 |
| author_file_ann.txt 行数(合著,无向) | **9,663** | 实测 wc -l | 高 |
| paper_file_ann.txt 行数(引用,有向 former→latter) | **327,113** | 实测 wc -l | 高 |
| feature.pkl shape / dtype | (79,937, 512) torch.float32 | pickle.load 实测; dataset.md L26 | 高 |
| feature.pkl 文件大小 | 163,711,392 字节(~156 MB) | ls -lh 实测 | 高 |
| 二部图正边密度 | 682421/(6611×79937=528,184,207) ≈ **1.29e-3** | 计算 | 高 |
| 56% 作者度=1 | 0.56 | 已核验种子事实(长尾稀疏) | 中(无本审计原始核验) |
| 公开榜评分占比 | 测试集的 50% | project_evaluation.md L5 | 高 |

### 2.2 验证切分(dynamic_seed202)

| 指标 | 值 | 来源 |
|---|---|---|
| 切分函数 | `make_notebook_style_split(root, seed=202, train_frac=0.9)` | train_val_lgcn_ensemble.py L132-165 |
| 验证正例 | 68,242(留出 10% 训练正边,= round(682421×0.1)) | 代码复算 |
| 验证负例 | 68,242(np.random.default_rng(202) 等量随机非边) | 代码复算 |
| 验证集对数 | **136,484**(人工 1:1) | val_labels_seed202.npy 实测 |
| val_pairs/label 文件 | `validation_runs/dynamic_seed202/val_pairs_seed202.npy`, `val_labels_seed202.npy` | 实测存在 |

### 2.3 方法演进(验证 F1, 同 seed=202 1:1 OOF) + 公开 LB F1

| 阶段 | 验证 F1 (1:1 OOF) | 公开 LB F1 | 主要来源 |
|---|---|---|---|
| baseline | 0.8850 | — | 已核验种子事实 |
| LightGCN 集成 (dyn202_l2d512_bpr_bigbatch_more) | 0.9386 (0.93857648) | 0.93044(早期 6-model sub_ens6_t0.36) | dynamic_summary.csv L2; README L42 |
| + 显式图 / meta-path stacking | 0.9560 (0.955992) | — | exploration_summary.md L113 |
| Post95 stacker(76 维,变体特征) | 0.95711 | ≈0.95760 | extra_score_ablation.csv L5; README L43 |
| + Content mean-cos | 0.95763 (+0.000519) | — | extra_score_ablation.csv L4 |
| + BPR-MF(84 维 X_base) | 0.9593 (0.95931) | ≈0.95996 | extra_score_ablation.csv L2; README L44 |
| + rich content(102 维) | 0.95990 | — | content_rich_ablation.csv L2 |
| + DeepWalk / Node2Vec | 0.9621 | ≈0.96252 | README L45 |
| + 7 RW blocks ensemble | 0.9649 (0.964921) | — | ensemble_7_ablation.csv L2 |
| + 高阶引用传播(有向) | **0.9669 (0.966873736337297)** | **0.96626** | validation_summary.csv L2; README L11 |

> 注: 公开 LB F1 链 0.93044 → 0.95760 → 0.95996 → 0.96252 → **0.96626**。各阶段公开 F1 来自不同提交 CSV;验证 F1 为同一 seed=202 切分下的 1:1 leak-free OOF。

### 2.4 高阶消融(high_order_graph_stack/validation_summary.csv,实测 4 行)

| stage | n_features | validation F1 | AUC | threshold |
|---|---|---|---|---|
| base_highorder | 108 | 0.964270 | 0.994052 | 0.455478 |
| rich_rw7 | 190 | 0.964947 | 0.994555 | 0.490447 |
| rich_rw7_highorder(+undirected) | 214 | 0.966556 | 0.994890 | 0.469339 |
| **rich_rw7_highorder_directed(+directed)** | **259** | **0.966874** | **0.994918** | **0.461731** |

> 注: 种子事实写"base_highorder 0.96427 / 0.99405",实测 CSV 值一致。

### 2.5 259 维特征构成

| 特征族 | 维度 | 产出脚本 / 函数 |
|---|---|---|
| rich rank4 = add_rank_features(score, global_rank, author_pct, author_rank) | 4 | stack_rank_calibration.py L148-160 |
| explicit18 = ExplicitGraphFeatures.transform(显式图/meta-path) | 18 | stack_rank_calibration.py L108-145 |
| neg8 = negative_evidence_features | 8 | post95_ablation.py L176-192 |
| topk3 = topk_content_similarity_fast(max, top-3, top-5) | 3 | generate_post95_submission.py L186-216 |
| variant43 = variant_feature_matrix(20 变体×(zscore+rank01)=40 + 3 聚合) | 43 | generate_post95_submission.py L175-183 |
| content_mean4 = score_to_features(content_mean_cos) | 4 | extra_score_sources_ablation.py L80-97 |
| bpr4 = score_to_features(mf_bpr, dim256) | 4 | extra_score_sources_ablation.py L100-163 |
| **X_base 小计** | **84** | (=4+18+8+3+43+4+4) |
| rich18 = content_rich_features(从 feature.pkl) | 18 | content_rich_ablation.py L54-129 |
| 7×RW block(pair_feature_block,每块 11) | 77 | randomwalk_systematic_ablation.py L216-270 |
| RW aggregate(一致性聚合) | 11 | generate_randomwalk_ensemble_submission.py L50-69 |
| high-order undirected | 24 | high_order_graph_stack.py build_high_order* |
| high-order directed | 45 | high_order_graph_stack.py build_high_order* |
| **合计** | **259** | validation_summary.csv L2 n_features=259 |

> 拼接顺序核对: 84(rich X_base) + 18(rich content) = 102(content_mf_baseline);102 + 77(7RW) + 11(RW agg) = 190(rich_rw7); +24(undir) = 214; +45(dir) = **259**(rich_rw7_highorder_directed)。

### 2.6 概率阈值与正例率 / 决策规则

| 指标 | 值 | 来源 |
|---|---|---|
| 验证最优概率阈值(seed=202, 259 维) | **0.46173080801963806** | validation_summary.csv L2 |
| 阈值 seed 间波动范围 | 0.4435 – 0.4857 | 已核验种子事实 |
| test 概率阈值迁移正例率漂移 | 0.5242(迁移到 test 后漂移) | 已核验种子事实 |
| 最终决策 rank cutoff | **top 50% (ratio 0.500000)** | submission_summary.csv; README L11 |
| 强制 known positives | test_known_mask.npy(force=1) | cached_scores/test_known_mask.npy(实测存在, 2,047,390 字节) |
| LightGBM OOF 折数 | 5 折 StratifiedKFold | stack_rank_calibration.py L165 |

### 2.7 LightGBM 最终超参(high_order_graph_stack fit_full_predict)

| 超参 | 值 |
|---|---|
| num_leaves | 15 |
| reg_lambda | 8.0 |
| min_child_samples | 100 |
| n_estimators | 1400 |
| learning_rate | 0.022 |
| 评估 | 5-fold StratifiedKFold OOF |

来源: 已核验种子事实。

### 2.8 标签对齐复算(已验证)

`val_labels_seed202.npy`(136,484)对 `rich_rw7_highorder_directed_oof.npy` 的 best F1 = **0.966874** / AUC **0.994918** —— 与 validation_summary.csv L2 完全一致(val-label ↔ OOF 已对齐,无泄漏)。

---

## 3. 方法演进时间线表

| 序 | 方法 | 关键产物 | 验证 F1 | 公开 F1 | 阶段意义 |
|---|---|---|---|---|---|
| 0 | baseline(启发式/度特征) | — | 0.8850 | — | 起点 |
| 1 | LightGCN 异构 CF 集成 | `dyn202_l2d512_bpr_bigbatch_more` 主分数 | 0.9386 | 0.93044(6-model) | 端到端图嵌入主分数生产者 |
| 2 | + 显式图 / meta-path(A-A-P, A-P-P, A-P-A-P)stacker | stack_rank_calibration.py | 0.9560 | — | 突破 0.95, 单一最大增益(+0.0174) |
| 3 | Post95 变体特征 stacker(76 维) | post95_submission | 0.95711 | ≈0.95760 | LightGCN 多变体聚合 |
| 4 | + Content mean-cos | extra_score_sources | 0.95763 | — | 内容语义 |
| 5 | + BPR-MF(84 维 X_base) | extra_bprmf_submission | 0.95931 | ≈0.95996 | 矩阵分解互补 CF |
| 6 | + rich content(18 维, feature.pkl) | content_rich | 0.95990 | — | 深度内容画像 |
| 7 | + DeepWalk / Node2Vec | node2vec_deepwalk_submission | 0.9621 | ≈0.96252 | 游走全局接近度 |
| 8 | + 7 RW blocks 一致性聚合 | randomwalk_systematic | 0.964921 | — | 多样性游走 |
| 9 | + 高阶引用传播(undirected→directed,259 维) | **high_order_graph_stack** | **0.966874** | **0.96626** | 最终方法 |

---

## 4. 文件流文本图

```
原始输入 (data_and_docs/)
  ├─ bipartite_train_ann.txt  (682,421 行 author→paper 正边)
  ├─ bipartite_test_ann.txt   (2,047,262 行 待预测对)
  ├─ author_file_ann.txt      (9,663 行 author↔author 无向合著)
  ├─ paper_file_ann.txt       (327,113 行 paper→paper 有向引用)
  └─ feature.pkl              (79,937×512 USE 论文嵌入, torch.float32)
        │
        ▼  make_notebook_style_split(seed=202, train_frac=0.9)
切分 (validation_runs/dynamic_seed202/)
  ├─ val_pairs_seed202.npy    (136,484 对)
  └─ val_labels_seed202.npy   (1:1 正负)
        │
        ├──── Stage-1 分数/特征生产者 (各自独立)
        │   ├─ train_val_lgcn_ensemble.py  → scores/val_vanilla_ensemble_mean.npy  (LightGCN 主分数)
        │   ├─ extra_score_sources_ablation.py → val_mf_bpr_s202_d256.npy, content_mean (BPR-MF / content_mean_cos)
        │   ├─ content_rich_ablation.py → content_rich_*.npy (18 维 rich, feature_cache)
        │   ├─ randomwalk_systematic_ablation.py → 7× Word2Vec .model + pair_features/*.npz (11 维/块)
        │   ├─ generate_randomwalk_ensemble_submission.py (aggregate) → RW 一致性 11 维
        │   ├─ generate_post95_submission.py → variant43 (20 变体选择), topk3
        │   ├─ stack_rank_calibration.py → explicit18 + rank4
        │   └─ high_order_graph_stack.py (build_high_order*) → undir24 + directed45 (H_k=R·C^k, G_k=S·R·C^k)
        │
        ▼  拼接 259 维 X
Stage-2 stacker (high_order_graph_stack.py)
  └─ fit_full_predict: LightGBM(num_leaves=15, reg_lambda=8, lr=0.022, n_est=1400) 5-fold OOF
        ├─ rich_rw7_highorder_directed_oof.npy        (验证 OOF, F1=0.966874)
        └─ rich_rw7_highorder_directed_test_pred.npy  (测试预测分)
        │
        ▼  决策
最终 submission (validation_runs/dynamic_seed202/high_order_graph_stack/submissions/)
  └─ submission_rich_rw7_highorder_directed_r0.500000.csv
       = sort test by score → top 50% = 1
       + cached_scores/test_known_mask.npy 强制已知训练正边 = 1
       → 公开 LB F1 = 0.96626
```

---

## 5. 不一致台账(全部审计 inconsistencies 汇总 + 裁决)

| # | 主题 | A 方 | B 方 | 裁决(可信来源) |
|---|---|---|---|---|
| 1 | 提交 CSV 表头列名 | project_evaluation.md L8 "Id and Probability" | project_evaluation.md L12 / dataset.md "Index,Predicted" | **以 `Index,Predicted` 为准**(dataset.md + CLAUDE.md + 实际提交一致用 0/1);"Id and Probability" 为残留措辞。可信度: dataset.md > evaluation 残句。 |
| 2 | F1 公式系数 | project_evaluation.md L3 F(f)=P·R/(P+R)(缺因子 2) | 标准 F1=2PR/(P+R) | **以标准 F1 为准**;公开 F1 0.96626 量纲与标准 F1 一致,A 为笔误。 |
| 3 | author-paper 边语义措辞 | project_description.md "authors have read" | dataset.md "paper that the author cites" | **实质同义,无冲突**(均 author→paper 正边);仅措辞差异。 |
| 4 | 测试集对数 | CLAUDE.md "~2.05M" | 实测 2,047,262 | **一致**,无冲突。 |
| 5 | feature.pkl 大小 | WORKSPACE_STATUS.md "约 156 MB" | 实测 163,711,392 字节(156.13 MiB) | **一致**,无冲突。 |
| 6 | **缓存/产物目录是否缺失** | WORKSPACE_STATUS.md L167-184 称 env/、checkpoints/、validation_runs/dynamic_seed202/、feature_cache/ 缺失,无法复现 | README 假定已含 | **裁决: 目录实存**。本次 ls 实测 `validation_runs/dynamic_seed202/`(含 high_order_graph_stack/randomwalk_systematic/content_rich 等全部 stage)、`validation_runs/feature_cache/`(content_mean/content_rich/high_order 缓存)、`checkpoints/`(extra_models/final_ens6)、`env/`(3 个文件)均存在。以**当前文件系统**为准,WORKSPACE_STATUS.md 描述过时/有误。 |
| 7 | author_file_ann 合著边规模 | CLAUDE.md/README 无具体数 | 实测 9,663 | 无冲突,补充实测数。 |
| 8 | LightGCN 默认层数 vs 最佳 | 代码默认 --layers=4 (L426); CLAUDE.md "4 层" | 最佳 run `l2d512` 编码 L=2 | **最佳配置 layers=2, dim=512, dot**(run 名 l2d512 + 复算)。4 仅为 argparse 默认;README/CLAUDE.md 笼统写 4 层易误导。可信: run 名+复算 > 文档措辞。 |
| 9 | bigbatch_more 缺 model_results.csv/ensemble_result.txt | 代码 main() 必写(L484, L499) | 目录仅 scores/ 子目录 | 该 run ensemble 分数已保留并被下游使用;CSV/txt 在精简时被删。F1 由 dynamic_summary.csv + 代码复算可信。 |
| 10 | "LightGCN ensemble" 混用 | preliminary_report.md: 6-model(5×256d/4层 + 1×384d)public 0.93044 | dynamic best: 2 seed(41,141) × 512d/2 层 dot 验证 0.9386 | **两个不同阶段产物**: 6-model=早期提交(0.93044);dynamic best=stacking 主分数(0.9386,未单独提交)。不矛盾但易混淆。 |
| 11 | eval-mode 默认 cos vs 最佳 dot | 代码默认 --eval-mode cos (L441) | bigbatch_more 分数文件名 `val_vanilla_dot_*`, 阈值 3.50(点积量纲) | **最佳 run 显式用 dot**;cos/dot 在未归一嵌入时结果不同。 |
| 12 | CLAUDE.md 称 explicit meta-path 用稀疏矩阵 | CLAUDE.md L107/L83 暗示 sparse | stack_rank_calibration.py 全文无 scipy.sparse | **本文件零稀疏矩阵**;meta-path 全用 Python set 交/并集(L120-142)。CLAUDE.md 所指 sparse-matrix 是 high_order_graph_stack.py 的 build_high_order*,非本文件。可信: 代码 > CLAUDE.md。 |
| 13 | out[i,12] 与 out[i,3] 重复(co_read_count) | L130 与 L139 字面相同 | 产生两列恒等特征 | **代码事实存在冗余**(LightGBM 自动忽略共线列);"18 维有效信息"实为 17 维独立。reports 未披露。可信: 代码 > reports。 |
| 14 | stack_rank_calibration.py 自带 ratio[0.505–0.540] vs 最终决策 0.500 | 本文件 L282 ratio list | CLAUDE.md/最终 high_order 用 0.500 | 不矛盾: 本文件 main() 是早期/独立消融提交,非最终物;最终 0.9669 来自 high_order_graph_stack。 |
| 15 | stack OOF F1=0.955992 无原始 csv | exploration_summary.md L113 | glob 查 stack_rank_calibration/result.csv 不存在 | 追溯性证据缺口而非冲突;数字只能来自 reports。需重跑脚本可复核。 |
| 16 | 负证据/topk 增益方向 | post95_ablation.csv: neg Δ≈-0.000235(微负), topk +0.00058 | README/CLAUDE.md 列为有效特征组 | **可信 csv>README**: 该阶段单独增量微弱/微负;真正增益来自变体特征(+0.0011→0.95707)与 BPR/content。README 叙事略夸大单独贡献。属叙事张力。 |
| 17 | post95 public 0.95760 vs 验证 0.95711 | README L43 | extra_score_ablation post95_lgbm_baseline | 两者口径不同(public 测试 vs 验证 1:1),数值相近,非冲突。 |
| 18 | selected_variant_val_scores.txt 绝对路径前缀 | 全 20 行 /data/lzc/cs3319_transfer_package/ | 代码用 Path 解析 | 已知遗留,CLAUDE.md 已声明以 package-root 为准。 |
| 19 | learnw/no_cite 变体未入选 | 代码支持 vanilla/learnw + use_citation 切换 | selected 20 行全为 val_vanilla_* | 不冲突: 按 F1 排序的客观结果,learnw/no_cite 排在 20 名外。 |
| 20 | RW aggregate 11 列 vs 内联 agg 10 列 | generate_randomwalk_ensemble_submission.py aggregate() 11 列 | randomwalk_systematic 内联 agg 10 列 | 维度不一致;以**最终使用的 aggregate() 11 列**为准。 |
| 21 | figures_paper "+0.00182" 稳态增益 | figures 标题 | CSV 重算 best-single→5→7 仅 +0.00155 | **以 CSV 重算 +0.00155 为准**;figures 数字偏高,需更正。 |
| 22 | "0.964947" vs "0.964921" | final_report/exploration 的 0.964947 | ensemble_7 CSV 0.964921 | **不同 stacker**: 0.964947=rich_rw7(190 维, high_order_graph_stack validation_summary.csv L4);0.964921=ensemble_7(172 维, randomwalk)。需区分,勿混用。 |
| 23 | small/graph_ablation_table.csv 仅 2 行 | 脚本应写 6/4 行+集成 | 实测各 2 行,且与 7 个 _oof.npy 不完全对应 | CSV 被部分覆盖/截断;**以 `_oof.npy` 重算为可信源**。 |
| 24 | bigbatch_more 精确生成命令无记录 | 无 notes/reports 命中 --seeds 41 141 | 由 scores 文件名(dot, s41/s141, d512)+ run 名 l2d512 反推 layers=2 | train-batch/lr/epochs 等未在包内可证,标注"未明确确认"。 |
| 25 | 测试集真实正例比例 | 公开榜 50% 评分 | 文件无法直接算出 | **未知**,无法从文件核验;rank top 50% 是否匹配真实正先验属建模假设。 |

---

## 6. 关键代码位置速查表

| 脚本 | 函数/符号 | 行号 | 作用 |
|---|---|---|---|
| train_val_lgcn_ensemble.py | `make_notebook_style_split` | 132-165 | seed=202 切分: 90/10 留出 + 等量随机负例 → 1:1 验证集 |
| train_val_lgcn_ensemble.py | `build_parts` | 168-236 | 加载 feature.pkl + 度特征 + popular 集 + coauthor_pool;L216 硬编码 range(6611) |
| train_val_lgcn_ensemble.py | `build_data` | 239-270 | PyG HeteroData: 4 边类型, 引用/合著双向拼接, 论文 515→embed 投影 |
| train_val_lgcn_ensemble.py | `LightGCNLayer` | 49-70 | 纯加权邻居聚合, 无非线性无 W, 入度归一 |
| train_val_lgcn_ensemble.py | `LightGCN.encode` | 87-100 | 1/(L+1) 均匀权重 layer-0 weighted sum |
| train_val_lgcn_ensemble.py | `LearnableWeightLightGCN.encode` | 112-125 | softmax 学习各层权重(variant=learnw) |
| train_val_lgcn_ensemble.py | `LightGCN.decode` | 102-104 | author·paper 点积打分 |
| train_val_lgcn_ensemble.py | `sample_hard_negatives` | 273-305 | 混合硬负采样 random 50% / popular 25% / coauthor-pool 25% |
| train_val_lgcn_ensemble.py | `best_f1` | 340-346 | PR 曲线 argmax 最优 F1 阈值 + AUC |
| train_val_lgcn_ensemble.py | `predict_scores` | 308-337 | no_grad 批量打分, cos/dot/neg_l2 |
| train_val_lgcn_ensemble.py | `train_one` | 349-414 | 单(seed,dim)训练: BPR/hinge/bce + 硬负 + 早停式 best F1 |
| train_val_lgcn_ensemble.py | `main` | 417-502 | argparse + dim×seed for 循环 + 均值 ensemble |
| stack_rank_calibration.py | `ExplicitGraphFeatures.__init__` | 54-106 | 默认 num_authors=6611, num_papers=79937; 预计算 shared_paper_authors(A-P-A) + coauthor_paper_union(A-A-P) |
| stack_rank_calibration.py | `ExplicitGraphFeatures.transform` | 108-145 | 18 维手工特征(out[i,0..17]);L139 与 L130 重复 |
| stack_rank_calibration.py | `add_rank_features` | 148-160 | 4 列: score/global_rank/author_pct/author_rank |
| stack_rank_calibration.py | `fit_oof` | 163-184 | 5-fold StratifiedKFold; LGBM(1200,lr0.025,reg_lambda5) |
| stack_rank_calibration.py | `boundary_rerank` | 187-201 | LightGCN 边界重排(zscore 加权), 仅本文件内用 |
| generate_post95_submission.py | `select_variant_val_scores` | 160-172 | 按 F1 排序取前 max_cols(20), 过滤 hgt/sage/bce/norm/hinge |
| generate_post95_submission.py | `variant_feature_matrix` | 175-183 | 43 列(20×2 + 3 聚合) |
| generate_post95_submission.py | `topk_content_similarity_fast` | 186-216 | 3 列(max, top-3, top-5 内容相似度) |
| generate_post95_submission.py | `score_checkpoint_on_test` | 79-157 | 验证变体→测试对映射(dot/neg_l2/cos) |
| generate_post95_submission.py | `make_submissions` | 219-229 | rank-cutoff + test_known_mask 强制 1 |
| post95_ablation.py | `negative_evidence_features` | 176-192 | 8 列负证据/交互(依赖 X_hand 第 1/3/7/8/12/13/14 列) |
| extra_score_sources_ablation.py | `score_to_features` | 47-56 | 标量分→4 列(raw/z/rank/author_rank) |
| extra_score_sources_ablation.py | `content_mean_score` | 80-97 | 作者历史 embedding 均值 · 候选向量 → 标量分 |
| extra_score_sources_ablation.py | `train_mf_bpr_score` / `MF` | 100-163 | BPR-MF: dim256, epochs220, batch65536 |
| content_rich_ablation.py | `content_rich_features` | 54-129 | 从 feature.pkl 产 18 列 rich 内容画像 |
| content_rich_ablation.py | `main`(X_base 构建) | 157-171 | 84 维 X_base 拼接(76 + content4 + mf4) |
| randomwalk_systematic_ablation.py | `pair_feature_block` | 216-270 | 每块 11 维(dot/cos/hadamard/absdiff/l2 + 6 排序) |
| randomwalk_systematic_ablation.py | `build_base_features` | 273-300 | X_base 84 维 |
| randomwalk_systematic_ablation.py | `deepwalk_walks` / Word2Vec | 139-176 | DeepWalk 等价 p=q=1; sg=1, min_count=0, neg=5, epochs=3 |
| randomwalk_systematic_ablation.py | (Node2Vec) | 178-189 | node2vec 包, batch_words=4096, epochs=3 |
| randomwalk_systematic_ablation.py | 配置块定义 | 87-115 | small_configs(6)/graph_configs(4)/extra_configs(6),最终仅 7 块入模型 |
| generate_randomwalk_ensemble_submission.py | `aggregate` | 50-69 | 11 列一致性聚合(5 cos stat + 2 dot + 4 rank + agree) |
| high_order_graph_stack.py | `build_high_order*` | (sparse-matrix) | H_k=R·C^k, G_k=S·R·C^k; fwd/bwd/undir; undir24 + directed45; 硬编码 6611/79937 稀疏矩阵形状 |
| high_order_graph_stack.py | `fit_full_predict` | (final) | LightGBM(num_leaves=15, reg_lambda=8, lr=0.022, n_est=1400) 5-fold OOF |

> 共享库说明: 无 utils.py;`train_val_lgcn_ensemble.py` 与 `stack_rank_calibration.py` 为两大事实共享库,被 ~14-16 个脚本经 importlib.util `load_module` 运行时加载。legacy `run_*.py`(run_baseline/improved/v2/final/ultimate/lgcn_final/lgcn_v2/graph_features, compare_gnn)含硬编码 `/home/lzc` 路径、无 argparse,仅作存证。

---

## 7. 三目录图表清单(候选素材)

以下为本仓库可作为论文/文档图表素材的清单(未逐一展开内容,供后续文档取用):

| 类别 | 路径 / 来源 | 建议用途 |
|---|---|---|
| 方法演进折线图 | 第 3 节时间线数据(验证 F1 + 公开 F1) | 总体性能演进 |
| 高阶消融柱状图 | 第 2.4 节 4 行(108→190→214→259 维) | undir/directed 增量贡献 |
| 259 维特征构成堆叠图 | 第 2.5 节 10 个特征族 | 特征工程总览 |
| LightGBM 特征重要性 | (注意) lightgbm/gensim 在本机 Python 3.14 未安装 → 用**消融贡献瀑布**替代 gain | 特征贡献(瀑布) |
| 验证 1:1 vs 测试分布漂移 | 阈值 0.4617(seed 间 0.4435–0.4857) vs rank 0.50 vs 漂移 0.5242 | 为何用 rank cutoff |
| 二部图稀疏/长尾 | 密度 1.29e-3, 56% 作者度=1 | 数据集难度 |
| RW 7 块单模型→集成 | small/graph_ablation + ensemble_7 CSV | 游走多样性互补 |
| 公式渲染 | H_k=R·C^k, G_k=S·R·C^k, S=合著, R=作者-论文, C=引用(fwd/bwd/undir) | 高阶传播方法图 |

> 图表规则(已核验记忆): 存在两个 paper figure 包;val-label↔OOF 已复算对齐(F1 0.966874);因无 lightgbm/gensim,特征重要性图用消融瀑布而非 LightGBM gain。

---

## 附: open_questions(待跨审计/后续核验)

- bigbatch_more 的精确 argparse(--train-batch-size, --lr, --epochs)未在包内可证,仅能反推 layers=2/dim512/dot/seeds{41,141} —— **未明确确认**。
- 其余 13 个 LightGCN 变体 run 的精确参数无日志,仅从 run 名 + dynamic_summary.csv 反推。
- LearnableWeightLightGCN(learnw)是否曾用于最终任何提交不明(dynamic_summary.csv 中 F1≈0.9356 较低)。
- 测试集 2,047,262 对的真实正例比例未知,rank top 50% 是否匹配真实正先验属建模假设。
- val_pairs.csv / train_refs.csv 在 split_dir 模式读取(L179-180)但包内无 splits/ 目录,验证集只能由 make_notebook_style_split 实时重建(已验证可复现)。
- stack OOF F1=0.955992 缺原始 result.csv 复核(需重跑 stack_rank_calibration.py)。
- boundary_rerank(L187-201)是否在最终提交被实际使用存疑(仅本文件内定义调用,未见外部复用)。
- data_and_docs/ 下 advice.md / proposal.md / references.md / project-example-2026-pygver.ipynb / project2_rec.pdf 等文档未逐一展开。