update

figures/README.md

@@ -0,0 +1,121 @@
+# Figures 说明
+
+本目录里的图片主要由 [plot_benchmark.py](file:///f:/Development/modbus_diffusion/mask-ddpm/mask-ddpm/example/plot_benchmark.py) 生成，用来对比：
+
+- generated：完整管线采样导出的 `example/results/generated.csv`（或 post 后的 `generated_post.csv`）
+- temporal_only：只使用 `temporal.pt`（temporal stage1）的输出
+- real：从 `--reference` 指定的真实训练数据（通常是 `example/config.json` 里的 `data_glob` / `data_path` 指向的 `train*.csv.gz`）
+
+## 通用图例
+
+- 蓝色：模型输出（generated 或 temporal_only，具体看文件名）
+- 红色：真实数据（real）
+- 文件名包含 `with_real`：一定画了红色 real
+- 文件名包含 `generated_only`：只画模型输出（没有 real）
+- 文件名包含 `temporal`：使用 `temporal.pt`（只时序 stage1）
+- 文件名包含 `ref384`：真实数据读取行数被限制到 384（通常用于和 generated 行数对齐）
+
+## 每张图是干嘛的
+
+### 总览与指标
+
+- [benchmark_panel.svg](./benchmark_panel.svg)
+  - 作用：一张图看完整评估概况（四个 panel）
+  - A：连续特征均值的“generated vs real”一致性轮廓（按 real min/max 做范围归一化）
+  - B：每个特征的 KS 分布差异（越小越好）
+  - C：不同训练文件之间的均值漂移（数据集 shift）
+  - D：多随机种子鲁棒性 + 指标历史曲线
+  - 生成：`python example/plot_benchmark.py --figure panel`
+
+- [benchmark_metrics.svg](./benchmark_metrics.svg)
+  - 作用：只看 3 个核心指标在不同 seed 下的均值/方差（越小越好）
+  - 指标：avg_ks（连续）、avg_jsd（离散）、avg_lag1_diff（滞后 1 自相关差异）
+  - 生成：`python example/plot_benchmark.py --figure summary`
+
+- [ranked_ks.svg](./ranked_ks.svg)
+  - 作用：定位“哪些特征拖累了平均 KS”
+  - 左侧：top-K KS 最大的特征
+  - 右侧：移除最差特征后，平均 KS 会下降多少
+  - 生成：`python example/plot_benchmark.py --figure ranked_ks`
+
+### 线图（时间序列形状）
+
+- [lines.svg](./lines.svg)
+  - 作用：对比 generated vs real 的时间序列曲线（选定若干特征）
+  - 输入：`example/results/generated.csv` + `--reference` 指向的 real
+  - 生成：`python example/plot_benchmark.py --figure lines --reference example/config.json`
+
+- [lines_generated_type4.svg](./lines_generated_type4.svg)
+  - 作用：Type4（`P1_PIT02,P2_SIT02,P1_FT03`）的 generated 时间序列（可能不含 real，取决于生成时的参数）
+  - 生成：通常来自 `--figure lines --lines-features ... --out ...`
+
+- [lines_generated_type4_with_real.svg](./lines_generated_type4_with_real.svg)
+  - 作用：Type4 的 generated vs real 时间序列对比
+  - 生成（示例）：
+    - `python example/plot_benchmark.py --figure lines --generated example/results/generated.csv --reference example/config.json --cont-stats example/results/cont_stats.json --lines-features P1_PIT02,P2_SIT02,P1_FT03 --lines-max-rows 2048 --out figures/lines_generated_type4_with_real.svg`
+
+- [lines_temporal.svg](./lines_temporal.svg)
+  - 作用：temporal_only vs real 的时间序列曲线（只时序 stage1）
+  - 输入：`temporal.pt` + `--reference` 指向的 real
+  - 生成：`python example/plot_benchmark.py --figure lines_temporal --reference example/config.json --temporal-pt <path/to/temporal.pt>`
+
+- [lines_temporal_type4.svg](./lines_temporal_type4.svg)
+  - 作用：Type4 的 temporal_only 时间序列（可能不含 real，取决于生成时的参数）
+
+- [lines_temporal_type4_with_real.svg](./lines_temporal_type4_with_real.svg)
+  - 作用：Type4 的 temporal_only vs real 时间序列对比
+
+### 分布图（CDF，对齐边缘/中位数/尾部）
+
+- [cdf_grid.svg](./cdf_grid.svg)
+  - 作用：连续特征的 CDF 网格（generated vs real）
+  - 生成：`python example/plot_benchmark.py --figure cdf_grid --reference example/config.json`
+
+- [cdf_grid_all.svg](./cdf_grid_all.svg)
+  - 作用：`cdf_grid.svg` 的“更多特征/全量特征”版本（通常是 `--cdf-max-features 0` 或更大的上限）
+
+- [cdf_grid_types.svg](./cdf_grid_types.svg)
+  - 作用：按 Type1~Type6 分组的连续特征 CDF（generated vs real）
+  - 生成：`python example/plot_benchmark.py --figure cdf_grid_types --reference example/config.json --type-config example/config.json`
+
+- [cdf_grid_types_generated_only.svg](./cdf_grid_types_generated_only.svg)
+  - 作用：按类型分组的连续特征 CDF，只画 generated（没有 real）
+
+- [cdf_grid_types_generated_with_real.svg](./cdf_grid_types_generated_with_real.svg)
+  - 作用：按类型分组的连续特征 CDF，generated vs real
+
+- [cdf_grid_types_ref384.svg](./cdf_grid_types_ref384.svg)
+  - 作用：按类型分组的连续特征 CDF，但 real 侧只读取 384 行（方便与 generated 行数对齐做“同样本量”对比）
+
+- [cdf_grid_types_temporal.svg](./cdf_grid_types_temporal.svg)
+  - 作用：按类型分组的连续特征 CDF，temporal_only vs real
+
+- [cdf_grid_types_temporal_fast.svg](./cdf_grid_types_temporal_fast.svg)
+  - 作用：`cdf_grid_types_temporal` 的快速版本（通常 seq_len/bins 更小）
+
+- [cdf_grid_types_temporal_ref384.svg](./cdf_grid_types_temporal_ref384.svg)
+  - 作用：按类型分组的 temporal_only CDF，但 real 侧只读取 384 行
+
+- [cdf_grid_types_temporal_with_real.svg](./cdf_grid_types_temporal_with_real.svg)
+  - 作用：按类型分组的 temporal_only vs real CDF
+
+### 离散特征分布
+
+- [disc_grid.svg](./disc_grid.svg)
+  - 作用：离散特征的分布网格（generated vs real）
+  - 生成：`python example/plot_benchmark.py --figure disc_grid --reference example/config.json`
+
+- [disc_points.svg](./disc_points.svg)
+  - 作用：离散特征的“类别占比对比点图”（每个类别两点：generated 与 real）
+  - 生成：`python example/plot_benchmark.py --figure disc_points --reference example/config.json`
+
+### Smoke / 临时检查图
+
+以下 `*_smoke_*.svg` 多数是临时/快速检查用输出（用于验证脚本跑通、参数组合是否正常），不一定是最终报告图：
+
+- [_smoke_cdf_all.svg](./_smoke_cdf_all.svg)
+- [_smoke_cdf_types_temporal_exclude.svg](./_smoke_cdf_types_temporal_exclude.svg)
+- [_smoke_disc_all.svg](./_smoke_disc_all.svg)
+- [_smoke_lines_temporal_cond.svg](./_smoke_lines_temporal_cond.svg)
+- [_smoke_lines_temporal_seeded.svg](./_smoke_lines_temporal_seeded.svg)
+