XiaoMaColtAI/math-modeling-skill / tools/figure
科研可视化工具
Verified从数据剖析到出版级成图的完整可视化工具。先做数据剖析(列类型/样本量/分布/异常值/分组结构/相关性), 再结合论证目标推荐图型,主动拦截科研画图经典错误,产出 Nature / Science / IEEE / Elsevier / PNAS / 中文核心期刊级别的成图。覆盖数据 EDA、图表契约、选图决策、出版级绘制、程序自检 + AI 读图闭环、多格式 导出和文件审计。数学建模场景额外支持三类图体系(原始数据/过程/结果)、子问题覆盖检查和建模流程图规范。 当用户涉及论文配图、科研画图、数据可视化、选图、期刊投稿图、figure、出版级图表、matplotlib、seaborn、 plotly、误差棒、显著性标注、色盲安全配色、矢量图导出、中文论文图表、多面板时使用。
references/design/viz_pitfalls.md
View on GitHub# 科研可视化避坑清单
每条错误都按这个结构写:**错误是什么 → 为什么是错的(审稿人视角)→ 正确做法**。这是 `scipilot-figure-skill` 的"主动拦截"清单——发现用户的需求会触发其中任意一条,**先说明问题再给替代方案,不要默默照做**。
## 目录
- [P1. 均值柱状图掩盖分布与样本量](#p1-均值柱状图掩盖分布与样本量)
- [P2. 双 Y 轴的误导性](#p2-双-y-轴的误导性)
- [P3. 饼图与 3D 图](#p3-饼图与-3d-图)
- [P4. Y 轴不当截断](#p4-y-轴不当截断)
- [P5. 连续色阶无 colorbar](#p5-连续色阶无-colorbar)
- [P6. 把离散点连成折线](#p6-把离散点连成折线)
- [P7. 过度使用颜色](#p7-过度使用颜色)
- [P8. 图例缺失或不清](#p8-图例缺失或不清)
- [P9. 误差类型不交代](#p9-误差类型不交代)
- [P10. 过度装饰(chartjunk)](#p10-过度装饰chartjunk)
- [P11. 分辨率 / 格式不达标](#p11-分辨率--格式不达标)
- [P12. 一图多论点](#p12-一图多论点)
- [P13. 红绿对比、不做色盲检查](#p13-红绿对比不做色盲检查)
- [P14. rainbow / jet 色图](#p14-rainbow--jet-色图)
- [P15. 显著性符号滥用](#p15-显著性符号滥用)
- [P16. 缺字乱码:中文 / 负号 / 特殊符号变方框](#p16-缺字乱码中文--负号--特殊符号变方框)
- [P17. 文字裁切与图例遮盖](#p17-文字裁切与图例遮盖)
- [P18. 多面板子图编号不对齐](#p18-多面板子图编号不对齐)
> P16–P18 是 v2.1 新增的「排版/渲染」类坑——和前 15 条不同,它们往往**画的时候看不出来、导出后才暴露**。配套的兜底手段:`setup_style`(字体+constrained_layout)、`layout_tools.py`(对齐+理版)、`visual_qa.py`(程序自检)、`visual_review.md`(AI 读图自检闭环)。
---
## P1. 均值柱状图掩盖分布与样本量
**错误**:每组只画一根柱代表均值,加一条小误差棒,没有原始数据点。
**审稿人视角**:
- n=3 和 n=300 画出来一样高,无法判断证据强度
- 双峰分布、严重偏态、单个 outlier 主导——全被均值吃掉
- 2020 年起多家期刊(如 PLoS Biology、Nature Methods 评论)公开呼吁停止使用"裸均值柱"
**正确做法**:
1. n ≥ 10 → **箱线/小提琴 + 叠加 stripplot 显示原始点**
2. n < 10 → **直接 stripplot / dot plot**,根本不画统计柱
3. 一定要用柱状(如剂量响应历史惯例)→ 至少**叠加 stripplot**,且必须显示误差棒(明确写 SD/SEM)
```python
sns.boxplot(data=df, x='group', y='value', showfliers=False)
sns.stripplot(data=df, x='group', y='value', color='black',
size=3, alpha=0.6, dodge=True)
```
---
## P2. 双 Y 轴的误导性
**错误**:左 y 轴一组数据、右 y 轴另一组数据,画在同一张图上。
**审稿人视角**:
- 两个轴的尺度可以任意调,**视觉上 A 和 B 的"重合"或"分歧"完全是作图者捏造的**
- Tufte 1983 起就批判过;Edward Tufte 称"基本上没有诚实使用双 Y 轴的情景"
**正确做法**:
1. 两个变量量纲相同 → 共用一个 y 轴
2. 量纲不同但要看相关 → 散点图(x 是 var1,y 是 var2,每个时间点一个点)
3. 量纲不同要看趋势 → **拆成上下两个子图**,共享 x 轴;或**标准化**两个量到 [0,1] 后共轴
---
## P3. 饼图与 3D 图
**错误**:用饼图展示占比;用 3D 柱状/3D 饼/3D 表面图。
**审稿人视角**:
- 人眼对**长度**的辨别比对**角度**至少精确 3 倍——饼图本质上不可读
- 3D 视角扭曲所有数值:靠前的 3D 柱看起来比靠后的高,与真实数据无关
- 多家期刊(Nature 系、Science、PNAS)的 figure guideline 明确不推荐 / 拒收
**正确做法**:
1. 占比 → **横向柱状图**(按值排序,类别名在 y 轴)
2. 总和分解 → 堆叠柱状(单根或多根)
3. 想要"圆形美感"且类别少(< 4)→ donut chart 勉强可,但仍不如柱
4. 真的需要展示 3D 数据 → **2D 热力图** + colorbar;或 contour plot
---
## P4. Y 轴不当截断
**错误**:y 轴从一个非 0 的值开始,让小差异看起来很大。
**审稿人视角**:
- 经典误导手段;新闻图表里常用,学术圈一查就知
- 截断会让 "上升 2%" 看起来像 "翻倍"
**正确做法**:
1. y 是比例 / 概率 / 准确率 → **从 0 开始**(或从合理基线,如 random baseline 25%)
2. y 跨数量级 → **log 轴**而不是截断线性轴
3. 必须截断(如显示 "98% vs 98.5%" 的差异)→ **明确画一道断裂标记**(两条小斜线),并在图注说明
---
## P5. 连续色阶无 colorbar
**错误**:用颜色深浅映射连续值(如 expression level),但没画 colorbar。
**审稿人视角**:
- 读者无法知道"深红"对应数值多少
- 多张图的"深红"可能不一致
**正确做法**:
1. 任何用颜色映射数值的图(热力图、散点 hue 是连续值、KDE 等高线)→ **必须配 colorbar**
2. colorbar 必须有 **label**(变量名 + 单位)
3. 多张图比较时 → **锁定** `vmin` / `vmax` 一致,否则视觉对比无效
---
## P6. 把离散点连成折线
**错误**:x 是分类变量(A/B/C/D),却用 `plt.plot` 把每组均值用线连起来。
**审稿人视角**:
- 折线 = 暗示 x 之间有连续关系;分类之间"连成线"完全没有数学意义
- 读者会误以为"从 A 到 B 是连续过渡"
**正确做法**:
1. x 是分类 → 柱状 / 箱线 / 点图(dot plot)
2. x 是有序但离散(如 Likert 1-5、剂量等级) → 点图,**可选**用极细的"引导线"连接但要在图注说明"连线仅为读图引导"
3. x 是真正连续(时间、剂量值) → 才用折线
---
## P7. 过度使用颜色
**错误**:一张图里用 10+ 种颜色区分类别;或不同图同一变量用不同颜色。
**审稿人视角**:
- 短期记忆容量 7±2;颜色超过 7 个无法稳定区分
- 多张图同一变量不同色 = 跨图对比要重新查图例
**正确做法**:
1. 类别 ≤ 5 → 颜色 + 双重编码(线型/marker)
2. 类别 6-12 → 用**直接标注**(曲线末端写名字)+ 颜色仍是辅助
3. 类别 > 12 → 拆图或聚类合并,或用 small multiples
4. **跨图色彩一致性**:建一份 `palette = {"control": "#999999", "drug_A": "#E69F00", ...}`,所有图共用
---
## P8. 图例缺失或不清
**错误**:图里有多组数据但没有图例;图例位置遮挡数据;图例标签是 `Series1` / `df["col"]` 之类的程序内部名。
**正确做法**:
1. 任何 hue 映射必有图例
2. 图例标签是**人话**("Drug A, 10 mg/kg")不是变量名
3. 图例位置:`loc='best'` 不一定最佳;手动放空白区域
4. 类别多时 → `bbox_to_anchor` 放到图外,或直接标注代替图例
5. `frameon=False` 让画面更干净(去掉图例黑框)
---
## P9. 误差类型不交代
**错误**:图里有误差棒 / 阴影带 / 箱线,但图注里没写是 SD / SEM / 95% CI。
**审稿人视角**:
- SD 和 SEM 差一个 √n;CI 又是另一回事——**混淆会让结论完全反转**
- 这是高频退稿原因之一
**正确做法**:图注必须包含:
```
"data are mean ± SEM, n = 12 per group"
"box plots show median, IQR, and 1.5×IQR whiskers; outliers shown as dots"
"shaded band = 95% confidence interval, n = 8 replicates"
```
显著性符号同理:
```
"* p<0.05, ** p<0.01, *** p<0.001 by Mann-Whitney U test;
Bonferroni-corrected for 6 comparisons"
```
---
## P10. 过度装饰(chartjunk)
**错误**:网格线密集、背景渐变、立体阴影、用样式花哨的 marker、每个柱不同色(无含义)。
**审稿人视角**:
- Tufte 提出的"data-ink ratio":墨水越多越好用于表达数据;装饰是浪费
- 装饰会**淹没**真实数据的对比
**正确做法**:
1. 关掉默认网格(`ax.grid(False)`)或只保留水平/垂直主网格、虚线浅灰
2. 去掉顶/右两条 spine(`despine`)
3. 同类数据**用同一颜色**(除非有分组意义)
4. marker 简洁:`o` / `s` / `^` 即可
---
## P11. 分辨率 / 格式不达标
**错误**:
- 提交 JPEG 数据图(有损压缩 + 边缘 artifact)
- 提交 72 DPI PNG
- 提交"截图"得到的位图
- PDF 嵌入 Type 3 字体(多家期刊拒收)
**正确做法**:
1. 数据图(线/柱/散点/热力/箱线)→ **矢量** PDF / SVG / EPS
2. 照片 / 显微图 → **位图** PNG / TIFF,**≥300 DPI**
3. 永远不用 JPEG
4. PDF 设 `rcParams['pdf.fonttype'] = 42`(TrueType)
跑 `scripts/check_figure.py --strict` 一键查。
---
## P12. 一图多论点
**错误**:一张图里塞了 5 个 panel,每个想说不同的事;或一个 panel 里画了 8 条曲线想说多件事。
**审稿人视角**:
- 读者第一眼应该 5 秒内 grasp 一个核心信息
- 多论点 = 没论点
**正确做法**:
1. 一张图 → 一个核心结论
2. 想说多件事 → 拆成多张图或多个 panel;每个 panel 一个独立论点
3. 一组 panel(同一个 Figure 编号下的 a/b/c/d)→ 围绕**同一主题**的不同侧面,不是几个不相关的内容硬拼
---
## P13. 红绿对比、不做色盲检查
**错误**:用红色 / 绿色区分两组(最经典的色盲不友好对比);不导出灰度版本检查。
**审稿人视角**:
- 8% 男性、0.5% 女性是色觉异常;最常见的是红绿色盲
- 色盲读者看你的图是两条**完全分不开**的灰线
**正确做法**:
1. 用 **Okabe-Ito** 8 色或 seaborn `colorblind` 调色板
2. 不同类别**加冗余编码**:颜色 + 线型 / marker
3. `export_figure(..., grayscale_preview=True)` 自动生成灰度版本
4. 灰度下能否区分?不能 → 加 marker / 改线型
---
## P14. rainbow / jet 色图
**错误**:连续值用 `rainbow` / `jet` / `hsv` 色图。
**审稿人视角**:
- 这些色图**感知不均匀**——视觉上的"亮度梯度"和实际数值梯度不对应
- 黄色波段视觉极亮,造出虚假的"峰"
- IEEE / Nature 等期刊已明确推荐 viridis 系列
**正确做法**:
- 单向连续值(全正 / 全负)→ `viridis` / `magma` / `inferno` / `cividis`
- 双向数据(有正有负,0 是基线)→ `RdBu_r` / `PiYG` / `seismic` + `center=0`
- 分类(discrete)→ `tab10` / `Set2` / Okabe-Ito,**不要**用 rainbow 抽点
---
## P15. 显著性符号滥用
**错误**:
- 每个组合都画 *,整张图全是星号
- 用了显著性但没说哪种检验
- 没做多重比较校正
- 把 "n=3, p=0.04" 当显著结论
**审稿人视角**:
- 小样本 p<0.05 经常是噪音
- 没校正的多重比较是 p-hacking 红旗
**正确做法**:
1. 只标**与论点有关**的少数几个对比,不全标
2. 图注必须写:检验类型 + 校正方法 + 符号定义
3. n<10 的"显著"要谨慎;考虑展示效应量(Cohen's d)而非只看 p
---
## P16. 缺字乱码:中文 / 负号 / 特殊符号变方框
**错误**:成图里中文显示成 `□□□` 方框 / 豆腐块;负号变方框;`±` `×` `μ` `Δ`、希腊字母、上下标缺字。
**为什么会这样(根因)**:
- matplotlib 默认字体(DejaVu Sans 等)**不含 CJK 字符表**——写中文必然方框。
- 某些字体不含 Unicode 真减号 `U+2212`,`axes.unicode_minus=True`(默认)时负号就渲染成方框。
- 最坑的是:matplotlib 遇到缺字**只发一条 warning、照样把图画出来**,不报错——所以**画的时候不一定注意到,导出投稿才暴露**。
**正确做法**:
1. **中文图先配字体**:`setup_style(lang='zh')` 自动按优先级查 `Noto Sans CJK SC > Source Han Sans > SimHei > Microsoft YaHei`;中文期刊宋体混排传 `serif_for_zh=True`。
2. **负号方框**:v2.1 的 `setup_style` 已**全模式默认** `axes.unicode_minus=False`(用 ASCII 减号,几乎所有字体都含)——不用再手动设。
3. **导出前用程序自检兜底**:`visual_qa.audit_layout(fig)` 会同时拦截 matplotlib 的 warning 与 logging 两条通道,**任何缺字直接判 FAIL**,把方框挡在导出之前。
4. 不确定系统有哪些中文字体:`python scripts/setup_style.py --list-fonts`。
```python
from setup_style import setup_style
from visual_qa import audit_layout, print_report
setup_style(journal='general', lang='zh') # 配 CJK + 关负号方框
# ... 画图 ...
print_report(audit_layout(fig)) # 有缺字 → FAIL,立刻可见
```
---
## P17. 文字裁切与图例遮盖
**错误**:
- 标题 / x 轴 / y 轴标签被画布边缘切掉一截。
- 图例(legend)压在数据点、曲线或柱子上面。
- 旋转后的长刻度标签底部出界。
**审稿人视角**:
- 被裁的标签 = 信息缺失,图自身不自洽,审稿人无法判断坐标含义。
- 图例压数据 = 关键数据点看不见,等于在藏数据。
**正确做法**:
1. **从源头**:v2.1 `setup_style` 默认开 `constrained_layout`,自动给标题/标签留位。
2. **兜底**:出图后跑 `layout_tools.finalize_figure(fig)`;导出时 `export_figure(..., tight=True)`(默认 `bbox_inches='tight'`)。
3. **图例移出数据区**:
```python
ax.legend(loc='upper left', bbox_to_anchor=(1.02, 1.0), frameon=False)
# 或类别多时直接在曲线末端标注,彻底不要图例
```
4. **长刻度标签**:`ax.tick_params(axis='x', rotation=30)` + `ha='right'`;或缩短标签。
5. **终检**:`visual_qa.audit_layout(fig)` 检测文字越界(WARN),再 AI 读图确认图例是否压住数据(程序难判的感知问题,见 `visual_review.md`)。
---
## P18. 多面板子图编号不对齐
**错误**:组图里 a/b/c/d 用各子图自己的坐标手动摆放,导致**横竖不成线**——常见写法:
```python
# ✗ 反例:用 axes 比例坐标,各子图 y 轴刻度宽度不同时标签会错位
for ax, lab in zip(axes.flat, 'abcd'):
ax.text(-0.20, 1.05, lab, transform=ax.transAxes, fontweight='bold')
```
**审稿人视角**:
- 子图标签错位、字号/风格不统一(`a` 和 `(a)` 混用)= 排版不专业,组图显得草率。
- 标签是读者理解"先看哪个 panel"的路标,乱放会打断阅读顺序。
**正确做法**:用 `layout_tools.add_panel_labels()` —— 它把标签锚在每个子图的 `axes fraction (0,1)`(左上角)再施加**统一的 points 偏移**。因为同列子图左边缘 figure-x 相同、同行子图上边缘 figure-y 相同,统一偏移后**所有标签横看一条线、竖看一条线**,且不受各子图 y 轴刻度宽度影响:
```python
# ✓ 正解:一行搞定,自动对齐 + 风格统一
from layout_tools import finalize_figure, add_panel_labels
finalize_figure(fig) # 先把版面定下来
add_panel_labels(fig, style='nature') # a b c d(IEEE 用 style='ieee' → (a)(b)(c))
```
字号默认取 `axes.labelsize` 并加粗,风格由 `style` 统一控制——不会再出现 `a` 和 `(a)` 混排。
---
## 拦截发生时的话术
当用户的需求会触发以上任何一条,本 skill 应当:
1. **先说明问题**:哪条 pitfall 触发了
2. **解释为什么**(一句话审稿人视角)
3. **给替代方案**(具体可执行的)
4. **询问是否仍坚持**——尊重用户最终决定,但**留下明确的劝阻记录**
示例话术:
> 你要的"3 组各 5 个样本的均值柱状图"会触发 P1(均值柱掩盖分布):
> n=5 太小,柱状会让审稿人怀疑你藏了什么。我建议改成
> **箱线 + stripplot 叠加每个点**,5 个点直接可见、分布形态一目了然。
> 还要按原方案画吗?
---
## 数学建模特有避坑
以下条目针对数学建模论文的常见问题,补充上文通用清单未覆盖的场景。
### P19. 锯齿折线暗示假波动
**错误**:对少量离散方案或参数取值画折线图,锯齿形状暗示不存在的连续趋势。
**为什么错**:x 轴是离散方案编号或参数标签,点之间没有过渡含义,折线让读者误以为有连续变化规律。
**正确做法**:改用分组柱状图或点图+误差棒。如果 x 确实是连续变量(如时间、剂量),保留折线。
### P20. 稀疏分组率图误导
**错误**:用柱状图展示各组的比率/百分比,但每组样本量差异巨大且未标注 n。
**为什么错**:n=5 和 n=500 的组在图上高度看起来同样可靠,掩盖了小样本组的高不确定性。
**正确做法**:在柱状图上方标注每组 n,或改用点图+区间(Wilson/Clopper-Pearson 置信区间),让不确定性可见。
### P21. 收敛曲线缺终止条件
**错误**:画迭代收敛曲线但不标注终止条件(如 max_iter、tolerance、早停策略)。
**为什么错**:读者无法判断收敛是"真正的稳态"还是"被截断的假收敛"。
**正确做法**:在图注或图内标注终止条件和最终迭代次数。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |