名称: matplotlib 描述: “基础绘图库。创建线图、散点图、条形图、直方图、热力图、3D图、子图，导出PNG/PDF/SVG格式，适用于科学可视化和出版图表。”

Matplotlib

概述

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

何时使用此技能

此技能应在以下情况下使用：

创建任何类型的图表（线图、散点图、条形图、直方图、热力图、等高线图等）
生成科学或统计可视化
自定义图表外观（颜色、样式、标签、图例）
创建包含子图的多面板图表
导出可视化图表到各种格式（PNG、PDF、SVG等）
构建交互式图表或动画
处理 3D 可视化
将图表集成到 Jupyter 笔记本或 GUI 应用程序中

核心概念

Matplotlib 层级结构

Matplotlib 使用对象的层级结构：

Figure - 所有绘图元素的顶级容器
Axes - 实际显示数据的绘图区域（一个 Figure 可包含多个 Axes）
Artist - 图表上所有可见元素（线、文本、刻度等）
Axis - 处理刻度和标签的数字线对象（x轴、y轴）

两种接口

1. pyplot 接口（隐式，MATLAB风格）

import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4])
plt.ylabel('一些数字')
plt.show()

适用于快速、简单的图表
自动维护状态
适合交互式工作和简单脚本

2. 面向对象接口（显式）

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3, 4])
ax.set_ylabel('一些数字')
plt.show()

推荐用于大多数用例
更明确地控制图形和坐标轴
更适合具有多个子图的复杂图表
更容易维护和调试

常见工作流程

1. 基本图表创建

单图表工作流程：

import matplotlib.pyplot as plt
import numpy as np

# 创建图形和坐标轴（面向对象接口 - 推荐）
fig, ax = plt.subplots(figsize=(10, 6))

# 生成和绘图数据
x = np.linspace(0, 2*np.pi, 100)
ax.plot(x, np.sin(x), label='sin(x)')
ax.plot(x, np.cos(x), label='cos(x)')

# 自定义
ax.set_xlabel('x')
ax.set_ylabel('y')
ax.set_title('三角函数')
ax.legend()
ax.grid(True, alpha=0.3)

# 保存和/或显示
plt.savefig('plot.png', dpi=300, bbox_inches='tight')
plt.show()

2. 多个子图

创建子图布局：

# 方法1：规则网格
fig, axes = plt.subplots(2, 2, figsize=(12, 10))
axes[0, 0].plot(x, y1)
axes[0, 1].scatter(x, y2)
axes[1, 0].bar(categories, values)
axes[1, 1].hist(data, bins=30)

# 方法2：马赛克布局（更灵活）
fig, axes = plt.subplot_mosaic([['left', 'right_top'],
                                 ['left', 'right_bottom']],
                                figsize=(10, 8))
axes['left'].plot(x, y)
axes['right_top'].scatter(x, y)
axes['right_bottom'].hist(data)

# 方法3：GridSpec（最大控制）
from matplotlib.gridspec import GridSpec
fig = plt.figure(figsize=(12, 8))
gs = GridSpec(3, 3, figure=fig)
ax1 = fig.add_subplot(gs[0, :])  # 顶部行，所有列
ax2 = fig.add_subplot(gs[1:, 0])  # 底部两行，第一列
ax3 = fig.add_subplot(gs[1:, 1:])  # 底部两行，最后两列

3. 图表类型及用例

线图 - 时间序列、连续数据、趋势

ax.plot(x, y, linewidth=2, linestyle='--', marker='o', color='blue')

散点图 - 变量之间的关系、相关性

ax.scatter(x, y, s=sizes, c=colors, alpha=0.6, cmap='viridis')

条形图 - 分类比较

ax.bar(categories, values, color='steelblue', edgecolor='black')
# 对于水平条形图：
ax.barh(categories, values)

直方图 - 分布

ax.hist(data, bins=30, edgecolor='black', alpha=0.7)

热力图 - 矩阵数据、相关性

im = ax.imshow(matrix, cmap='coolwarm', aspect='auto')
plt.colorbar(im, ax=ax)

等高线图 - 2D 平面上的 3D 数据

contour = ax.contour(X, Y, Z, levels=10)
ax.clabel(contour, inline=True, fontsize=8)

箱线图 - 统计分布

ax.boxplot([data1, data2, data3], labels=['A', 'B', 'C'])

小提琴图 - 分布密度

ax.violinplot([data1, data2, data3], positions=[1, 2, 3])

有关全面图表类型示例和变体，请参阅 references/plot_types.md。

4. 样式和自定义

颜色指定方法：

命名颜色：'red'、'blue'、'steelblue'
十六进制代码：'#FF5733'
RGB 元组：(0.1, 0.2, 0.3)
颜色映射：cmap='viridis'、cmap='plasma'、cmap='coolwarm'

使用样式表：

plt.style.use('seaborn-v0_8-darkgrid')  # 应用预定义样式
# 可用样式：'ggplot'、'bmh'、'fivethirtyeight' 等
print(plt.style.available)  # 列出所有可用样式

使用 rcParams 自定义：

plt.rcParams['font.size'] = 12
plt.rcParams['axes.labelsize'] = 14
plt.rcParams['axes.titlesize'] = 16
plt.rcParams['xtick.labelsize'] = 10
plt.rcParams['ytick.labelsize'] = 10
plt.rcParams['legend.fontsize'] = 12
plt.rcParams['figure.titlesize'] = 18

文本和标注：

ax.text(x, y, '标注', fontsize=12, ha='center')
ax.annotate('重要点', xy=(x, y), xytext=(x+1, y+1),
            arrowprops=dict(arrowstyle='->', color='red'))

有关详细样式选项和颜色映射指南，请参阅 references/styling_guide.md。

5. 保存图表

导出到各种格式：

# 高分辨率 PNG 用于演示/论文
plt.savefig('figure.png', dpi=300, bbox_inches='tight', facecolor='white')

# 矢量格式用于出版物（可缩放）
plt.savefig('figure.pdf', bbox_inches='tight')
plt.savefig('figure.svg', bbox_inches='tight')

# 透明背景
plt.savefig('figure.png', dpi=300, bbox_inches='tight', transparent=True)

重要参数：

dpi：分辨率（300 用于出版物，150 用于网页，72 用于屏幕）
bbox_inches='tight'：移除多余空白
facecolor='white'：确保白色背景（适用于透明主题）
transparent=True：透明背景

6. 处理 3D 图表

from mpl_toolkits.mplot3d import Axes3D

fig = plt.figure(figsize=(10, 8))
ax = fig.add_subplot(111, projection='3d')

# 表面图
ax.plot_surface(X, Y, Z, cmap='viridis')

# 3D 散点图
ax.scatter(x, y, z, c=colors, marker='o')

# 3D 线图
ax.plot(x, y, z, linewidth=2)

# 标签
ax.set_xlabel('X 标签')
ax.set_ylabel('Y 标签')
ax.set_zlabel('Z 标签')

最佳实践

1. 接口选择

使用面向对象接口（fig, ax = plt.subplots()）用于生产代码
仅将 pyplot 接口用于快速交互式探索
始终显式创建图形，而非依赖隐式状态

2. 图形大小和 DPI

在创建时设置 figsize：fig, ax = plt.subplots(figsize=(10, 6))
为输出媒介使用适当的 DPI：
- 屏幕/笔记本：72-100 dpi
- 网页：150 dpi
- 打印/出版物：300 dpi

3. 布局管理

使用 constrained_layout=True 或 tight_layout() 防止元素重叠
fig, ax = plt.subplots(constrained_layout=True) 推荐用于自动间距

4. 颜色映射选择

顺序（viridis、plasma、inferno）：有序数据，具有一致的进展
发散（coolwarm、RdBu）：数据具有有意义的中心点（如零）
定性（tab10、Set3）：分类/名义数据
避免彩虹颜色映射（jet） - 它们不是感知均匀的

5. 可访问性

使用色盲友好的颜色映射（viridis、cividis）
为条形图添加图案/阴影，除了颜色
确保元素间有足够的对比度
包含描述性标签和图例

6. 性能

对于大型数据集，在绘图调用中使用 rasterized=True 以减少文件大小
在绘图前使用适当的数据缩减（例如，下采样密集时间序列）
对于动画，使用位块传输以获得更好的性能

7. 代码组织

# 良好实践：清晰结构
def create_analysis_plot(data, title):
    """创建标准化分析图表。"""
    fig, ax = plt.subplots(figsize=(10, 6), constrained_layout=True)

    # 绘图数据
    ax.plot(data['x'], data['y'], linewidth=2)

    # 自定义
    ax.set_xlabel('X 轴标签', fontsize=12)
    ax.set_ylabel('Y 轴标签', fontsize=12)
    ax.set_title(title, fontsize=14, fontweight='bold')
    ax.grid(True, alpha=0.3)

    return fig, ax

# 使用函数
fig, ax = create_analysis_plot(my_data, '我的分析')
plt.savefig('analysis.png', dpi=300, bbox_inches='tight')

快速参考脚本

此技能包含 scripts/ 目录中的助手脚本：

`plot_template.py`

模板脚本演示了各种图表类型和最佳实践。将此作为创建新可视化的起点。

用法：

python scripts/plot_template.py

`style_configurator.py`

交互式实用程序，用于配置 matplotlib 样式偏好并生成自定义样式表。

用法：

python scripts/style_configurator.py

详细参考资料

有关全面信息，请参阅参考文档：

references/plot_types.md - 完整的图表类型目录，带有代码示例和用例
references/styling_guide.md - 详细样式选项、颜色映射和自定义
references/api_reference.md - 核心类和方法参考
references/common_issues.md - 常见问题的故障排除指南

与其他工具集成

Matplotlib 与以下工具集成良好：

NumPy/Pandas - 直接从数组和 DataFrame 绘图
Seaborn - 基于 matplotlib 构建的高级统计可视化
Jupyter - 使用 %matplotlib inline 或 %matplotlib widget 进行交互式绘图
GUI 框架 - 嵌入到 Tkinter、Qt、wxPython 应用程序中

常见问题

元素重叠：使用 constrained_layout=True 或 tight_layout()
状态混淆：使用面向对象接口避免 pyplot 状态机问题
内存问题（多图表）：使用 plt.close(fig) 显式关闭图表
字体警告：安装字体或使用 plt.rcParams['font.sans-serif'] 抑制警告
DPI 混淆：记住 figsize 是以英寸为单位，而不是像素：像素 = dpi * 英寸

其他资源

官方文档：https://matplotlib.org/
画廊：https://matplotlib.org/stable/gallery/index.html
备忘单：https://matplotlib.org/cheatsheets/
教程：https://matplotlib.org/stable/tutorials/index.html