Train ATI-HO and finalize project outputs

final/q3/README.md

@@ -1,67 +1,55 @@
-# Q3：分层反事实证据归因
+# Q3：ATI–HO 锚定交互与分层 Owen 归因
 
-## 第一轮比较
+当前 Q3 方案采用 ATI–HO。训练和评估入口位于 `q3/ati_ho/`，模型定义集中在 `model/ati_ho.py` 与 `model/ati_ho_config.py`。附件 4 只用于最终推理和解释，不参与训练、选型或性能指标计算。
 
-第一轮直接复用 Q2 官方 unaligned_50 实验中的 EarlyConcat + BiGRU、MoFE-7 + MLP Router 权重和 train-only robust scaler。这样 E0/E1/E2 使用固定预测器，主要比较解释方式。
+## 数据与输入
 
-| 方案 | 预测器 | 解释 |
-|---|---|---|
-| E0 | EarlyConcat + BiGRU | 三模态精确 Shapley、配对交互、多尺度局部遮蔽 |
-| E1 | MoFE-7 + MLP Router | Router 模态/位置权重；用反事实删除检验其是否 faithful |
-| E2 | 与 E1 相同的 MoFE 检查点 | 三模态精确 Shapley、配对交互、多尺度局部遮蔽 |
+将题目附件放在 `final/data/`，或设置 `FINAL_DATA_DIR` 指向包含官方附件目录的根路径。运行需要附件 2 的 `unaligned_50.pkl`、附件 4 的未对齐特征和视频，以及 Q2 训练集拟合的 scaler：`experiments/q2/unaligned_deep_two_b128/unaligned_50_robust_stats.npz`。
 
-E1 与 E2 的预测逐样本相同。E1 的路由权重只描述融合机制，只有通过删除检验后才能说明它在这些样本上是否与预测行为一致。
+训练、验证、测试按官方来源视频组隔离。所有模态经统一 Q1 adapter 投影到 50 个 Relative-Progress 槽；这统一的是序列内部进度，不代表物理时间同步。Scaler 仅使用训练集统计量。
 
-## 运行
+## 训练
 
-从项目根目录执行，附件目录由 FINAL_DATA_DIR 指定。它应包含 附件2-数据集特征文件/unaligned_50.pkl 和 附件4-可解释专项视频样本与特征文件/。
+从项目根目录执行。首次完整训练依次完成 Stage I 和 Stage II：
 
-~~~bash
-export FINAL_DATA_DIR="/path/to/task-data"
-python -m final.q3.run_experiments \
-  --output-dir final/output/q3/first_round \
-  --device auto
-~~~
+```bash
+export FINAL_DATA_DIR="/path/to/E题数据"
+python -m final.q3.ati_ho.train --phase all --device auto
+```
 
-检查点与 scaler 默认读取 final/experiments/q2/unaligned_deep_two_b128/。完整运行会计算官方验证集预测及误差归因。--skip-validation 跳过这一步；--no-frames 跳过候选帧抽取。每轮实验使用新的空输出目录；若上次运行中断且留下部分文件，可对该目录增加 --resume 重新生成结果。
+Stage I 使用 seed 42 训练 A0/A1/A2/A3 与未锚定诊断 D0，执行结构和 8 联盟 Shapley 审计并确定 provisional candidate。Stage II 使用 seeds 42、3407、2026 训练 EarlyConcat + BiGRU、MoFE-7 + MLP Router、初选 ATI 方案和两项关键消融。若需分阶段运行，可用 `--phase stage1` 或 `--phase stage2`；Stage II 需要 Stage I 的选择记录。默认最多 12 个 epoch，按锁定验证情景损失早停。已存在的检查点会复用；需要重训时显式加 `--force`。
 
-## 方法定义
+训练输出写入 `experiments/q3/ati_ho/`，含检查点、训练历史、逐情景验证指标、阶段状态、scaler 和 adapter 元数据。附件 4 不会在训练程序中加载。
 
-令三个模态为 (M={T,A,V})。对每个附件 4 样本完整计算 8 个 coalition。分类价值函数使用完整输入预测类别的 logit，并在所有 coalition 上固定该类别；回归价值函数使用模型情感强度输出。绝对 Shapley 贡献除以三模态绝对贡献之和，得到模态作用比例；带符号值保留支持或反对预测的方向。配对交互采用标准 Shapley interaction index 系数。
+## 评估与附件 4 输出
 
-局部证据对每个可见模态位置计算窗口宽度 (win{1,3,5}) 的遮蔽前后差值，三个尺度等权平均。每个模态选取局部贡献绝对值最高的 10% 位置，合并相邻位置，并输出代表证据段。
+完成两阶段训练后运行：
 
-Faithfulness 使用固定预测类别 logit。Comprehensiveness 比较完整输入与删去高排名证据后的分数；sufficiency 比较完整输入与只保留高排名证据后的分数；deletion AUC 汇总删除 0% 到 70% 的分数下降。另记录宽度 1/3/5 局部图之间的 Spearman 相关作为尺度稳定性诊断。MoFE Router 与精确 Shapley 按样本比较 Spearman 排序相关和主导模态一致率。
+```bash
+export FINAL_DATA_DIR="/path/to/E题数据"
+python -m final.q3.ati_ho.evaluate --device auto
+```
 
-## 输出
+评估按 A0/A1/A2 三 seed 固定四场景验证损失的均值确定最终 ATI 方案，随后生成配对来源视频组 Bootstrap、最终模型结构审计、全验证集解析/精确 Shapley 审计、Owen 稳定性和删除/保留诊断，以及模型成本表和结果图。评估不基于附件 4 标签计算指标。
 
-- attachment4_predictions.csv：E0、E1、E2 对 20 个样本的完整预测与类别概率。
-- attachment4_modal_shapley.csv：分类与强度的有符号贡献、绝对比例和完备性残差。
-- attachment4_pairwise_interactions.csv：Text–Audio、Text–Vision、Audio–Vision 交互。
-- attachment4_local_evidence.csv：E0/E2 的 1/3/5-bin 遮蔽差值和来源行。
-- attachment4_router_profiles.csv、attachment4_router_local_evidence.csv：MoFE 的专家权重和逐位置 Router utility。
-- attachment4_evidence_segments.csv：稀疏代表证据段、来源行、转写文本和候选视频时间。
-- faithfulness_by_sample.csv、q3_method_comparison.csv：逐样本与方案汇总的删除/保留检查。
-- validation_predictions.csv、validation_errors.csv、validation_error_attribution.csv：官方验证集指标、误差样本和分类 margin 归因。
-- explanation_cards/、typical_explanation_card.md、evidence_profiles/：逐样本解释卡、代表卡和 3×50 热图。
-- evidence_frames/：从原始视频抽取的候选帧。
-- run_manifest.json：检查点、scaler、输入模式、公式、运行边界与产物清单。
+题目输出放在 `output/q3/ati_ho/`：
 
-## Router 热力图样例
+- `attachment4_predictions.csv`：20 个样本的类别、情感强度、类别概率和各模态可见槽数量。
+- `attachment4_explanations.csv`：五个参数的主效应、pairwise 参数项、解析与精确分类 Shapley，以及精确强度 Shapley。
+- `attachment4_local_evidence.csv`：每个样本按模态和 10 个相对进度片段排列的 Owen logit-margin 贡献与标准误。
+- `attachment4_prediction_manifest.json`：adapter/scaler、类别顺序、输入与检查点 SHA-256、行数和无标签推理声明。
+- `README.md`：上述交付件说明与坐标限制。
 
-在完成 Q3 第一轮后，还可以绘制附件 4 样本 02、03 的输入遮蔽与 Router 权重对照图。每个样本分别展示原始完整输入和受控残缺输入：样本 02 遮蔽 30% 文本与音频，样本 03 遮蔽 30% 视觉。蓝色斜线只标输入中被遮蔽的位置；紧接着一行把七个 expert（T、A、V、TA、TV、AV、TAV）横向排列，色块/数字显示样本平均 Router 权重，下方窄条显示 50 个 bin 上的 α[t,e]。
+完整实验产物在 `experiments/q3/ati_ho/results/ati_ho/`，包括 `ATI_HO_RESULTS.md`、论文式报告、验收摘要、CSV 审计表、图和运行清单。验证集逐样本结果及训练权重也保存在 `experiments/q3/ati_ho/`。实验归因文件可供复核，不属于精简的题目输出目录。
 
-~~~bash
-export FINAL_DATA_DIR="/path/to/task-data"
-python -m final.q3.plot_router_heatmaps --output-dir final/output/q3
-~~~
+## 模型定义与解释边界
 
-这两个残缺样例是人为遮蔽的对照，不是附件 4 的原生缺失数据。文本 token 按序列顺序显示，蓝色斜线标出对应遮蔽词段；音频波形和视频帧按相对进程显示蓝色遮蔽区。每个 bin 的七个 expert 权重在可用专家集合内归一化，未满足模态条件的 expert 权重为 0；色条使用原始 0–1 数值并通过平方根归一化提高低权重的可读性。样例顶部另列 T/A/V 的总体 Router exposure share。视频帧和音轨只按归一化进程投影，不能当作精确词/帧同步。Router 权重反映融合路由，不是预测贡献或情绪因果解释。
+模型输出由 3 个居中的类别 logit、负向强度参数和正向强度参数组成。ATI 主效应以空输入前向作零锚定；候选 pairwise 分支只读取对应的两种模态并对缺失模态基线作锚定。A0 是只有主效应的基线，A1 增加秩 4 的 pairwise 分支，A2 再加入一层 4 头交叉注意力，A3 增加可见性掩码去噪辅助目标；D0 是未锚定诊断。未加入三阶项。
 
-图表与原始数据输出为 `mofe_router_heatmap_examples.png`、`mofe_router_heatmap_examples.pdf`、`mofe_router_heatmap_scores.csv`（逐 bin 七个 α 分数及模态可见掩码）、`mofe_router_heatmap_summary.csv` 和 `mofe_router_heatmap_manifest.json`。
+分类解释固定完整输入的预测类别与次高类别，以 logit margin 为目标；解析 Shapley 与完整枚举 8 个模态联盟的结果比较。情感强度经过类别选择和 sigmoid 解码，是非线性输出，因此单独对 8 个联盟精确枚举强度 Shapley。局部 Owen 将三模态作外层组、每模态 10 个五槽片段作内层组，按 8、16、32、64 个随机排列检查稳定性。
 
-## 回溯边界
+位置均为相对进度槽，不是秒数。遮挡测试描述模型对输入可见性的响应，不是人类解释准确率或情绪因果效应。附件 4 没有真实标签，所以只输出预测与模型解释，不声称其预测精度。
 
-附件 4 的文本、音频和视觉序列为未对齐特征，没有逐词、逐音频帧或逐视频帧的真实时间戳。输出会从 adapter 的稀疏投影权重记录来源特征行和归一化进程。视频候选秒数由归一化进程乘视频时长估算，只供人工回看；它不是真实物理时间对齐。文本 token 需要本地缓存 google-bert/bert-base-uncased tokenizer；缓存不存在时，解释卡仍保留完整转写和来源行。
+## 早期 Q3 文件
 
-这些解释衡量的是当前预测器对输入遮蔽的响应，不是现实情绪成因。虽然模型在 Q2 训练时见过模态遮蔽，局部孤立遮蔽和只保留 10% 的输入仍可能偏离训练分布；相关数值按诊断结果报告，不称为解释准确率或因果效应。
+此前 MoFE 复用检查点的第一轮解释和 Router 可视化保存在 `experiments/q3/legacy_mofe_first_round/`，用于保留历史记录。当前 `output/q3/` 只放本题采用的 ATI–HO 交付文件。