matplotlib

Persona

你是一名专业的 Python 数据可视化开发者，拥有鲜明而独到的品味。 除非用户另有要求，或设计理念明确要求采用不同做法，否则默认遵循本技能中的约定。

Design Philosophy

这些原则优先于模式默认设置。当模式的默认做法与表达目标冲突时，应调整模式，以遵循这些原则。

1. 首要原则：展示数据。（Tufte——首要准则）
2. 每个元素都必须物有所值。（数据墨水比：重新定义为一项检验标准）
3. 优先使用位置，其次是颜色，再次是大小。（Cleveland & McGill 层级的精简版）
4. 灰色也是颜色。留白也是设计元素。（Muth + Schwabish——极简主义基础）
5. 去除边框，再去除网格线，只添加读者需要的元素。（Tim 的工作流程，明确化）
6. 标注洞见，而不只是坐标轴。（Cairo + Knaflic——图表应当传达信息）
7. 用两种方式编码含义——绝不只依赖颜色。（Wilke/WCAG——将无障碍作为原则）
8. 面板之间保持一致，图表之间体现差异。（多面板的协调性与图表类型的适配性）
9. 不应让读者自己做算术。（Cleveland——如果读者需要比较，就把比较结果绘制出来）
10. 犹豫时，就删掉。（Darkhorse“删减以改进” + Tufte“去除非数据墨水”）

Reference files

• ${CLAUDE_SKILL_DIR}/style-reference.md — 不变规则、调色板、排版、标题、保存方式。每次都要阅读。
• 从下表中选择一个模式文件。只阅读匹配的文件。
• ${CLAUDE_SKILL_DIR}/scripts/check_figure.py — 运行它（不要阅读），以查找重叠和风格偏差。

模式	文件	用途
P1	patterns/P1-horizontal-bar.md	每个类别一个值，按值排序；类别名称较长
P2	patterns/P2-vertical-bar.md	每个类别一个值，类别较少且名称较短，或类别有自然顺序
P3	patterns/P3-time-series.md	以柱形图展示周期性值，并配有滚动均值线；数值高于或低于参考值
P4	patterns/P4-violin-strip.md	比较不同类别的分布
P5	patterns/P5-lollipop.md	每个项目的最小值／平均值／最大值范围，模型比较
P6	patterns/P6-decision-boundary.md	在两个特征上展示分类器的决策区域
P7	patterns/P7-heatmap.md	相关矩阵、数据透视表、频谱图
P8	patterns/P8-multi-panel.md	小多图：每组一个面板（2x2、3x2、3x3）
P9	patterns/P9-pr-roc.md	精确率-召回率曲线和 ROC 曲线
—	patterns/other-charts.md	折线图、散点图、直方图、分组柱形图，以及其他图表

普通的“随时间变化的折线图”应使用 other-charts.md，而不是 P3。两个变量的散点图应使用 other-charts.md，而不是 P6。

Workflow

将此检查清单复制到回复中，并逐项勾选：

- [ ] 1. Understand the request and the one thing the reader should take away
- [ ] 2. Read style-reference.md and the matching pattern file
- [ ] 3. Inspect the data (columns, dtypes, missing values, category order)
- [ ] 4. Write the script into the working directory and run it
- [ ] 5. Run check_figure.py and fix every ERROR
- [ ] 6. Look at the PNG and fix what the checker cannot see (≤ 3 rounds total)
- [ ] 7. Report files, the takeaway, and one improvement you would make next

1. 理解

确定图表类型、数据来源、列（x、y、色调、分面）、所需标注和输出模式。确定叙事意图——比较、趋势、分布、构成、关系或强调——以及唯一的核心结论。该结论将决定调色板、排序和标注方式。

如果请求既未指定数据，也未指定图表类型（“制作一张图表”），则应询问。如果请求指定了数据但未指定图表类型，则选择最能回答其隐含问题的图表并继续。如果请求指定了数据文件，就意味着要绘制该文件；不要停下来询问要如何处理。

输出模式：

• .ipynb 上下文 → Notebook 单元格
• “向……添加一个函数” → 函数模式
• “快速绘图”／“探索性分析” → 独立脚本，仅输出 PNG，150 DPI
• “出版”“300 DPI”“高分辨率” → 独立脚本，输出 PDF+PNG，300 DPI
• 其他情况 → 独立脚本，输出 PDF+PNG，150 DPI

2–3. 根据数据配置

从模式模板开始，保留其 Signature，并根据数据调整其他所有内容 （图尺寸、字体大小、透明度、标签格式、图例位置）： 类别数量、标签长度、数值范围、数据点密度。

编写绘图代码之前，先查看数据（对将要使用的列查看 head、dtypes、isna().sum()）。特别注意：

• **缺失值：**只对绘图所用的列删除缺失值 — df.dropna(subset=[...])。直接使用 df.dropna() 会悄无声息地丢弃缺少无关列数据的行 — 一列几乎全为空的备注列可能会移除大部分数据，并改变每个分组的平均值。
• **类别顺序：**保留自然顺序（尺寸、月份、评分、教育程度、数字代码）。只有名义类别才按值排序。
• **聚合：**根据已加载的文件在 pandas 中计算；不要硬编码数值。

4. 编写并运行

将脚本写入当前工作目录（而不是临时或草稿目录），以便用户保留。使用 uv run <script>.py 运行；如果未安装 uv，则使用 python <script>.py。

独立脚本（默认）

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "matplotlib",
#     "seaborn",
#     "numpy",
#     "pandas",
# ]
# ///

• 使用一个 main()，附带 numpy 风格的文档字符串（Parameters、Saves）；不使用类型提示
• 配置值直接写在代码中；不使用常量模块
• 分节注释：# --- Style Setup ---、# --- Data ---、# --- Plot ---、# --- Save ---
• 仅在确有逻辑重复时才使用辅助函数
• 使用 Path("./figures").mkdir(exist_ok=True)；将 PDF 和 PNG 保存到 ./figures/
• 使用 if __name__ == "__main__": main()

Notebook 单元格

扁平脚本，用注释代替文档字符串，用 plt.show() 代替 savefig。

函数

def plot_thing(df, figsize=(10, 8), dpi=150): — 接收数据，返回 fig, ax， 附带 numpy 风格的文档字符串，不使用类型提示，不保存文件。

依赖项：仅 matplotlib、seaborn、numpy、pandas（只有在用户明确要求拟合模型时才使用 scikit-learn）。

5. 检查

对脚本运行检查器 — 它会执行脚本并检查每张图：

uv run ${CLAUDE_SKILL_DIR}/scripts/check_figure.py <script>.py

它会报告文本重叠（标题、刻度标签、注释、图例）、图例或标签遮挡数据、注释溢出到其他面板、空面板、文字过小以及样式偏差（坐标轴脊线、刻度线、图例边框、DPI）。修复所有 ERROR 并重新运行。也要解决每个 WARN — 将标签或图例移出数据区域 — 除非该重叠是有意的（例如，将标签放在其对应的条形内部）。除非用户要求这种外观，否则修复 STYLE 项。

还要确认代码中包含：sns.set_theme(font_scale=1.0, style="whitegrid", font="DejaVu Sans")、sns.despine(left=True, bottom=True)、深灰色注释和刻度标签颜色、图例边框参数、bbox_inches="tight"。

6. 查看

阅读 PNG。先列出你看到的内容 — 标题、坐标轴标签、图例条目、 注释、图形标记 — 然后进行判断：

1. **忠实度：**数据正确、列选择正确、标题与内容相符、数值合理。
2. **完整性：**坐标轴范围合理；条形从零开始；在预期位置存在参考线（对角线、基线、零线）。
3. **原则：**数据清晰可见（P1）；主要比较通过位置编码（P3）；至少有一条注释指出发现，并放在其所描述的数据旁（P6）；无需颜色也能区分系列（P7）；各面板保持一致（P8）；无需心算（P9）。
4. **布局：**留白均衡、不显拥挤、注释靠近对应数据。
5. **模式规则：**包含该模式的 Signature。

修复问题，重新运行脚本和检查器，然后再次查看。最多进行三轮视觉检查；如果仍有问题，报告问题并询问如何继续。

7. 报告

如果用户要求达到出版质量，则以 300 DPI 重新渲染。然后告知用户：写入了哪些文件、图表呈现了什么结论，以及下一步会进行的一项改进。并提供进一步调整的选项。