更新 math Q1 Q2 实验与特征

math/Q1/README.md

@@ -1,44 +1,40 @@
-# 问题一模型对比
+# Q1：模态对齐与特征分支
 
-本目录实现问题一 PDF 第 4.8.3 节的 B0–B4 单因素对照。代码从附件一的 100 条原始视频和标签表开始，先生成统一的文本、语音、视觉特征，再在 0.1 秒主时间网格上进行五折 `video_id` 留组评估。
+本目录按《E题V2》第四章构建 Q1 对齐特征。规格核对与限制见 [`V2_REVIEW.md`](V2_REVIEW.md)，可供后续训练读取的主特征包位于 `features_v2/`。
 
-## 运行
+## V2 特征包
 
-在仓库根目录执行：
+- 100 个样本、300 条模态明细；主物理时间视图为 0.1 秒，并保留真实末段长度。
+- 文本采用冻结 BERT 词级特征；音频 74 维；视觉采用 OpenFace 2.2.0 的 35 维输出。
+- 原生词、音频窗、视频帧与源索引均保留；另提供逐词 CTC 后验、50 段相位视图、多尺度视图、B4 语音视图和物理时间查询矩阵。
+- 每个时间视图包含均值、方差、计数、逐维物理覆盖率、掩码和独立质量摘要。质量加权只影响特征汇聚，不改变物理覆盖率。
+- B4 Wav2Vec2 视图通过接口从本机 `cache/native/` 按需读取；不复制进主包。
+- 特征文件共 44,321,715 字节（约 42.27 MiB）。`feature_manifest.json` 记录配置哈希、源运行信息及精确字节数。
 
-```bash
-cd math/Q1
-uv sync
-uv run python compare_models.py
+## 读取接口
+
+```python
+from q1_io import load_sample, get_view, csr_from_sample
+
+sample = load_sample("video_id/clip_id")
+primary = get_view(sample, "audio", "sec")
+multiscale = get_view(sample, "audio", "multi", context_s=0.3)
+posterior_text = get_view(sample, "text", "posterior")
+word_to_audio = csr_from_sample(sample, "query_word_audio_H_time")
+b4_speech = get_view(sample, "speech", "sec")
 ```
 
-默认使用 CUDA（如果可用），需要可访问 Hugging Face 下载 BERT 与 Wav2Vec2 权重；MediaPipe Face Landmarker 权重会保存在 `math/Q1/cache/`。可用 `--device cpu` 指定 CPU。缓存保存在 `math/Q1/cache/native/`，中断后重跑会继续使用已完成样本。只有传入 `--force-extract` 才会重算全部原始特征。
+`get_view` 支持 `sec`、`word`、`phase50`、`multi` 和文本专用 `posterior`。多尺度视图从原生行按窗口重新聚合；`speech` 视图依赖本机原生缓存。清单文件为 `features_v2/manifest_q1.jsonl`、`sample_summary.csv` 和 `modality_summary.csv`。
 
-## 对照定义
+## 重建和五折探针
 
-- **B0**：冻结 BERT 词向量、冻结 CTC Viterbi 词边界、物理时间区间投影；训练折均值/标准差缩放。
-- **B1**：B0 加训练折中位数/MAD 稳健缩放，并对面部旋转使用 SO(3) 均值、对视线代理使用单位向量均值。
-- **B2**：B1 只替换文本时间投影，使用 CTC 固定转写状态图的前向–后向词占据后验。音频/视频的 PTS 不变。
-- **B3**：B1 加音频 log-F0/能量和面部 jaw-open/嘴部开合率的一、二阶时间增广路径签名。缺测处会断开路径。
-- **B4**：B1 加冻结 Wav2Vec2-base-960h 最后四层的时间投影表示。
+在仓库根目录运行：
 
-每个模型以相同的五段时间池化探针评价极性和强度。分类器为固定 C=0.05 的逻辑回归，回归器为固定 alpha=25 的 Ridge；参数不按留出折调节。归一化器只使用训练折观测值。95% 差值区间以 `video_id` 为单位做 2,000 次配对 Bootstrap。
+```bash
+uv run --project math/Q1 python math/Q1/build_v2.py
+uv run --project math/Q1 python math/Q1/compare_v2.py
+```
 
-文本维度为 768（BERT 最后四层、词内子词平均）；语音为 74 维（40 log-Mel、13 MFCC、13 ΔMFCC、8 韵律/谱量）；视觉为 35 维（17 个 MediaPipe blendshape 代理、6 维头姿、6 维近似视线、6 维面部比例几何）。MediaPipe blendshape 分数不等于 OpenFace AU 强度，视线为基于虹膜偏移的代理量；本次实现记录了实际所用索引与定义，没有将代理量称为 OpenFace 特征。
+特征重建依赖 `cache/native/`、`source_cache_manifest.json`、附件一视频及本机模型资源。`build_v2.py` 复用 `compare_models.py` 中的标签读取、缓存解析和数据结构；V2 对照入口是 `compare_v2.py`。B0–B4 五折 `video_id` 分组探针写入 `results/model_comparison_v2/`，每折缩放器只在训练视频组拟合；报告包含 Accuracy、Macro-F1、MAE、RMSE 和 Pearson。无人工词边界真值时，不报告边界误差或 CTC 后验校准率。
 
-硬边界质量由 CTC 发射分数得到，但不视为校准概率。聚合时按样本内有效词的中位分数归一化，并截断到 [0.25, 4]，仅作为相对质量权重。物理覆盖率仍以实际区间交叠计算。B2 的文本后验占据率是期望词活动质量，不能与物理覆盖率互换。
-
-没有人工词边界标注，因此结果不报告边界误差、IoU/MATE 或后验经验校准率。情感探针分数只检查当前特征视图保留标签信息的程度，不是对齐正确性的真值。
-
-## 结果文件
-
-完整结果在 [`results/model_comparison/`](results/model_comparison/)：
-
-- `report.md`：实验设置、主要结果和限制。
-- `comparison_summary.csv`、`fold_metrics.csv`：总体和分折指标。
-- `group_bootstrap_deltas.csv`：相对 B1 的视频组配对 Bootstrap 区间。
-- `oof_predictions.csv`：100 条留组预测。
-- `sample_alignment_summary.csv`、`modality_summary.csv`：100 行样本汇总与 300 行模态明细。
-- `word_alignment_posterior.csv`：逐词硬边界、未校准对齐分数、实际相对质量权重与模型内部边界区间。
-- `split_assignments.csv`、`run_manifest.json`：折号、文件哈希、模型 revision、运行环境和参数。
-- `comparison.png`：OOF 指标图。
+词到原生音频窗和视频帧的 `H_time` 查询矩阵示例可用 `visualize_alignment.py` 重绘；默认展示样本 `-iRBcNs9oI8/8`，也可通过 `--sample-id` 指定样本。图与样本清单写入 `results/`。