PlotKit：论文风格可视化模板（Matplotlib + Seaborn）

项目目标

PlotKit 是一个模板化、论文友好的 Python 可视化工具箱，目标是：

• 统一科研 / 建模 / 工程项目中的图像风格
• 覆盖常见论文图类型：
  • 折线图（趋势 / 对比）
  • 条形图（最终结果）
  • 散点图（trade-off）
  • 热力图（蓝色系参数扫描）
  • 稳定性图（box / violin）
  • 饼图 / 环形图（组成比例，克制使用）
• 提供高级标注工具：
  • 事件虚线（干预 / 切换）
  • 纯色区间高亮
  • 渐变衰减背景（恢复期 / 影响减弱）
  • 箭头注释、时间区间标注
• 方便将画图需求直接交给 agent，由 agent 基于模板自动生成符合要求的图片

---

目录结构

plotkit/
  README.md
  requirements.txt
  figs/                      # 图片输出目录（demo 会生成）
  plots/
    __init__.py
    plot_style.py            # 全局风格、保存函数、语义配色
    annotations.py           # 事件线 / 区间 / 渐变衰减 / 箭头标注
    line.py                  # 折线图模板
    bar.py                   # 条形图模板
    scatter.py               # 散点图（trade-off）
    heatmap.py               # 热力图（蓝色系）
    box_violin.py            # 稳定性箱线图
    pie_donut.py             # 饼图 / 环形图（克制使用）
  scripts/
    demo_all.py              # 一键生成所有示例图

---

环境安装

pip install -r requirements.txt

依赖库：

• matplotlib
• seaborn
• numpy
• pandas

---

快速开始

生成所有示例图（推荐先跑一次）

python scripts/demo_all.py

运行后：

• 所有示例图片会生成在 figs/ 目录下
• 每张图同时输出：
  • *.pdf（论文 / 矢量）
  • *.png（预览 / 投稿系统）

---

基本使用方式

1. 启用统一论文风格

from plots import set_paper_style
set_paper_style()

建议在每个画图脚本最开始调用一次。

---

2. 折线图（baseline 灰化，ours 突出）

import matplotlib.pyplot as plt
from plots import plot_line, save_fig

fig, ax = plt.subplots(figsize=(5.2, 3.2))
plot_line(
    ax,
    x,
    baseline,
    ours,
    ylabel="PPL (lower is better)",
    title="Ours improves perplexity"
)
save_fig(fig, "figs/my_line")

---

3. 条形图（最终结果对比）

from plots import plot_bar

plot_bar(
    ax,
    df_bar,   # columns: method, metric
    ylabel="Metric (lower is better)"
)

---

4. 散点图（trade-off）

from plots import plot_tradeoff_scatter

plot_tradeoff_scatter(
    ax,
    df_scatter,  # columns: runtime_ms, metric, method
)

---

5. 热力图（参数扫描，蓝色系）

from plots import plot_heatmap

plot_heatmap(
    ax,
    data2d,
    row_labels=strides,
    col_labels=windows,
    cmap="Blues"
)

---

6. 稳定性 / 多次实验分布

from plots import plot_stability_box

plot_stability_box(
    ax,
    df_box,   # columns: method, metric
)

---

7. 饼图 / 环形图（组成比例）

from plots import plot_donut

plot_donut(
    ax,
    labels,
    values,
    title="Biomass composition"
)

注意：饼图只建议用于“组成 / 占比”，不用于性能对比。

---

高级标注（论文常用）

事件虚线（干预 / 切换时刻）

from plots import add_event_line
add_event_line(ax, t_event)

---

渐变衰减区（恢复期 / 影响逐渐减弱）

from plots import add_fade_region

add_fade_region(
    ax,
    x_start=t_event,
    x_end=t_event + 80,
    cmap="Greens",           # Greens / Blues / Oranges
    alpha_start=0.22,
    alpha_end=0.0
)

建议在曲线画完后再调用（确保 y 轴范围已稳定）。

---

箭头注释（关键变化）

from plots import add_arrow_label

add_arrow_label(
    ax,
    "K restored",
    xy=(x0, y0),
    xytext=(x1, y1),
    color="green"
)

---

时间区间标注（T1 / T2 / T3）

from plots import add_interval

add_interval(
    ax,
    x1=120,
    x2=260,
    y=7000,
    label="T1 = 54"
)

---

数据接口约定（强烈建议遵守）

• 折线图
  x, baseline, ours → 等长一维数组
• 条形图
  DataFrame 两列：method, metric
• 散点图
  DataFrame 三列：runtime_ms, metric, method
• 热力图
  data2d（二维数组）+ 可选 row_labels, col_labels
• 稳定性
  DataFrame 两列：method, metric

---

给 Agent 的任务模板（直接复制）

你现在在 plotkit 仓库中工作，请基于 plots/ 下的模板生成指定图片。

输入数据：
- 数据文件路径：<PATH>
- 数据格式与列名：<说明>
- 需要生成的图类型：<line / bar / scatter / heatmap / box / donut>
- 图片输出路径：figs/<name>

风格与规范要求：
- 必须调用 set_paper_style()
- baseline 使用灰色，ours 使用 COLORS["ours"]
- 不反转 y 轴，y 轴写清楚 “lower is better”（如适用）
- 热力图必须使用蓝色系（cmap="Blues"）
- 若存在干预 / 恢复期：
  - 使用 add_event_line()
  - 使用 add_fade_region() 表示渐变衰减区
- 输出图片需同时生成 pdf 与 png

请输出：
- 可运行脚本 scripts/make_my_figs.py
- 生成的图片文件

---

常见注意事项

• 渐变衰减区不要太浓（alpha_start ≤ 0.3）
• legend 不要遮挡曲线，必要时移动或 frameon=False
• 图像结论应尽量体现在标题或注释中
• 同一论文中保持颜色语义一致

---

推荐使用场景

• 科研论文（物理 / AI / 系统）
• 实验报告 / 技术报告
• agent 自动生成图像流水线