scipilot-figure-skill 6 个核心脚本 API 深度解析：科研数据可视化开发者完整指南

【免费下载链接】scipilot-figure-skillSciPilot Skills family - Publication-grade scientific figure copilot for Claude Code项目地址: https://gitcode.com/gh_mirrors/sc/scipilot-figure-skill

scipilot-figure-skill 是 SciPilot Skills 家族的科研数据可视化顾问——先剖析数据、再选图、主动拦截画图错误，最后产出 Nature / Science / IEEE / 中文核心级别的出版级图表。本文将带你深度解析 scripts/ 目录下 6 个核心脚本的 API，帮你快速掌握这套「思考-绘制-自检」工作流的底层能力 🎯

一、项目结构与 6 个脚本的定位

项目围绕一条 8 步工作流组织，6 个脚本分别覆盖其中的关键环节：

完整技能定义见 SKILL.md，绘图配方在 references/plot_recipes.md。

快速安装

git clone https://gitcode.com/gh_mirrors/sc/scipilot-figure-skill pip install -r scipilot-figure-skill/requirements.txt

核心依赖仅 matplotlib / seaborn / pandas / numpy / scipy / Pillow（见 requirements.txt），SciencePlots、pypdf 等为可选增强，缺失时功能优雅降级。

二、profile_data.py：数据剖析 API——思考的起点

文件：scripts/profile_data.py

这是「先思考后绘制」的第一环：在画图前先读懂数据。

核心 API：profile_data(source, group_cols)

定义于 profile_data.py#L296。接受三种输入：CSV/Excel 文件路径、pd.DataFrame、或 CSV 字符串内容。返回结构化报告字典，包含：

• columns：每列的类型（连续/分类/有序/时间/布尔/文本）、样本量、缺失率
• 连续列深度指标：均值、中位数、标准差、偏度及可读标签（approximately symmetric/moderately skewed/highly skewed）、IQR 异常值数量、是否建议对数轴（profile_data.py#L158-L163）
• correlation：连续列间 Pearson 相关矩阵，按 |r| 排序并给出强度描述
• group_summary：分组样本量分布，自动标记n<10的小样本组（触发"禁止均值柱"警告）
• suggestions：把数据形态直接翻译成图型建议（折线/箱线/散点/热力图等）
• warnings：缺失率超 20%、小样本组等风险提示

配套 API：render_report(info)

定义于 profile_data.py#L376，将字典渲染为 Markdown 风格人类可读报告，结尾会附一句关键提醒：图型最终必须结合论证目标（详见 references/chart_selection.md）。

💡使用技巧：命令行支持--group多次指定形成交叉分组，--json可输出 JSON 便于程序化处理：

python scripts/profile_data.py results.csv --group group --group condition

三、setup_style.py：期刊样式 API——一键对齐出版规范

文件：scripts/setup_style.py

核心 API：setup_style(journal, lang, use_sciplots, serif_for_zh, constrained_layout)

定义于 setup_style.py#L259，一次调用完成整图视觉基线：

内置预设 JOURNAL_PRESETS 覆盖了期刊最挑剔的细节：Nature 单栏 3.5 in、字号 7pt、pdf.fonttype=42（TrueType 嵌入）、关闭上下边框等——这些正是期刊 PDF 检查器会逐项核实的项。

中文支持两个辅助 API

• configure_chinese_fonts(serif_for_zh)（setup_style.py#L193）：按Noto Sans CJK SC > Source Han Sans SC > SimHei > Microsoft YaHei优先级自动找字体，同时设置axes.unicode_minus=False修复负号方框；找不到任何中文字体时抛出带安装指引的清晰报错
• list_cjk_fonts()：列出系统已识别的中文字体，配合 CLIpython scripts/setup_style.py --list-fonts排查环境问题

四、layout_tools.py：多面板排版 API——子图编号自动对齐

文件：scripts/layout_tools.py

多面板组合图（如 Figure 1 的 4 个 panel）最容易出两类事故：子图 a/b/c 编号乱放、标题标签被裁。这个脚本专治这两件事。

API 1：add_panel_labels(fig, style='nature')

定义于 layout_tools.py#L78。对齐原理很巧妙：每个标签锚定在子图 axes 左上角，再施加统一的 points 物理偏移——同列子图左边缘 x 相同、同行子图上边缘 y 相同，因此标签天然横竖成线，不会因 y 轴刻度宽度不同而错位。支持 6 种期刊惯例（PANEL_STYLES）：

• nature/science：加粗小写a b c
• ieee/paren：(a)(b)(c)
• upper/upper_paren：A B C/(A)(B)(C)

它自动排除 colorbar 和 inset，超过 26 个 panel 会用aa, ab...兜底。

API 2：finalize_figure(fig, prefer='constrained')

定义于 layout_tools.py#L160。出图前的"版面兜底"：优先 constrained_layout，失败自动回退 tight_layout，都失败则不动。返回实际采用的策略（'constrained' | 'tight' | 'none'）。

⚠️调用顺序：建议先finalize_figure(fig)定版、再add_panel_labels(fig)打标——版面稳定后子图位置才不会漂移（对应 references/viz_pitfalls.md 的 P18 坑）。

五、visual_qa.py：视觉自检 API——机器层质检

文件：scripts/visual_qa.py

v2.1 新增的「出图后闭环」中负责确定性问题检测（感知性问题交给 AI 读图，清单在 references/visual_review.md）。

API 1：render_preview(fig_or_path, out_png, dpi=150)

定义于 visual_qa.py#L242。渲染一张中分辨率 PNG 供 AI 用 Read 工具读图复核。支持 Figure 对象或已落盘文件（PDF 需可选的 PyMuPDF）。矢量 PDF 无法直接"看像素重叠"，所以必须经过这一步栅格化。

API 2：audit_layout(fig)

定义于 visual_qa.py#L134，非破坏性检测，返回[(severity, msg), ...]：

配套print_report(issues)输出 PASS/WARN/FAIL 结论。

六、export_figure.py：导出 API——按最终尺寸一次成型

文件：scripts/export_figure.py

核心 API：export_figure(fig, basename, formats, dpi, size_inches, ...)

定义于 export_figure.py#L53，一次调用产出整组文件：

• 多格式：默认pdf + svg + png，支持 tiff/eps；传 JPEG 会被主动跳过并警告（有损压缩不适合线条/文字数据图）
• 强制最终尺寸：size_inches=(3.5, 2.625)直接fig.set_size_inches()，杜绝"Word 里二次缩放导致字号缩水"的经典退稿原因
• 字体嵌入：自动设pdf.fonttype=42、svg.fonttype="none"（文本保留可编辑），多家期刊明确拒收 Type-3 PDF
• 灰度预览：grayscale_preview=True额外生成_grayscale.png（export_figure.py#L128-L147），用 Pillow 转灰度做色盲安全检查，没装 Pillow 会优雅跳过

from export_figure import export_figure paths = export_figure( fig, basename="figs/fig1", formats=["pdf", "svg", "png"], size_inches=(3.5, 2.625), dpi=300, grayscale_preview=True, )

七、check_figure.py：合规审计 API——投稿前最后一道闸

文件：scripts/check_figure.py

只读、非破坏性，逐文件输出问题清单，严重程度分为INFO < WARN < FAIL。

核心 API：check_figure(path, min_dpi=300, target_inches=None)

定义于 check_figure.py#L175，返回(issues, info)。内置三类检查：

• 位图：JPEG 直接 FAIL；读取 DPI 元数据与目标值比较（PIL 会 round-trip 出 299.9994 这类值，内部做了取整容错）；像素/DPI 反推实际英寸并与目标尺寸比对（±0.1 in 容差）
• 矢量 PDF：check_figure.py#L96-L156 用 pypdf 解析字体资源，Type-3 字体直接 FAIL、未嵌入字体 WARN
• SVG：扫描 base64 内嵌位图——一旦误用 imshow 贴图，矢量优势就没了

配套 CLI 与 API

python scripts/check_figure.py figs/*.pdf --min-dpi 300 --strict

--strict下任意 FAIL 返回 exit code 2，可直接接入 CI；Python 端print_report(path, issues, info)打印逐图 verdict（PASS/WARN/FAIL）。

八、六 API 速查表与调用顺序

推荐调用链：profile_data → setup_style → 绘图 → finalize_figure → add_panel_labels → render_preview + audit_layout → export_figure → check_figure。任何一层自检不通过就回改重渲，把问题挡在投稿之前 ✅

九、新手常见问题

Q：中文图出方框怎么办？先setup_style(journal='general', lang='zh')配 CJK 字体；仍出现时audit_layout()会以 FAIL 级拦截，提示是字体未命中还是负号问题（对应 references/viz_pitfalls.md 的 P16）。

Q：可选依赖（SciencePlots / pypdf / PyMuPDF）没装会崩吗？不会。setup_style回退内置预设、check_figure跳过字体嵌入检查、render_preview提示改传 Figure 对象——全部优雅降级并给出提示。

Q：这些脚本能脱离 Skill 单独用吗？完全可以。每个脚本都带 CLI 入口（如python scripts/export_figure.py demo生成演示图、python scripts/layout_tools.py demo验证 2×2 标签对齐），也可作为模块直接 import。

十、延伸阅读

• 图型决策框架：references/chart_selection.md
• 剖析报告解读：references/data_profiling.md
• 期刊栏宽/字号/DPI 速查：references/journal_specs.md
• 18 条科研画图禁忌：references/viz_pitfalls.md
• 投稿前形式合规清单：references/publication_checklist.md

掌握这 6 个 API，就等于拿到了 scipilot-figure-skill 从数据到成图的完整「出版级流水线」——让每张图都经得起审稿人的像素级审视 📊

【免费下载链接】scipilot-figure-skillSciPilot Skills family - Publication-grade scientific figure copilot for Claude Code项目地址: https://gitcode.com/gh_mirrors/sc/scipilot-figure-skill