academic-plotting

面向 ML 论文的学术绘图

为 ML/AI 会议论文生成出版级图表。两种不同的工作流：

1. 示意图（架构、系统设计、工作流、流水线）——通过 Gemini 进行 AI 图像生成
2. 数据图表（折线图、条形图、散点图、热力图、消融实验）——使用 matplotlib/seaborn

何时使用哪种工作流

图表类型	工具	原因
架构图 / 系统示意图	Gemini（工作流 1）	适合包含方框、箭头、标签的复杂空间布局
工作流 / 流水线 / 生命周期	Gemini（工作流 1）	适合包含连接关系的多步骤流程
条形图、折线图、散点图	matplotlib（工作流 2）	数值数据精确、可复现
热力图、混淆矩阵	matplotlib/seaborn（工作流 2）	适合结构化网格数据
以图表形式呈现的消融表	matplotlib（工作流 2）	可使用分组条形图或折线对比图
饼图 / 环形图	matplotlib（工作流 2）	适合比例数据（在 ML 论文中应谨慎使用）
训练曲线	matplotlib（工作流 2）	展示随步数/轮次变化的损失/准确率

经验法则：如果图表有数值坐标轴，使用 matplotlib。如果图表包含方框和箭头，使用 Gemini。

---

步骤 0：上下文分析与提取

用户通常会提供以下某种输入，而不是现成的规格说明：

输入类型	示例	要提取的内容
完整论文 / 章节草稿	“这是我们的方法部分……”	系统组件、它们之间的关系、数据流
描述段落	“我们的系统有三层……”	关键实体、层级结构、连接关系
原始结果 / 数据表	“MMLU：85.2，HumanEval：72.1……”	指标、方法、对比结构
CSV / JSON 数据	实验日志文件	变量、趋势、分组维度
模糊请求	“为概览绘制一张图”	阅读论文相关上下文以推断内容

提取工作流

对于示意图（研究背景 → 架构图）：

1. 阅读提供的上下文——论文章节、摘要或描述段落
2. 识别视觉实体——主要组件/模块/阶段有哪些？
   • 查找：代表系统组成部分的名词、具名模块、层、阶段
   • 统计数量：如果顶层实体超过 8 个，考虑按部分分组
3. 识别关系——组件之间如何连接？
   • 查找：描述数据流的动词（“发送到”“查询”“馈入”）
   • 分类：数据流（实线箭头）、控制流（灰色）、错误路径（红色虚线）
4. 确定布局模式：
   • 顺序流水线 → 从左到右排列
   • 分层架构 → 水平带状结构垂直堆叠
   • 星型结构 → 中心节点向外辐射连接
   • 层级结构 → 自上而下的树形布局
5. 分配颜色——每个逻辑组/层使用一种强调色
6. 准确写出每个标签——从论文文本中提取准确术语

对于数据图表（结果 → 图表）：

1. 阅读提供的数据——表格、包含数值的段落、CSV 或 JSON
2. 识别维度：
   • 要比较什么？（方法、模型、配置）→ 分类轴
   • 指标是什么？（准确率、损失、延迟、F1）→ 数值轴
   • 是否有时间/步数维度？→ 折线图
   • 是否有多个指标？→ 多面板图或分组条形图
3. 自动选择图表类型，优先级如下：
   • 存在步数/时间轴 → 折线图
   • 比较 N 种方法在 M 个基准上的表现 → 分组条形图
   • 单项排名 → 水平条形图（排行榜）
   • 两个连续变量之间的相关性 → 散点图
   • 数值方阵 → 热力图
   • 比例分解 → 堆叠条形图（避免使用饼图）
4. 确定图表尺寸——根据数据密度选择单栏或全宽
5. 突出显示“我们的方法”——识别论文的贡献项，并为其指定一种独特颜色

自动检测示例

上下文 → 图示：“我们的系统包含 Planner、Executor 和 Verifier。Planner 向 Executor 发送计划，Executor 向 Verifier 返回结果；如果失败，Verifier 会向 Planner 反馈。” → 3 个实体，循环布局，虚线反馈箭头 → 工作流 1（Gemini）

数据 → 图表：“GPT-4：MMLU 86.4，HumanEval 67.0。我们的模型：88.1，71.2。Llama-3：79.3，62.1。” → 3 种方法 × 2 个基准 → 工作流 2（分组柱状图），用珊瑚色突出显示“我们的模型”

---

工作流 1：架构与系统图示（AI 图像生成）

使用 Gemini 3 Pro Image Preview 生成图示。请先选择视觉风格——这是决定图示看起来专业还是普通的最大因素。

视觉风格

每篇论文选择一种风格（所有图示应保持一致）：

风格 A：“Sketch / 简笔画”（手绘）

温暖、亲切、令人印象深刻。非常适合概览图和系统介绍。看起来像是经过设计师润色的白板草图。

VISUAL STYLE — HAND-DRAWN SKETCH:
- Slightly irregular, hand-drawn line quality — lines wobble gently, not perfectly straight
- Rounded, soft shapes with visible pen strokes (like drawn with a thick felt-tip marker)
- Warm off-white background (#FAFAF7), NOT pure white
- Fill colors are soft watercolor-like washes: muted blue (#D6E4F0), soft peach (#F5DEB3),
  light sage (#D4E6D4), pale lavender (#E6DFF0)
- Borders are dark charcoal (#2C2C2C) with 2-3px line weight, slightly uneven
- Arrows are hand-drawn with slight curves, ending in simple open arrowheads (not filled triangles)
- Text uses a rounded sans-serif font (like Comic Neue or Architects Daughter feel)
- Small doodle-style icons inside boxes: a tiny gear ⚙ for processing, a lightbulb 💡 for ideas,
  a magnifying glass 🔍 for search — rendered as simple line drawings, NOT emoji
- Overall feel: a carefully drawn whiteboard diagram, clean but with personality
- NO clip art, NO stock icons, NO photorealistic elements

风格 B：“Modern Minimal”（简洁醒目）

自信、权威。最适合注重精确性的技术方法图。

VISUAL STYLE — MODERN MINIMAL:
- Ultra-clean geometric shapes with crisp edges
- Bold color blocks as backgrounds for sections — NOT just accent bars, but full section fills
  using desaturated tones: slate blue (#E8EDF2), warm sand (#F5F0E8), cool mint (#E8F2EE)
- Component boxes have ROUNDED CORNERS (12px radius), NO visible border — they float on
  the section background using subtle shadow (1px, 4px blur, rgba(0,0,0,0.06))
- ONE accent color per section used sparingly on key elements: Deep blue (#2563EB),
  Emerald (#059669), Amber (#D97706), Rose (#E11D48)
- Arrows are thin (1.5px), dark gray (#6B7280), with small filled circle at source
  and clean arrowhead at target — NOT thick colored arrows
- Typography: Inter or system sans-serif, title 600 weight, body 400 weight
- Labels INSIDE boxes, not beside them
- Generous whitespace — at least 24px between elements
- NO decorative elements, NO icons — let the structure speak

风格 C：“Illustrated Technical”（图标丰富）

引人入胜、易于理解。适合教程风格的论文，以及需要一目了然的图示。

VISUAL STYLE — ILLUSTRATED TECHNICAL:
- Each major component has a small MEANINGFUL ICON drawn in a consistent line-art style
  (single color, 2px stroke, ~24x24px): brain icon for reasoning, database cylinder for storage,
  arrow-loop for iteration, network nodes for communication
- Components sit inside soft rounded rectangles with a LEFT COLOR STRIP (4px wide)
- Background is pure white, but each logical group has a very faint colored region behind it
  (#F8FAFC for blue group, #FFF8F0 for orange group)
- Connections use CURVED bezier paths (not straight lines), colored by SOURCE component
- Key data flows are THICKER (3px) than secondary flows (1px, dashed)
- Small annotation badges on arrows: "×N" for repeated operations, "optional" in italics
- Title labels are ABOVE each section in small caps, letter-spaced
- Overall: like a well-designed API documentation diagram

风格 D：“Accent Bar”（经典学术风格）

默认的学术风格。适用于任何投稿场合，也适合灰度打印。

VISUAL STYLE — CLASSIC ACCENT BAR:
- Horizontal section bands stacked vertically, pale gray (#F7F7F5) fill
- Thick colored LEFT ACCENT BAR (8px) distinguishes each section
- Content boxes: white fill, thin #DDD border, 4px rounded corners
- Section palette: Blue #4A90D9, Teal #5BA58B, Amber #D4A252, Slate #7B8794
- Sans-serif typography (Helvetica/Arial), bold titles, regular body
- Colored arrows match their SOURCE section
- Clean, flat, zero decoration

精选配色方案

“Ocean Dusk”（专业、沉稳——默认推荐）： #264653 深青色，#2A9D8F 青绿色，#E9C46A 金色，#F4A261 沙橙色，#E76F51 烧珊瑚色

“Ink & Wash”（适用于简笔画风格）： #2C2C2C 炭墨色，#D6E4F0 淡洗蓝，#F5DEB3 淡洗麦色，#D4E6D4 淡洗鼠尾草绿，#E6DFF0 淡洗薰衣草色

“Nord”（适用于现代简约风格）： #2E3440 极夜色，#5E81AC 霜蓝色，#A3BE8C 极光绿色，#EBCB8B 极光黄色，#BF616A 极光红色

“Okabe-Ito”（通用色盲友好配色，数据图表必用）： #E69F00 橙色，#56B4E9 天蓝色，#009E73 绿色，#F0E442 黄色，#0072B2 蓝色，#D55E00 朱红色，#CC79A7 粉色

检查清单

• 从上下文中提取信息：阅读论文/描述，识别实体及其关系
• 选择视觉风格（A/B/C/D）——与论文的基调和投稿场合相符
• 选择配色方案——或使用与论文现有图示一致的配色
• 获取 Gemini API 密钥（GEMINI_API_KEY 环境变量）
• 编写详细提示词：风格说明 + 布局 + 连接关系 + 限制条件
• 在 figures/gen_fig_<name>.py 生成脚本，并运行 3 次
• 检查并选出最佳结果，保存为 figures/fig_<name>.png

提示词结构（6 个部分）

每个 Gemini 提示词都必须按顺序包含以下部分：

1. FRAMING (5 lines): "Create a [STYLE_NAME]-style technical diagram for a
   [VENUE] paper. The diagram should feel [ADJECTIVES]..."

2. VISUAL STYLE (20-30 lines): Copy the full style block from above (A/B/C/D).
   This is the most important section — it determines the entire visual character.

3. COLOR PALETTE (10 lines): Exact hex codes for every color used.

4. LAYOUT (50-150 lines): Every component, box, section — exact text, spatial
   arrangement, and grouping. Be exhaustively specific.

5. CONNECTIONS (30-80 lines): Every arrow individually — source, target, style,
   label, routing direction.

6. CONSTRAINTS (10 lines): What NOT to include. Adapt per style — e.g., sketch
   style allows slight irregularity but still no clip art.

生成脚本模板

#!/usr/bin/env python3
"""Generate [FIGURE_NAME] diagram using Gemini image generation."""
import os, sys, time
from google import genai

API_KEY = os.environ.get("GEMINI_API_KEY")
if not API_KEY:
    print("ERROR: Set GEMINI_API_KEY environment variable.")
    print("  Get a key at: https://aistudio.google.com/apikey")
    sys.exit(1)

MODEL = "gemini-3-pro-image-preview"
OUTPUT_DIR = os.path.dirname(os.path.abspath(__file__))
client = genai.Client(api_key=API_KEY)

PROMPT = """
[PASTE YOUR 6-SECTION PROMPT HERE]
"""

def generate_image(prompt_text, attempt_num):
    print(f"\n{'='*60}\nAttempt {attempt_num}\n{'='*60}")
    try:
        response = client.models.generate_content(
            model=MODEL,
            contents=prompt_text,
            config=genai.types.GenerateContentConfig(
                response_modalities=["IMAGE", "TEXT"],
            ),
        )
        output_path = os.path.join(OUTPUT_DIR, f"fig_NAME_attempt{attempt_num}.png")
        for part in response.candidates[0].content.parts:
            if part.inline_data:
                with open(output_path, "wb") as f:
                    f.write(part.inline_data.data)
                print(f"Saved: {output_path} ({os.path.getsize(output_path):,} bytes)")
                return output_path
            elif part.text:
                print(f"Text: {part.text[:300]}")
        print("WARNING: No image in response")
        return None
    except Exception as e:
        print(f"ERROR: {e}")
        return None

def main():
    results = []
    for i in range(1, 4):
        if i > 1:
            time.sleep(2)
        path = generate_image(PROMPT, i)
        if path:
            results.append(path)
    if not results:
        print("All attempts failed!")
        sys.exit(1)
    print(f"\nGenerated {len(results)} attempts. Review and pick the best.")

if __name__ == "__main__":
    main()

关键规则

• 始终尝试 3 次——不同运行结果的质量差异可能很大
• 必须包含风格说明——否则 Gemini 会默认生成普通的企业风格
• 切勿将 API 密钥硬编码——使用 os.environ.get("GEMINI_API_KEY")
• 保存生成脚本——可复现性至关重要
• 精确指定每个标签——Gemini 可能会拼错或重新排列文本

各风格的完整提示词示例：参见 references/diagram-generation.md

---

工作流 2：数据驱动图表（matplotlib/seaborn）

适用于包含数值数据、坐标轴或定量比较的图示。

检查清单

• 从上下文中提取信息：解析结果/数据，识别方法、指标和比较结构
• 根据数据维度自动选择图表类型（参见下方决策指南）
• 准备数据（CSV、字典或内联数组）
• 应用出版级样式设置（字体、颜色、尺寸）
• 使用醒目颜色突出显示“我们的方法”
• 同时导出 PDF（矢量）和 PNG（300 DPI）
• 检查 LaTeX 字体兼容性
• 将脚本保存在 figures/gen_fig_<name>.py

图表类型决策指南

数据模式	最佳图表	说明
随时间/步骤变化的趋势	折线图	训练曲线、缩放定律
比较类别	分组柱状图	模型比较、消融实验
分布	小提琴图 / 箱线图	不同方法的分数分布
相关性	散点图	嵌入分析、指标相关性
网格值	热力图	注意力图、混淆矩阵
整体中的部分	堆叠柱状图（而非饼图）	ML 论文中优先使用堆叠柱状图，而非饼图
多种方法、单个指标	水平柱状图	排行榜式比较

出版物样式模板

import matplotlib.pyplot as plt
import numpy as np

# --- Publication defaults (polished, not generic) ---
plt.rcParams.update({
    "font.family": "serif", "font.serif": ["Times New Roman", "DejaVu Serif"],
    "font.size": 10, "axes.titlesize": 11, "axes.titleweight": "bold",
    "axes.labelsize": 10, "legend.fontsize": 8.5, "legend.frameon": False,
    "figure.dpi": 300, "savefig.dpi": 300, "savefig.bbox": "tight",
    "axes.spines.top": False, "axes.spines.right": False,
    "axes.grid": True, "grid.alpha": 0.15, "grid.linestyle": "-",
    "lines.linewidth": 1.8, "lines.markersize": 5,
})

# --- "Ocean Dusk" palette (professional, distinctive, colorblind-safe) ---
COLORS = ["#264653", "#2A9D8F", "#E9C46A", "#F4A261", "#E76F51",
          "#0072B2", "#56B4E9", "#8C8C8C"]
OUR_COLOR = "#E76F51"       # coral — warm, stands out
BASELINE_COLOR = "#B0BEC5"  # cool gray — recedes
FIG_SINGLE, FIG_FULL = (3.25, 2.5), (6.75, 2.8)

常见图表模式

折线图（训练曲线） — 带标记和置信带：

fig, ax = plt.subplots(figsize=FIG_SINGLE)
markers = ["o", "s", "^", "D", "v"]
for i, (method, (mean, std)) in enumerate(results.items()):
    color = OUR_COLOR if method == "Ours" else COLORS[i]
    ax.plot(steps, mean, label=method, color=color,
            marker=markers[i % 5], markevery=max(1, len(steps)//8),
            markersize=4, zorder=3)
    ax.fill_between(steps, mean - std, mean + std, color=color, alpha=0.12)
ax.set_xlabel("Training Steps")
ax.set_ylabel("Accuracy (%)")
ax.legend(loc="lower right")
fig.savefig("figures/fig_training.pdf")
fig.savefig("figures/fig_training.png", dpi=300)

分组柱状图（消融实验） — 带数值标签：

fig, ax = plt.subplots(figsize=FIG_FULL)
x = np.arange(len(categories))
n = len(methods)
width = 0.7 / n
for i, (method, scores) in enumerate(methods.items()):
    color = OUR_COLOR if method == "Ours" else COLORS[i]
    offset = (i - n / 2 + 0.5) * width
    bars = ax.bar(x + offset, scores, width * 0.9, label=method, color=color,
                  edgecolor="white", linewidth=0.5)
    for bar, s in zip(bars, scores):
        ax.text(bar.get_x() + bar.get_width()/2, bar.get_height() + 0.3,
                f"{s:.1f}", ha="center", va="bottom", fontsize=7, color="#444")
ax.set_xticks(x)
ax.set_xticklabels(categories)
ax.set_ylabel("Score")
ax.legend(ncol=min(n, 4))
fig.savefig("figures/fig_ablation.pdf")

热力图 — 使用发散色图和简洁边框：

import seaborn as sns
fig, ax = plt.subplots(figsize=(4, 3.5))
sns.heatmap(matrix, annot=True, fmt=".2f", cmap="YlOrRd", ax=ax,
            cbar_kws={"shrink": 0.75, "aspect": 20},
            linewidths=1.5, linecolor="white",
            annot_kws={"size": 8, "weight": "medium"})
ax.set_xlabel("Predicted")
ax.set_ylabel("Actual")
fig.savefig("figures/fig_confusion.pdf")

水平柱状图（排行榜） — 突出显示“我们的方法”：

fig, ax = plt.subplots(figsize=FIG_SINGLE)
y_pos = np.arange(len(models))
colors = [BASELINE_COLOR] * len(models)
colors[our_idx] = OUR_COLOR
bars = ax.barh(y_pos, scores, color=colors, height=0.55,
               edgecolor="white", linewidth=0.5)
ax.set_yticks(y_pos)
ax.set_yticklabels(models)
ax.set_xlabel("Accuracy (%)")
ax.invert_yaxis()
for bar, s in zip(bars, scores):
    ax.text(bar.get_width() + 0.3, bar.get_y() + bar.get_height()/2,
            f"{s:.1f}", va="center", fontsize=8, color="#444")
fig.savefig("figures/fig_leaderboard.pdf")

完整模式库（缩放定律、小提琴图、多面板、雷达图）：参见 references/data-visualization.md

---

出版物样式速查

会议	单栏	通栏	字体
NeurIPS	5.5 in	5.5 in	Times
ICML	3.25 in	6.75 in	Times
ICLR	5.5 in	5.5 in	Times
ACL	3.3 in	6.8 in	Times
AAAI	3.3 in	7.0 in	Times

始终导出 PDF，以获得矢量图质量。仅对 AI 生成的示意图使用 PNG。

特定会议的详情、LaTeX 集成、字体匹配、无障碍检查清单：参见 references/style-guide.md

---

常见问题

问题	解决方案
LaTeX 中的字体显示异常	导出 PDF，设置 text.usetex=True，或使用 font.family=serif
图形超出栏宽	检查会议的宽度限制，使用以英寸为单位的 figsize
打印时颜色难以区分	使用色盲友好调色板 + 不同的线型/标记
Gemini 拼错标签	在提示词中准确写出每个标签，并添加“SPELL EXACTLY”约束
Gemini 忽略样式	添加更多负向约束，更具体地指定十六进制颜色
PDF 中的图形模糊	导出为 PDF（矢量图），而非 PNG；或者将 PNG 的分辨率设为 300+ DPI
图例与数据重叠	使用 bbox_to_anchor、loc="upper left" 或外置图例
刻度标签过多	使用 ax.xaxis.set_major_locator(MaxNLocator(5))

何时使用及替代方案

需求	此技能	替代方案
架构图	Gemini 生成	TikZ（手动）、draw.io（交互式）、Mermaid（简单）
数据图表	matplotlib/seaborn	Plotly（交互式）、R/ggplot2（侧重统计）
完整论文写作	与 ml-paper-writing 一起使用	—
海报插图	更大字体、更宽版面	latex-posters 技能
演示文稿插图	更大的文字、更少的细节	PowerPoint/Keynote 导出

---

快速参考：文件命名约定

figures/
├── gen_fig_<name>.py      # Generation script (always save for reproducibility)
├── fig_<name>.pdf         # Final vector output (for LaTeX)
├── fig_<name>.png         # Raster output (300 DPI, for AI-generated or fallback)
└── fig_<name>_attempt*.png # Gemini attempts (keep for comparison)