matplotlib

Matplotlib 是 Python 的基础可视化库，用于创建静态、动画和交互式图表。本技能提供使用 Matplotlib 的指导，涵盖 pyplot 接口（MATLAB 风格）与面向对象 API（Figure/Axes），以及制作出版级可视化的最佳实践。

适用场景

需要创建任意类型的图表（折线、散点、柱状、直方图、热力图、等高线等）；生成科学或统计可视化；自定义图表外观（颜色、样式、标签、图例）；创建多面板子图；将可视化导出为多种格式（PNG、PDF、SVG 等）；构建交互式图表或动画；进行 3D 可视化；将图表集成到 Jupyter 笔记本或 GUI 应用中。

安装与设置

项目中使用 uv 安装：uv add matplotlib。笔记本交互：uv add matplotlib ipympl，然后在 Jupyter 中启用 %matplotlib widget 或 %matplotlib ipympl。Matplotlib 3.10 需要 Python 3.10+ 和 NumPy 1.23+。非交互式文件输出通过 Agg、PDF、SVG 等后端完成。GUI 窗口由 Matplotlib 自动选择可用后端；若在 uv 管理的 Python 中 TkAgg 失败，可用 uv self update 和 uv python upgrade --reinstall 更新，或安装 Qt 后端 uv add pyside6。

核心概念

Matplotlib 采用对象层级结构：Figure 是顶层容器；Axes 是实际绘图区域（一个 Figure 可含多个 Axes）；Artist 是图上所有可见元素（线、文本、刻度等）；Axis 是处理刻度和标签的数轴对象。

两种接口

pyplot 接口（隐式、MATLAB 风格）：import matplotlib.pyplot as plt; plt.plot([1,2,3,4]); plt.ylabel('some numbers'); plt.show()。适合快速简单绘图，自动维护状态，适合交互工作和简单脚本。

面向对象接口（显式）：fig, ax = plt.subplots(); ax.plot([1,2,3,4]); ax.set_ylabel('some numbers'); plt.show()。推荐用于大多数场景，对图形和坐标轴控制更明确，适合多子图的复杂图形，更易维护和调试。

常见工作流

基础绘图：创建 fig, ax = plt.subplots(figsize=(10,6))，用 numpy 生成数据，ax.plot 绘制并加 label，设置 xlabel、ylabel、title、legend、grid，最后 fig.savefig('plot.png', dpi=300, bbox_inches='tight') 并 plt.show()。

多子图：方法一为规则网格 plt.subplots(2,2)；方法二为 mosaic 布局 plt.subplot_mosaic；方法三为 GridSpec 最大控制。

图表类型与用途：折线图用于时间序列、连续数据、趋势；散点图用于变量关系与相关性；柱状图用于分类比较（barh 为水平柱状）；直方图用于分布；热力图用于矩阵数据与相关性（imshow + colorbar）；等高线图用于二维平面上的三维数据；箱线图用于统计分布；小提琴图用于分布密度。

样式与自定义：颜色可用命名色、十六进制、RGB 元组、colormap；可用 plt.style.use 应用预定义样式（如 'ggplot'、'bmh'、'fivethirtyeight'），plt.style.available 列出全部；可用 rcParams 设置字号；用 ax.text 和 ax.annotate 添加文本与注释。

保存图形：fig.savefig 支持 PNG（dpi=300）、PDF、SVG 等；重要参数包括 dpi（出版 300、网页 150、屏幕 72）、bbox_inches='tight'、facecolor='white'、transparent=True。

3D 绘图：fig.add_subplot(111, projection='3d')，支持 plot_surface、scatter、plot 及三轴标签。

最佳实践

生产代码使用面向对象接口，pyplot 仅用于快速交互探索；创建时设置 figsize；按输出介质选择 DPI；用 constrained_layout=True 或 tight_layout() 防止元素重叠；colormap 按数据类型选择（顺序型 viridis/plasma/inferno、发散型 coolwarm/RdBu、定性型 tab10/Set3），避免彩虹色 jet；使用色盲友好 colormap（viridis、cividis），柱状图除颜色外加图案/阴影，保证对比度并包含描述性标签和图例；大数据集用 rasterized=True 减小文件体积，绘图前适当降采样，动画用 blitting 提升性能；代码组织上封装清晰的绘图函数。

辅助脚本与参考

scripts/plot_template.py 为演示多种图表类型与最佳实践的模板，用法 uv run python scripts/plot_template.py；scripts/style_configurator.py 为交互式样式配置工具，用法 uv run python scripts/style_configurator.py。参考文档包括 references/plot_types.md、references/styling_guide.md、references/api_reference.md、references/common_issues.md。

与其他工具集成

可与 NumPy/Pandas（直接从数组和 DataFrame 绘图）、Seaborn（基于 matplotlib 的高级统计可视化）、Jupyter（%matplotlib inline 或 %matplotlib widget）、GUI 框架（Tkinter、Qt、wxPython）集成。

常见问题

元素重叠用 constrained_layout=True 或 tight_layout()；状态混乱用 OO 接口避免 pyplot 状态机问题；多图形内存问题用 plt.close(fig) 显式关闭；字体警告可安装字体或设置 plt.rcParams['font.sans-serif']；DPI 混淆需记住 figsize 单位是英寸，像素 = dpi × 英寸。

代理操作流程

检查环境，确认数据源、每张图要传达的信息和目标介质；确定输入，确认格式、标识符和参数，有歧义时询问而非猜测；先渲染一张最终尺寸的小版本检查可读性；执行完整任务；验证结果（坐标轴、单位、误差棒已标注，颜色色盲安全，数字与底层数据一致）；报告运行内容（版本、命令、参数）、已检查项和仍不确定项。

完整性规则

不得捏造结果、参数、标识符、引用或统计；无法运行或验证时如实说明；不得为改善图形外观而修改数据，图像调整须统一应用并披露；版本相关细节可能过时，须对照已安装版本的官方文档确认；涉及花钱、占用共享 GPU 或云配额、触及个人或患者数据、不可撤销的操作前须先询问。

技能介绍