# 助教验收说明（SUBMISSION README — for the TA）

> **一句话**：本项目为 CS3319 Project 2（学术论文阅读推荐 / 作者-论文异构图链接预测），最终**公开榜单 F1 = 0.96626**、验证集 F1 = 0.966874。
> **验收只需 3 步、纯 CPU、数秒**：解压 → 装依赖 → 跑一个 notebook，即可看到提交被**逐位复现**。

---

## 0. 本包是什么（What's in this package）

| 项 | 内容 |
|---|---|
| 任务 | 异构学术网络（6,611 作者 / 79,937 论文）上的作者-论文链接预测，指标 F1 |
| 最终方法 | 259 维多源特征（LightGCN + BPR-MF + 7×DeepWalk/Node2Vec + 高阶引用传播 + content-rich + meta-path）上的 LightGBM 二阶段堆叠；决策用 rank-cutoff top 50% + 强制已知正样本 |
| 最终成绩 | **公开 F1 0.96626** · 验证 F1 0.966874 · AUC 0.994918 |
| 论文 | `ACM_Conference_Proceedings_Primary_Article_Template/cs3319_final_paper_cn.pdf`（中文，ACM 双栏） |
| 代码 | `code/run_inference.ipynb`（验收入口，加载权重复现提交）+ `code/*.py`（完整实验脚本） |
| AI 标注 | 见根目录 `AI_USAGE.md` |

> ⚠️ 这是一个**精简可运行包**。大体积中间产物（2.5 GB 验证中间结果、完整随机游走特征等）未打入本 zip，但可在 **Hugging Face 备份仓库**获取（见第 5 节）。本包已包含**验收所需的一切**。

---

## 1. 目录结构（Key layout）

```
cs3319_final_deliverable/
├── SUBMISSION_README.md          ← 本文件（先读我）
├── README.md                     ← 完整项目说明与全流程复现命令
├── AI_USAGE.md                   ← AI 内容使用声明
├── code/
│   ├── run_inference.ipynb       ← ★ 验收入口：加载权重 → 复现最终提交
│   └── *.py                      ← 完整实验/提交生成脚本
├── checkpoints/                  ← LightGCN 训练权重（final_ens6 6 个 + extra_models）
├── cached_scores/                ← LightGBM 模型、测试分数、已知正样本掩码
├── validation_runs/dynamic_seed202/high_order_graph_stack/
│   ├── rich_rw7_highorder_directed_test_pred.npy   ← 最终系统测试集推理输出
│   ├── rich_rw7_highorder_directed_oof.npy         ← OOF 分数
│   ├── validation_summary.csv                      ← 验证指标
│   └── submissions/
│       └── submission_rich_rw7_highorder_directed_r0.500000.csv  ← ★ 最终提交（公开 0.96626）
├── data_and_docs/                ← 官方数据（边文件 + feature.pkl + 测试对）+ 课程文档
├── env/                          ← 环境依赖（requirements-minimal.txt / environment-cs3319.yml）
├── reports/                      ← 报告（preliminary / exploration / final）
└── ACM_Conference_Proceedings_Primary_Article_Template/
    └── cs3319_final_paper_cn.pdf ← 论文 PDF（同目录有 .tex / .bib 源码）
```

---

## 2. 环境准备（Environment，约 2 分钟）

需要 **Python 3.10**。验收 notebook 仅依赖 `numpy` + `pandas`（可选 `torch`，用于加载权重演示）。

```bash
# 方式 A：最小依赖（够跑验收 notebook）
python -m pip install numpy pandas

# 方式 B：完整依赖（可跑全流程实验）
python -m pip install -r env/requirements-minimal.txt
# 或 conda：
# conda env create -f env/environment-cs3319.yml
```

> 推荐 Python 3.10。若只想验收，方式 A 即可，无需 GPU、无需 torch。

---

## 3. ★ 三步验收（Verification in 3 steps）

```bash
# 1) 解压（若尚未解压）
unzip cs3319_final_deliverable.zip
cd cs3319_final_deliverable

# 2) 装依赖（最小集即可）
python -m pip install numpy pandas

# 3) 运行验收 notebook（纯 CPU，数秒）
jupyter notebook code/run_inference.ipynb
#   或命令行直接执行：
jupyter nbconvert --to notebook --execute --ExecutePreprocessor.kernel_name=python3 \
    code/run_inference.ipynb --output run_inference.executed.ipynb
```

### 预期输出（Expected output）

notebook 会逐步打印，关键两处：

```
逐位一致 / exact match : 2047262 / 2047262 -> True
OK Reproduction verified: regenerated submission is byte-identical to the stored final submission.

验证集 F1   / validation F1 : 0.966874
公开榜单 F1 / public LB F1  : 0.96626
```

看到 **`exact match : 2047262 / 2047262 -> True`** 即代表：从训练系统的缓存推理输出出发，应用论文的 rank-cutoff 决策规则，**逐位复现**了最终提交 CSV。这就是对「模型权重有效、决策规则正确、结果可复现」的完整证明。

> notebook 第 5 节为可选项：用 `torch.load` 直接载入一个 LightGCN 权重文件，证明训练好的 GNN 权重确实在包内且可在 CPU 载入。无 torch 时会自动跳过，不影响上面结论。

---

## 4. 直接核对最终提交（无需运行代码）

若只想快速核对结果，不用跑代码：

```bash
# 验证集指标
cat validation_runs/dynamic_seed202/high_order_graph_stack/validation_summary.csv
# → rich_rw7_highorder_directed, validation_f1=0.966874, auc=0.994918, n_features=259

# 最终提交文件存在性与正例比例（应 = 0.5）
python -c "import pandas as pd; d=pd.read_csv('validation_runs/dynamic_seed202/high_order_graph_stack/submissions/submission_rich_rw7_highorder_directed_r0.500000.csv'); print(d.shape, d.Predicted.mean())"
# → (2047262, 2) 0.5
```

---

## 5.（可选）完整管线复现（Full pipeline reproduction）

本 zip 只含「加载权重→复现提交」所需产物。若需**从原始数据重训全部模型**（LightGCN / DeepWalk / LightGBM），需要大体积中间特征，可从 **Hugging Face 备份仓库**拉取（URL 见交付邮件/最终报告），然后按 `README.md` 的「Command Reproduction」一节运行：

```bash
python code/high_order_graph_stack.py --package-root . --split-seed 202 --seed 202 --n-splits 5 --make-submission
```

> 该路径**纯 CPU 可跑**（LightGBM），但需 `cached_scores/`、`validation_runs/feature_cache/`、`randomwalk_systematic/` 等完整缓存（数分钟）。重训 LightGCN 本身需 GPU。

---

## 6. 常见问题（Troubleshooting）

| 现象 | 处理 |
|---|---|
| `ModuleNotFoundError: numpy/pandas` | `pip install numpy pandas` |
| notebook 找不到仓库根目录 | 从仓库根或 `code/` 目录启动均支持；切勿把 notebook 单独拷出 |
| 第 5 节 `(跳过) torch 权重加载需要 PyTorch` | 正常，非必需；装 `torch`（CPU 版）后可看到权重加载 |
| 想看完整训练代码 | `code/train_val_lgcn_ensemble.py`（数据/划分/best_f1）、`code/high_order_graph_stack.py`（最终堆叠器） |
| 提交文件格式 | 两列 `Index,Predicted`，Predicted ∈ {0,1}，共 2,047,262 行，正例比例 0.5 |

---

## 7. AI 内容标注

本交付物的 AI 使用情况（论文/文档/图表/notebook 等）已在 **`AI_USAGE.md`** 中逐产物如实标注。**所有实验数值均来自真实实验**，AI 未参与数值生成/伪造。

---

## 8. 联系

如验收遇阻，请按第 3 步命令把 notebook 输出贴回；该命令在本机已验证通过（见 `AI_USAGE.md` 第 4 节「结果真实性承诺」）。