scientific-figure

科学图表

按精确的期刊尺寸（mm/pt）制作可供发表的多面板图表，在导出前根据期刊最低要求检查字体大小，并输出期刊接受且无需调整大小的 PDF/PNG。

此技能的用途

之前的 react-pdf 工作流存在两个结构性问题：

1. 排版未遵循实际尺寸。 Flexbox 布局在渲染过程中会以不易察觉的方式改变尺寸。
2. 字体缩小到低于可读阈值。 内容溢出时，react-pdf 会统一缩放整张图，有时会将坐标轴标签缩小到 4 pt 以下。

此技能将取代该工作流。面板按精确的 mm 坐标放置，文本保留为 SVG <text> 元素，以便在导出前检查字体大小；如果字体低于最低要求，验证器会单独缩放面板，而不是缩放整张图。

流程

1. Plan        2. Build elements        3. Compose          4. Validate fonts     5. Export
   (journal      (matplotlib/seaborn      (svgutils, at        (per-element pt vs    (Inkscape if
    size, panel   per panel; SVG out;     exact mm/pt;         journal minimum;      present;
    grid)         optional icons)         text preserved)      rescale panel if      cairosvg
                                                               below minimum)        otherwise)

每个步骤都通过 uv run --with 即时执行，因此技能本身无需永久安装任何内容。

步骤 1：规划图表

开始生成前，先确定以下内容：

• 目标期刊 — 决定画布宽度。完整表格请参阅 references/journal-specs.md；以下汇总了最常见的四种期刊。
• 面板网格 — 1x1、1x2、2x2、上方宽面板 + 子面板，或自定义 mm 坐标。
• 配色方案 — 从 references/color-palettes.md 中选择，并在所有面板中保持一致。

期刊宽度／最小字体速查表

期刊	单栏	双栏	正文字体最小值	备注
Nature	89 mm	183 mm	5 pt	面板标签为 8 pt
Science	55 mm	120 mm	6 pt	首选 Myriad/Helvetica
Cell	85 或 112 mm	174 mm	6 pt	高度最多 225 mm
PNAS	87 mm	180 mm	6 pt	标签高度不得低于 2 mm

步骤 4 中的验证器会强制执行这些要求。尽早选择期刊，以便验证器及时发出警告。

步骤 2：构建元素

每个面板都单独生成为 SVG。常见来源：

• 绘图： 使用 matplotlib/seaborn，并以 bbox_inches='tight', transparent=True, format='svg' 保存。有关库的选择流程和 SciencePlots 配方，请参阅 figures:plot-styling 技能。
• 图标： 使用 figures:transparent-icons 技能生成透明 PNG。
• 示意图： 对于新的 Python 驱动项目，使用 figures:svg-primitives（自动适配框、经过验证的箭头、分层 z-order）；手工编写的 SVG 样式请参阅 figures:svg-figure。

将每个元素保存到工作目录（通常为 panels/），然后在步骤 3 中组合。

步骤 3：组合图表

组合器基于 svgutils 构建（MIT 许可证；uv run --with svgutils）。它会按精确的 mm 坐标放置面板，并将文本保留为可检查的 SVG <text> 元素。

有两种组合方式：使用 scripts/compose.py 中的 Figure 辅助工具（适用于大多数情况），或直接使用 svgutils.compose 以获得完整控制。

配方 A：辅助工具（推荐）

uv run --with svgutils --with lxml python scripts/compose.py panels-config.json -o figure.svg

panels-config.json 架构：

{
  "width_mm": 183,
  "height_mm": 120,
  "journal": "nature",
  "panels": [
    {"id": "A", "src": "panels/spectrum.svg", "x_mm": 0,  "y_mm": 0, "scale": 0.5, "label": "A"},
    {"id": "B", "src": "panels/topomap.svg",  "x_mm": 92, "y_mm": 0, "scale": 0.5, "label": "B"},
    {"id": "C", "src": "panels/timecourse.svg", "x_mm": 0, "y_mm": 60, "scale": 1.0, "label": "C", "width_mm": 183}
  ]
}

面板标签（A、B、C）以 12 pt 粗体无衬线字体放置在各面板的左上角。

配方 B：直接使用 svgutils（完整控制）

from svgutils.compose import Figure, SVG, Panel, Text

fig = Figure(
    "183mm", "120mm",
    Panel(
        SVG("panels/spectrum.svg").scale(0.5),
        Text("A", 5, 15, size=12, weight="bold"),
    ).move(0, 0),
    Panel(
        SVG("panels/topomap.svg").scale(0.5),
        Text("B", 5, 15, size=12, weight="bold"),
    ).move(92, 0),
)
fig.save("figure.svg")

有关相关模式（面板缩放、标签放置、比例尺、多面板网格实用工具），请参阅 references/composition-workflow.md。

步骤 4：导出前验证字体

此步骤可避免期刊拒稿。运行：

uv run --with lxml python scripts/validate_fonts.py figure.svg --journal nature

验证器会解析每个带有 font-size 的 <text> 和 <tspan> 元素，遍历累积的变换堆栈，以计算最终物理尺寸下的有效字号，并报告任何小于期刊最低要求的情况。输出为 JSON：

{
  "svg": "figure.svg",
  "journal": "nature",
  "minimum_pt": 5.0,
  "checked_count": 47,
  "skipped_count": 0,
  "issue_count": 1,
  "issues": [
    {
      "text": "Frequency (Hz)",
      "specified_pt": 9.0,
      "effective_pt": 4.5,
      "scale_x": 0.5,
      "scale_y": 0.5,
      "minimum_pt": 5.0,
      "tag_id": ""
    }
  ]
}

skipped_count 统计无法解析出 font-size 的文本元素数量（例如由 CSS 类选择器设置或继承样式的元素）。退出代码：0 表示无问题，1 表示发现问题，2 表示脚本错误（SVG 格式错误、文件缺失）。

如果问题出在某个面板上（其 .scale() 过小），有三种解决方法：

1. 放大该面板（同时缩小其他面板），而不是接受过小的文字。
2. 增大源图的字号，确保即使面板缩放为 0.5 也能通过验证（例如，源图为 12 pt，在 0.5 倍缩放下为 6 pt，达到 Science 的 6 pt 最低要求）。
3. 改用更大的画布（例如，从 1 栏升级到 1.5 栏）。

完整原理和说明请参阅 references/font-validation.md。

步骤 5：导出为 PDF/PNG

uv run --with cairosvg python scripts/export.py figure.svg --out figure.pdf --dpi 300

export.py 会在运行时检测 $PATH 中是否有 Inkscape。若存在，Inkscape 会生成保真度最高的 PDF（文本仍为文本，字体经过子集化）。若不存在，脚本会回退到 cairosvg，并在 stderr 中发出警告：未安装字体的文本可能会转换为路径或被跳过。

安装 Inkscape（一次性，推荐）

brew install inkscape    # macOS
sudo apt install inkscape # Debian/Ubuntu

brew install inkscape 只需运行一行命令，约需 200 MB 的一次性空间；安装后脚本会自动检测。无需安装 Inkscape 也可使用 cairosvg 回退方案，但如果未安装期刊要求的字体，生成的 PDF 保真度会较低。

图注指南

生成图注时：

• 以简洁标题开头（加粗，用一个句子）。
• 描述每个面板：“(A) 描述。(B) 描述。(C) 描述。”
• 首次出现时定义所有缩写（例如，“脑电图（EEG）”）。
• 说明样本量、统计检验方法和误差线的含义。
• 如有比例尺，注明其数值。

质量保证

figures:figure-qa Agent 会主动检查合成后的 SVG，验证几何正确性、对齐、配色方案合规性和标签可读性。该 Agent 会在后台调用 validate_fonts.py 检查字号，同时执行 SVG 分支的配色方案和几何检查。

更多资源

• references/composition-workflow.md — svgutils 模式和惯用写法
• references/font-validation.md — pt 最低字号机制、变换堆栈数学
• references/journal-specs.md — 期刊尺寸和字体规则完整表格
• references/color-palettes.md — 色盲友好配色方案（Wong、Okabe-Ito、viridis、Crameri）
• scripts/compose.py — svgutils 合成器（CLI + 库）
• scripts/validate_fonts.py — 字号验证器
• scripts/export.py — Inkscape/cairosvg 导出器
• examples/two-column-figure.py — 端到端工作示例（matplotlib 面板 → 合成 → 验证 → 导出）