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-skillscipilot-figure-skill 是 SciPilot Skills 家族的科研数据可视化顾问——先剖析数据、再选图、主动拦截画图错误最后产出 Nature / Science / IEEE / 中文核心级别的出版级图表。本文将带你深度解析 scripts/ 目录下 6 个核心脚本的 API帮你快速掌握这套「思考-绘制-自检」工作流的底层能力 一、项目结构与 6 个脚本的定位项目围绕一条 8 步工作流组织6 个脚本分别覆盖其中的关键环节工作流步骤脚本核心 API① 剖析数据profile_data.pyprofile_data()/render_report()④ 配样式setup_style.pysetup_style()⑤ 绘制排版layout_tools.pyadd_panel_labels()/finalize_figure()⑥ 视觉自检visual_qa.pyrender_preview()/audit_layout()⑦ 导出成图export_figure.pyexport_figure()⑧ 合规审计check_figure.pycheck_figure()/print_report()完整技能定义见 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.txtSciencePlots、pypdf 等为可选增强缺失时功能优雅降级。二、profile_data.py数据剖析 API——思考的起点文件scripts/profile_data.py这是「先思考后绘制」的第一环在画图前先读懂数据。核心 APIprofile_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-L163correlation连续列间 Pearson 相关矩阵按 |r| 排序并给出强度描述group_summary分组样本量分布自动标记n10的小样本组触发禁止均值柱警告suggestions把数据形态直接翻译成图型建议折线/箱线/散点/热力图等warnings缺失率超 20%、小样本组等风险提示配套 APIrender_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核心 APIsetup_style(journal, lang, use_sciplots, serif_for_zh, constrained_layout)定义于 setup_style.py#L259一次调用完成整图视觉基线参数说明journalnature/science/ieee/general四种预设langen/zh中文模式自动配置 CJK 字体并修复负号方框use_sciplots装了 SciencePlots 就用其风格栈没装自动回退内置预设不会崩溃serif_for_zh中文期刊宋体正文 Times New Roman 数字混排约定constrained_layout默认开启自适应排版从源头减少文字裁切、图例压数据内置预设 JOURNAL_PRESETS 覆盖了期刊最挑剔的细节Nature 单栏 3.5 in、字号 7pt、pdf.fonttype42TrueType 嵌入、关闭上下边框等——这些正是期刊 PDF 检查器会逐项核实的项。中文支持两个辅助 APIconfigure_chinese_fonts(serif_for_zh)setup_style.py#L193按Noto Sans CJK SC Source Han Sans SC SimHei Microsoft YaHei优先级自动找字体同时设置axes.unicode_minusFalse修复负号方框找不到任何中文字体时抛出带安装指引的清晰报错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 1add_panel_labels(fig, stylenature)定义于 layout_tools.py#L78。对齐原理很巧妙每个标签锚定在子图 axes 左上角再施加统一的 points 物理偏移——同列子图左边缘 x 相同、同行子图上边缘 y 相同因此标签天然横竖成线不会因 y 轴刻度宽度不同而错位。支持 6 种期刊惯例PANEL_STYLESnature/science加粗小写a b cieee/paren(a)(b)(c)upper/upper_parenA B C/(A)(B)(C)它自动排除 colorbar 和 inset超过 26 个 panel 会用aa, ab...兜底。API 2finalize_figure(fig, preferconstrained)定义于 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.pyv2.1 新增的「出图后闭环」中负责确定性问题检测感知性问题交给 AI 读图清单在 references/visual_review.md。API 1render_preview(fig_or_path, out_png, dpi150)定义于 visual_qa.py#L242。渲染一张中分辨率 PNG 供 AI 用 Read 工具读图复核。支持 Figure 对象或已落盘文件PDF 需可选的 PyMuPDF。矢量 PDF 无法直接看像素重叠所以必须经过这一步栅格化。API 2audit_layout(fig)定义于 visual_qa.py#L134非破坏性检测返回[(severity, msg), ...]检测项级别原理缺字乱码FAIL同时拦截 matplotlib 的 warnings 与 logging 两条告警通道任一报 missing from font 即判定成图会出方框文字越界裁切WARNText 的window_extent超出画布跳过 tick 标签避免误报刻度标签重叠WARN相邻 tick label 包围盒相交检测配套print_report(issues)输出 PASS/WARN/FAIL 结论。六、export_figure.py导出 API——按最终尺寸一次成型文件scripts/export_figure.py核心 APIexport_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.fonttype42、svg.fonttypenone文本保留可编辑多家期刊明确拒收 Type-3 PDF灰度预览grayscale_previewTrue额外生成_grayscale.pngexport_figure.py#L128-L147用 Pillow 转灰度做色盲安全检查没装 Pillow 会优雅跳过from export_figure import export_figure paths export_figure( fig, basenamefigs/fig1, formats[pdf, svg, png], size_inches(3.5, 2.625), dpi300, grayscale_previewTrue, )七、check_figure.py合规审计 API——投稿前最后一道闸文件scripts/check_figure.py只读、非破坏性逐文件输出问题清单严重程度分为INFO WARN FAIL。核心 APIcheck_figure(path, min_dpi300, target_inchesNone)定义于 check_figure.py#L175返回(issues, info)。内置三类检查位图JPEG 直接 FAIL读取 DPI 元数据与目标值比较PIL 会 round-trip 出 299.9994 这类值内部做了取整容错像素/DPI 反推实际英寸并与目标尺寸比对±0.1 in 容差矢量 PDFcheck_figure.py#L96-L156 用 pypdf 解析字体资源Type-3 字体直接 FAIL、未嵌入字体 WARNSVG扫描 base64 内嵌位图——一旦误用 imshow 贴图矢量优势就没了配套 CLI 与 APIpython scripts/check_figure.py figs/*.pdf --min-dpi 300 --strict--strict下任意 FAIL 返回 exit code 2可直接接入 CIPython 端print_report(path, issues, info)打印逐图 verdictPASS/WARN/FAIL。八、六 API 速查表与调用顺序#API一句话职责所属脚本1profile_data()数据剖析 图型初建议profile_data.py2setup_style()期刊预设 中文字体 排版引擎setup_style.py3finalize_figure()出图前兜底理版layout_tools.py4add_panel_labels()子图编号横竖对齐layout_tools.py5render_preview()audit_layout()渲染预览 缺字/裁切/重叠自检visual_qa.py6export_figure()→check_figure()多格式导出 → 合规审计export_figure.py / check_figure.py推荐调用链profile_data → setup_style → 绘图 → finalize_figure → add_panel_labels → render_preview audit_layout → export_figure → check_figure。任何一层自检不通过就回改重渲把问题挡在投稿之前 ✅九、新手常见问题Q中文图出方框怎么办先setup_style(journalgeneral, langzh)配 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.md18 条科研画图禁忌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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考