publication-chart-skill

出版级图表技能

目标

使用此技能，通过端到端工作流将研究结果转化为出版级图表和表格。

主要制作工具链：

• pubfig：用于图表
• pubtab：用于出版级表格

此技能涵盖完整的交付流程：

1. 理解科学传播目标，
2. 选择合适的产物类型，
3. 将任务对应到 pubfig、pubtab 或两者，
4. 生成可直接运行的具体指令，
5. 导出可直接用于论文的素材，
6. 执行出版级 QA，
7. 提出有针对性的修改建议。

适用场景

对于以下请求，请使用此技能：

• “制作一张出版质量的图”
• “为这些结果选择合适的图表”
• “将这些结果制作为可直接用于论文的图”
• “制作基准测试 / 消融 / 校准 / 森林图 / 热图 / 散点图 / 折线图 / 柱状图”
• “根据 Excel 制作基准测试 / 附录 / 消融表格”
• “将此 Excel 表格转换为可直接用于出版的 LaTeX”
• “为结果部分准备一张汇总图和一张配套表格”
• “审查并改进这张科学图表 / 表格”
• “我已经有一张效果不佳的图表 / 截图 / 草稿图——将其改成可直接用于出版的版本”
• “导出论文图表的各个面板”

不适用场景

当任务主要涉及以下内容时，不要使用此技能：

• 撰写论文正文，
• 在不设计产物的情况下进行统计检验，
• 不涉及出版交付物的原始探索性分析，
• 图表 / 表格内容尚未完善时，优先使用 Figma 进行排版。

如果图表内容已经完善，只需进行简单的组合排版，请使用 references/composite-assembly.md 中的可选辅助工作流。

主要约定

输入

预期输入可能包括以下内容的组合：

• 科学传播目标，
• 可用数据的结构，
• 会议或期刊的风格要求，
• 产物是图表、表格还是混合交付物，
• 可选的现有素材，例如代码、电子表格、.tex、截图或草稿图，
• 用户需要的是初稿、可直接用于出版的产物，还是审查 / 修改。

输出

最低限度的实用输出包括：

• 推荐的图表 / 表格形式，
• 推荐使用的 pubfig / pubtab 流程，
• 可直接运行的最简代码片段或 CLI 命令，
• 明确的导出文件名和格式，
• 出版级 QA 摘要，
• 以及必要时的修改计划。

默认工作流

0. 探查环境和制品状态

在生成任何内容之前，先确认：

• pubfig 或 pubtab 是否可用，
• 用户是否已有代码、电子表格、.tex 文件或截图，
• 交付内容是全新制作还是修订现有内容，
• 结果是否需要精确数值、快速视觉感知，或两者兼备。

优先执行最精简且有助于工作的环境检查。如果有随附的辅助脚本，请先使用：

• python3 scripts/ensure_publication_tooling.py --require pubfig --json
• python3 scripts/ensure_publication_tooling.py --require pubtab --json

必要时也可以进行等效的手动检查：

• python -c "import pubfig; print(pubfig.__version__)"
• python -c "import pubtab; print(pubtab.__version__)"
• pubtab --help

清楚地报告检查结果为可用或缺失。

如果缺少依赖，且任务需要实际运行：

• 默认自动安装，
• 优先使用用户当前激活的环境，不要随意猜测一个全局解释器，
• 如果有该脚本，默认使用 python3 scripts/ensure_publication_tooling.py --require ... 作为随附的安装方式，
• 让该辅助脚本针对当前激活的解释器选择 uv 或 python -m pip，
• 安装后重新检查可用性，
• 然后再继续处理制品。

也可以使用以下等效的具体命令：

• python3 scripts/ensure_publication_tooling.py --require pubfig
• python3 scripts/ensure_publication_tooling.py --require pubtab
• uv pip install pubfig
• uv pip install pubtab
• python -m pip install pubfig
• python -m pip install pubtab

如果自动安装失败，请报告确切错误，然后尽可能妥善处理。

不要因为全面审计环境而阻塞任务。

1. 对任务进行分类

按以下维度对请求进行分类：

• 制品类型：图表 / 表格 / 混合交付
• 成熟度：探索性草稿 / 可供发表的成品 / 修订现有制品
• 结构：单面板 / 多面板 / 图表加表格套件
• 证据模式：模式感知 / 精确数值查询 / 两者兼备

在明确沟通目标之前，不要直接开始编写绘图代码。

绘制研究结果前，先确定证据约定：

• 主要科学论点，
• 分析单位，
• 主要指标及指标方向，
• 重复行是否相互独立，
• 缺失单元格或不完整的比较组，
• 误差条依据：受试者、受试者-任务、折、随机种子、运行或自助抽样样本，
• 是否需要配套表格列出精确数值，
• 当前证据是否足以支持胜出或显著性结论。

如果这些信息不明确，请提问或给出审查建议，而不要制作精修图表。如果分析单位、缺失单元格处理方式或误差条依据尚未确定，请勿制作可供发表的图表。

2. 选择表示形式

根据科学主张选择表示形式，而不是根据新颖性或视觉效果。

常见类型：

• 比较 — 分组散点图、柱状图、折线对比、基准测试摘要、配套表格
• 消融 — 分组比较、哑铃图、配对比较、紧凑表格
• 分布 — 箱线图、小提琴图、雨云图、直方图、密度图、ECDF、QQ 图
• 关系 — 散点图、气泡图、二维等高线图、六边形分箱图
• 趋势 — 折线图、面积图
• 评估 / 诊断 — 校准图、ROC、PR、Bland–Altman 图、森林图、火山图
• 组成 / 层级 — UpSet 图、堆叠比例图、环形图、径向层级图、圆形分组或堆叠柱状图
• 表格 — 基准测试表、消融表、数据集摘要、附录表、错误细分表

避免采用不合适的默认形式：

• 当精确比较很重要且柱状图 / 表格更清晰时，避免使用饼图 / 环形图；
• 除非比较确实呈现低基数的轮廓特征，否则避免使用雷达图；
• 避免使用 3D、装饰性渐变，以及仅用于美化的密集图例；
• 当出版物表格能更好地传达证据时，不要强行将每项结果都做成图。

如果请求含糊不清，请明确说明该作品应支持什么科学主张。

3. 映射到工具链

默认映射：

• 图表 → pubfig
• 表格 → pubtab
• 混合交付物 → 两者都用，并让每个作品承担不同的作用

工具职责：

• pubfig 是用于科学绘图和论文就绪导出的默认图表引擎。
• pubtab 是用于 Excel ↔ LaTeX 工作流、预览和出版就绪表格导出的默认表格引擎。
• Figma / 复合图组装是用于多面板润色的可选辅助流程。

路由选择规则：

• 使用 Python 生成 pubfig 图表；
• 当任务由文件驱动时，优先使用 pubtab CLI；
• 当任务已处于笔记本或脚本化流水线中时，优先使用 Python 调用 pubtab；
• 对于混合请求，将图表和表格的职责分开。

4. 生成具体的作品说明

首先提供最精简、可用于生产的作品：

• 用于 pubfig 的最简可运行 Python，或
• 用于 pubtab 的最简 CLI / Python

然后，仅在有必要时添加出版参数：

• 标签、图注、宽度、导出格式、后端、预览、面板打包或复合布局。

明确列出文件名和后缀。

推荐默认方案：

• 图表：一次 pubfig 调用 + 一次 save_figure(...)
• 多个图表输出：batch_export(...)
• 表格：一次 pubtab xlsx2tex ... 或 pubtab.preview ...
• 混合请求：分别列出一个图表流程和一个表格流程

5. 明确交付约定

对于每个回复，尽可能明确以下内容：

• 作品支持的主张；
• 哪部分由 pubfig 处理，哪部分由 pubtab 处理；
• 输出文件名；
• 输出格式；
• 作品属于草稿 / 定稿 / 修订稿；
• 还需要用户提供哪些数据或手稿背景。

6. 执行出版质量检查

生成后，检查：

• 标题和图例的密集程度；
• 坐标轴标签和单位；
• 类别排序及基线是否清晰；
• 颜色的无障碍性和灰度呈现效果；
• 字体 / 线宽的一致性；
• 图注是否可直接使用；
• 图表 / 表格缩小后的可读性；
• 多面板图表中各面板的一致性；
• 是否适合投稿场合，例如宽度、拥挤程度或标注过多等问题。

质量检查的结果必须具体。不要只说“看起来更好了”，而不说明原因。

7. 修订

如果结果不理想，应进行有针对性的修订，例如：

• 更换图表类型；
• 删除图表杂项；
• 重新排列类别；
• 将精确数值移到表格中；
• 拆分拥挤的面板；
• 添加或简化图注；
• 更改导出宽度；
• 或将交付物从以图表为主改为以表格为主。

缺少依赖时的处理

如果 pubfig 或 pubtab 不可用：

• 不要立即失败，
• 先尝试在当前活动环境中自动安装，
• 如果存在捆绑脚本，优先使用 python3 scripts/ensure_publication_tooling.py --require ...，
• 明确说明缺少哪项依赖，
• 说明将使用哪个安装命令或辅助工具途径，
• 安装后重新检查依赖是否可用，
• 如果安装成功，继续执行可运行的工作流，
• 如果安装失败，则降级为设计／规格说明工作流，
• 提供伪代码或待执行命令，
• 保留推荐的图表结构，
• 仍然提供 QA 和修订指导。

组合图组装规则

将组合图或 Figma 组装视为次要选项：

• 用户明确需要论文多面板图时使用，
• 或确实需要逐面板导出和布局润色时使用。

默认不要将简单的制图任务升级为组合图／Figma 工作流。

输出风格规则

• 优先提供可直接用于实现的输出。
• 简要说明选择图表／表格的原因，然后给出可运行的方案。
• 涉及执行时，加入简短的环境状态块，例如 pubfig: available/missing、pubtab: available/missing。
• 如果缺少依赖，说明确切的辅助命令或安装命令，执行安装，并报告安装后的状态。
• 表格优于图表时，明确说明。
• 图表优于表格时，明确说明。
• 两者都需要时，为它们分配不同的信息传达角色。
• 修订指导应切实可行，且结果可验证或证伪。

推荐的回复结构

符合此技能要求的高质量回复通常包含 6 个部分：

1. 产物选择 — 图表／表格／两者配套，并说明原因
2. 工具方案 — pubfig、pubtab 或两者
3. 最简实现 — 可运行的代码或 CLI
4. 导出方案 — 文件名、格式、宽度／后端／预览选项
5. 出版 QA — 提交论文前需要核查的内容
6. 修订计划 — 当前产物效果不佳时需要修改的内容

资源

按需加载以下资源：

• references/workflow.md — 完整的端到端决策顺序和交付要求
• references/chart-selection.md — 任务到图表类型的映射及反模式
• references/execution-and-verification.md — 环境探测、强制安装行为及可运行性验证
• scripts/ensure_publication_tooling.py — 用于探测并自动安装 pubfig／pubtab 的捆绑辅助脚本
• references/pubfig-recipes.md — 简明实用的图表模式和导出方案
• references/pubtab-recipes.md — 简明实用的表格方案和后端指导
• references/source-guides/pubfig-architecture.md — 基于源码的包布局和图表生成边界
• references/source-guides/pubfig-api-map.md — 基于 __init__.py 的稳定 pubfig 公共接口和图表系列映射
• references/source-guides/pubfig-export-flow.md — 基于源码的图表导出、出版尺寸设置和面板导出流程
• references/source-guides/pubtab-architecture.md — 基于源码的包布局及正向／反向转换架构
• references/source-guides/pubtab-cli-api-flow.md — CLI 到 API 的控制流及批处理／工作表行为
• references/source-guides/pubtab-backend-and-preview.md — 基于源码的后端／主题划分和实际预览编译流程
• references/publication-qa-checklist.md — 图表／表格 QA 检查清单
• references/composite-assembly.md — 可选的多面板和 Figma 分支

提示词形式的示例见 examples/。