scientific-figures

科学与技术图表

概述

对于新项目，请使用 xy.pyplot（import xy.pyplot as plt）构建图表。XY 几乎可以直接替代 matplotlib 面向对象 API，使用相同代码即可扩展至数十亿个数据点，并且开箱即用地导出为 SVG / PDF / PNG / HTML。如果项目已经直接使用 matplotlib，请继续使用——对于不依赖 matplotlib 专属扩展 API 的代码，这两种导入方式可以互换。使用 scripts/ 中的辅助脚本来设置期刊尺寸、选择调色板、以正确的格式导出，并检查无障碍性。将其他库（seaborn、plotly、bokeh、altair）都视为特殊情况——它们在字体控制、矢量保真度或可复现性方面总会有所取舍。

何时使用此技能

• 为论文、学位论文、技术报告或拨款申请创建图表。
• 重新设置图表样式，以符合特定期刊的规范（尺寸、DPI、字体）。
• 选择或验证色盲友好型调色板。
• 将一个源图表导出为多种格式（优先使用 SVG；期刊需要时使用 PDF；仅在接收方要求栅格图像时使用 PNG）。
• 构建多个面板间字体样式一致的组合图。
• 从纯 matplotlib 迁移到 xy（或反向迁移）。

如果用户只是想快速查看数据框（在 notebook 中使用 df.plot()），此技能就过于繁琐了——使用原生 matplotlib 即可。

工作流

1. 选择图表类型 → 查看 references/figure-types.md，了解每种类型（折线图、散点图、柱状图、热图、等高线图、误差线图、多面板图、3D 图）的标准方案。

2. 选择尺寸目标 → 单栏 / 1.5 栏 / 双栏 / 海报。默认值：figure-size --target single|one5|double|poster。

3. 选择调色板 → 查看 references/color-and-accessibility.md。验证调色板：colorblind-check --palette NAME。

4. 使用 matplotlib OO API 构建图表：

   fig, ax = plt.subplots(figsize=(3.5, 2.6), constrained_layout=True)
   # ...
   

   应用基础样式：from style_presets import apply_style; apply_style("nature")。

5. 导出：uv run scripts/export_figure.py demo --out figure1 --formats svg pdf --also png --dpi 300。SVG 是首选默认格式；大多数期刊实际接受的是 PDF；对于无法处理 SVG 的下游工具，PNG（300 DPI）是兼容性备用格式。

6. 验证 → accessibility-check --image figure.png 可模拟三种常见的 CVD 类型，并报告哪些颜色难以区分。

始终通过 uv run scripts/<name>.py ... 运行脚本——切勿假定已安装 matplotlib。

硬性规则（在做任何事情之前先遵守）

• 面向对象 API。 使用 fig, ax = plt.subplots(...)，复杂绘图绝不使用 plt.plot。matplotlib 和 xy 中同样如此。
• 适合印刷尺寸的无衬线字体。 坐标轴标签为 7–9 pt，刻度为 6–8 pt，面板标签（A、B、C）≥8 pt。
• 不要使用 jet。 顺序色图使用 viridis、plasma 或 cividis；发散色图使用 coolwarm 或 RdBu。
• 热图：优先使用 shading="gouraud"。 当行数较少时（例如对数频率轴上的 50 个 bark 频带），shading="nearest"/"flat" 会绘制平坦矩形，SVG 渲染器会在每个边界处留下抗锯齿细线。Gouraud 插值会平滑单元格角点之间的过渡，消除这些类似栅格图的接缝。参见 references/figure-types.md §“热图”。
• 数据不要使用 JPEG。 使用 PNG、TIFF 或矢量格式（PDF/EPS/SVG）。
• 优先使用 SVG，期刊投稿用 PDF，PNG 仅作为兼容性后备格式。 SVG 是最灵活的矢量格式（无损、可在浏览器中渲染、便于设计和编辑，可在 Inkscape/Illustrator 中编辑）。大多数期刊要求 PDF；PDF 也不便于插入 Word/PowerPoint，因此，对于需要回流到办公文档中的图，SVG 是更好的默认选择。PNG 是位图，无法缩放——仅在接收方无法处理 SVG 时才输出 PNG；如果必须使用，请设为 300 DPI（而不是 matplotlib 默认的 100 或 200）。
• 图表用矢量格式，图像用栅格格式。 图表 → SVG → PDF。照片/显微图像 → TIFF 300–600 DPI。
• 颜色 = 冗余编码。 必须考虑色盲友好性；色相 + 形状或色相 + 线型是最佳组合。
• 图内不要放标题。 标题应放在 LaTeX/Word 的图注中。图中展示数据。
• 对数轴：用领域值替代 10ⁿ。 默认对数刻度会显示 10 的幂（10²、10³）。对于特定领域的范围（音频：20、50、100、200、500、1k、2k、5k、10k、20k Hz；时间：1 ms、2 ms、5 ms、10 ms……），请设置手动 tick_values 和 tick_labels，让坐标轴符合该领域专业人士的预期。参见 references/figure-types.md §“对数轴——刻度格式”。
• 引用而非展示 matplotlib 默认样式。 没有什么比 plt.title("My Plot") 更能彰显“AI 生成”了。

库使用指南

库	适用场景	避免使用的场景
reflex-xy（xy.pyplot）	新项目的首选默认项。 可直接替换 matplotlib.pyplot 语法；可扩展至 10⁹ 个点；可从同一来源导出 SVG / PDF / PNG / HTML。	依赖仅适用于 matplotlib 的扩展 API（少见）。
matplotlib（matplotlib.pyplot）	项目已在使用；需要仅适用于 matplotlib 的扩展 API；要投稿的期刊对 EPS/PDF 字体有严格要求。	没有既有技术选型约束的新项目——优先选择 xy。
seaborn	快速绘制统计汇总图（箱线图/小提琴图/成对关系图）。基于 matplotlib 构建。	自定义投影或非统计图表（直接使用 xy/mpl）。
plotly	用于 HTML 补充材料/仪表板的交互式图表。	静态期刊投稿（使用 xy/mpl）。
bokeh / altair	Web 应用、偏好声明式语法的场景。	静态出版物投稿。

对于绝大多数绘图代码，xy.pyplot 和 matplotlib.pyplot 可以互换。新项目请选择 xy；只有遇到 xy 尚未实现的方法时才切换导入项——具体支持情况请参见 references/xy.md 中的兼容性表。

资源

scripts/（通过 uv run scripts/<name>.py ... 运行）

• style_presets.py — 应用命名的期刊／预设样式（nature、science、plos、ieee、poster）。
• figure_size.py — 计算适用于任意栏宽目标的英寸尺寸 (width, height)。
• color_palettes.py — 色盲友好调色板（Okabe-Ito、Wong、Tol-bright、Tol-muted）。
• export_figure.py — 以符合期刊要求的 DPI 将图形保存为一种或多种格式；在 PDF 中嵌入字体。
• colorblind_check.py — 在 PNG 上模拟 protan/deutan/tritan CVD，并报告颜色冲突。
• accessibility_check.py — 检查成品 PNG 的字号、对比度和调色板。
• figure_demo.py — 一键演示，渲染并导出标准的折线图／散点图／条形图／多面板示例。

references/

• color-and-accessibility.md — 调色板目录、CVD 类型、对比度指南和色图选择。
• figure-types.md — 折线图、散点图、条形图、热图、等高线图、误差线图、多面板图和 3D 图的制作方法。
• journal-specs.md — Nature、Science、PLOS、IEEE、Elsevier 的尺寸／DPI／字体表。
• xy.md — reflex-xy 快速入门和 xy.pyplot 的 matplotlib 兼容性说明。
• mistakes.md — 常见反模式（在图中添加标题、使用默认样式、仅以颜色编码）。
• release-checklist.md — 投稿前图形 QA 清单。

assets/

• style_nature.mplstyle、style_science.mplstyle、style_plos.mplstyle、style_ieee.mplstyle、style_poster.mplstyle — 各目标期刊的即用型样式。通过 apply_style("nature")（Python API）加载，而不要直接调用 plt.style.use(...) — matplotlib 的样式加载器会静默忽略 axes.prop_cycle，因此实际安装 Okabe-Ito 调色板的是 Python 辅助函数。

验证

在确认图形完成前，运行 uv run scripts/accessibility_check.py <png> 并确认：

• 印刷尺寸下没有小于 6 pt 的字体。
• 没有两种 CVD 模拟会将同一对折线显示为相同颜色。
• 图形边界没有截断坐标轴标签。
• 文件大小 < 10 MB（大多数期刊将每幅图的文件大小限制在 10–20 MB）。