Back to Details

matplotlib

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Matplotlib

Matplotlib

Overview

概述

Matplotlib is Python's foundational visualization library for creating static, animated, and interactive plots. This skill provides guidance on using matplotlib effectively, covering both the pyplot interface (MATLAB-style) and the object-oriented API (Figure/Axes), along with best practices for creating publication-quality visualizations.
Matplotlib是Python的基础可视化库，用于创建静态、动画和交互式图表。本技能提供有效使用Matplotlib的指导，涵盖pyplot接口（MATLAB风格）和面向对象API（Figure/Axes），以及创建符合出版质量可视化的最佳实践。

When to Use This Skill

何时使用本技能

This skill should be used when:
  • Creating any type of plot or chart (line, scatter, bar, histogram, heatmap, contour, etc.)
  • Generating scientific or statistical visualizations
  • Customizing plot appearance (colors, styles, labels, legends)
  • Creating multi-panel figures with subplots
  • Exporting visualizations to various formats (PNG, PDF, SVG, etc.)
  • Building interactive plots or animations
  • Working with 3D visualizations
  • Integrating plots into Jupyter notebooks or GUI applications
在以下场景中应使用本技能：
  • 创建任何类型的图表（折线图、散点图、柱状图、直方图、热力图、等高线图等）
  • 生成科学或统计可视化结果
  • 自定义图表外观（颜色、样式、标签、图例）
  • 创建包含子图的多面板图形
  • 将可视化结果导出为多种格式（PNG、PDF、SVG等）
  • 构建交互式图表或动画
  • 处理3D可视化
  • 将图表集成到Jupyter笔记本或GUI应用程序中

Core Concepts

核心概念

The Matplotlib Hierarchy

Matplotlib层级结构

Matplotlib uses a hierarchical structure of objects:
  1. Figure - The top-level container for all plot elements
  2. Axes - The actual plotting area where data is displayed (one Figure can contain multiple Axes)
  3. Artist - Everything visible on the figure (lines, text, ticks, etc.)
  4. Axis - The number line objects (x-axis, y-axis) that handle ticks and labels
Matplotlib使用对象的层级结构：
  1. Figure - 所有图表元素的顶级容器
  2. Axes - 显示数据的实际绘图区域（一个Figure可包含多个Axes）
  3. Artist - 图表上所有可见元素（线条、文本、刻度等）
  4. Axis - 处理刻度和标签的数轴对象（x轴、y轴）

Two Interfaces

两种接口

1. pyplot Interface (Implicit, MATLAB-style)
python
import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4])
plt.ylabel('some numbers')
plt.show()
  • Convenient for quick, simple plots
  • Maintains state automatically
  • Good for interactive work and simple scripts
2. Object-Oriented Interface (Explicit)
python
import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3, 4])
ax.set_ylabel('some numbers')
plt.show()
  • Recommended for most use cases
  • More explicit control over figure and axes
  • Better for complex figures with multiple subplots
  • Easier to maintain and debug
1. pyplot接口（隐式，MATLAB风格）
python
import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4])
plt.ylabel('some numbers')
plt.show()
  • 适用于快速创建简单图表
  • 自动维护状态
  • 适合交互式工作和简单脚本
2. 面向对象接口（显式）
python
import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3, 4])
ax.set_ylabel('some numbers')
plt.show()
  • 推荐用于大多数使用场景
  • 对Figure和Axes有更明确的控制
  • 更适合包含多个子图的复杂图形
  • 更易于维护和调试

Common Workflows

常见工作流程

1. Basic Plot Creation

1. 基础图表创建

Single plot workflow:
python
import matplotlib.pyplot as plt
import numpy as np
单图表工作流程：
python
import matplotlib.pyplot as plt
import numpy as np

Create figure and axes (OO interface - RECOMMENDED)

创建Figure和Axes（面向对象接口 - 推荐）

fig, ax = plt.subplots(figsize=(10, 6))
fig, ax = plt.subplots(figsize=(10, 6))

Generate and plot data

生成并绘制数据

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)')
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)')

Customize

自定义设置

ax.set_xlabel('x') ax.set_ylabel('y') ax.set_title('Trigonometric Functions') ax.legend() ax.grid(True, alpha=0.3)
ax.set_xlabel('x') ax.set_ylabel('y') ax.set_title('Trigonometric Functions') ax.legend() ax.grid(True, alpha=0.3)

Save and/or display

保存和/或显示

plt.savefig('plot.png', dpi=300, bbox_inches='tight') plt.show()
undefined
plt.savefig('plot.png', dpi=300, bbox_inches='tight') plt.show()
undefined

2. Multiple Subplots

2. 多子图创建

Creating subplot layouts:
python
undefined
创建子图布局：
python
undefined

Method 1: Regular grid

方法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)
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)

Method 2: Mosaic layout (more flexible)

方法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)
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)

Method 3: GridSpec (maximum control)

方法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, :]) # Top row, all columns ax2 = fig.add_subplot(gs[1:, 0]) # Bottom two rows, first column ax3 = fig.add_subplot(gs[1:, 1:]) # Bottom two rows, last two columns
undefined
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:]) # 底部两行，最后两列
undefined

3. Plot Types and Use Cases

3. 图表类型及适用场景

Line plots - Time series, continuous data, trends
python
ax.plot(x, y, linewidth=2, linestyle='--', marker='o', color='blue')
Scatter plots - Relationships between variables, correlations
python
ax.scatter(x, y, s=sizes, c=colors, alpha=0.6, cmap='viridis')
Bar charts - Categorical comparisons
python
ax.bar(categories, values, color='steelblue', edgecolor='black')
折线图 - 时间序列、连续数据、趋势
python
ax.plot(x, y, linewidth=2, linestyle='--', marker='o', color='blue')
散点图 - 变量间关系、相关性
python
ax.scatter(x, y, s=sizes, c=colors, alpha=0.6, cmap='viridis')
柱状图 - 分类对比
python
ax.bar(categories, values, color='steelblue', edgecolor='black')

For horizontal bars:

水平柱状图：

ax.barh(categories, values)

**Histograms** - Distributions
```python
ax.hist(data, bins=30, edgecolor='black', alpha=0.7)
Heatmaps - Matrix data, correlations
python
im = ax.imshow(matrix, cmap='coolwarm', aspect='auto')
plt.colorbar(im, ax=ax)
Contour plots - 3D data on 2D plane
python
contour = ax.contour(X, Y, Z, levels=10)
ax.clabel(contour, inline=True, fontsize=8)
Box plots - Statistical distributions
python
ax.boxplot([data1, data2, data3], labels=['A', 'B', 'C'])
Violin plots - Distribution densities
python
ax.violinplot([data1, data2, data3], positions=[1, 2, 3])
For comprehensive plot type examples and variations, refer to 
references/plot_types.md
.
ax.barh(categories, values)

**直方图** - 分布情况
```python
ax.hist(data, bins=30, edgecolor='black', alpha=0.7)
热力图 - 矩阵数据、相关性
python
im = ax.imshow(matrix, cmap='coolwarm', aspect='auto')
plt.colorbar(im, ax=ax)
等高线图 - 2D平面上的3D数据
python
contour = ax.contour(X, Y, Z, levels=10)
ax.clabel(contour, inline=True, fontsize=8)
箱线图 - 统计分布
python
ax.boxplot([data1, data2, data3], labels=['A', 'B', 'C'])
小提琴图 - 分布密度
python
ax.violinplot([data1, data2, data3], positions=[1, 2, 3])
如需全面的图表类型示例及变体，请参考
references/plot_types.md
。

4. Styling and Customization

4. 样式与自定义

Color specification methods:
  • Named colors: 
    'red'
    , 
    'blue'
    , 
    'steelblue'
  • Hex codes: 
    '#FF5733'
  • RGB tuples: 
    (0.1, 0.2, 0.3)
  • Colormaps: 
    cmap='viridis'
    , 
    cmap='plasma'
    , 
    cmap='coolwarm'
Using style sheets:
python
plt.style.use('seaborn-v0_8-darkgrid')  # Apply predefined style
颜色指定方法：
  • 命名颜色：
    'red'
    , 
    'blue'
    , 
    'steelblue'
  • 十六进制代码：
    '#FF5733'
  • RGB元组：
    (0.1, 0.2, 0.3)
  • 颜色映射：
    cmap='viridis'
    , 
    cmap='plasma'
    , 
    cmap='coolwarm'
使用样式表：
python
plt.style.use('seaborn-v0_8-darkgrid')  # 应用预定义样式

Available styles: 'ggplot', 'bmh', 'fivethirtyeight', etc.

可用样式：'ggplot', 'bmh', 'fivethirtyeight'等

print(plt.style.available) # List all available styles

**Customizing with rcParams:**
```python
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
Text and annotations:
python
ax.text(x, y, 'annotation', fontsize=12, ha='center')
ax.annotate('important point', xy=(x, y), xytext=(x+1, y+1),
            arrowprops=dict(arrowstyle='->', color='red'))
For detailed styling options and colormap guidelines, see 
references/styling_guide.md
.
print(plt.style.available) # 列出所有可用样式

**使用rcParams自定义：**
```python
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
文本与注释：
python
ax.text(x, y, 'annotation', fontsize=12, ha='center')
ax.annotate('important point', xy=(x, y), xytext=(x+1, y+1),
            arrowprops=dict(arrowstyle='->', color='red'))
如需详细的样式选项和颜色映射指南，请参阅
references/styling_guide.md
。

5. Saving Figures

5. 保存图形

Export to various formats:
python
undefined
导出为多种格式：
python
undefined

High-resolution PNG for presentations/papers

用于演示/论文的高分辨率PNG

plt.savefig('figure.png', dpi=300, bbox_inches='tight', facecolor='white')
plt.savefig('figure.png', dpi=300, bbox_inches='tight', facecolor='white')

Vector format for publications (scalable)

用于出版物的矢量格式（可缩放）

plt.savefig('figure.pdf', bbox_inches='tight') plt.savefig('figure.svg', bbox_inches='tight')
plt.savefig('figure.pdf', bbox_inches='tight') plt.savefig('figure.svg', bbox_inches='tight')

Transparent background

透明背景

plt.savefig('figure.png', dpi=300, bbox_inches='tight', transparent=True)

**Important parameters:**
- `dpi`: Resolution (300 for publications, 150 for web, 72 for screen)
- `bbox_inches='tight'`: Removes excess whitespace
- `facecolor='white'`: Ensures white background (useful for transparent themes)
- `transparent=True`: Transparent background
plt.savefig('figure.png', dpi=300, bbox_inches='tight', transparent=True)

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

6. Working with 3D Plots

6. 处理3D图表

python
from mpl_toolkits.mplot3d import Axes3D

fig = plt.figure(figsize=(10, 8))
ax = fig.add_subplot(111, projection='3d')
python
from mpl_toolkits.mplot3d import Axes3D

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

Surface plot

曲面图

ax.plot_surface(X, Y, Z, cmap='viridis')
ax.plot_surface(X, Y, Z, cmap='viridis')

3D scatter

3D散点图

ax.scatter(x, y, z, c=colors, marker='o')
ax.scatter(x, y, z, c=colors, marker='o')

3D line plot

3D折线图

ax.plot(x, y, z, linewidth=2)
ax.plot(x, y, z, linewidth=2)

Labels

标签

ax.set_xlabel('X Label') ax.set_ylabel('Y Label') ax.set_zlabel('Z Label')
undefined
ax.set_xlabel('X Label') ax.set_ylabel('Y Label') ax.set_zlabel('Z Label')
undefined

Best Practices

最佳实践

1. Interface Selection

1. 接口选择

  • Use the object-oriented interface (fig, ax = plt.subplots()) for production code
  • Reserve pyplot interface for quick interactive exploration only
  • Always create figures explicitly rather than relying on implicit state
  • 使用面向对象接口（fig, ax = plt.subplots()）编写生产代码
  • 仅在快速交互式探索时使用pyplot接口
  • 始终显式创建图形，而非依赖隐式状态

2. Figure Size and DPI

2. 图形尺寸与DPI

  • Set figsize at creation: 
    fig, ax = plt.subplots(figsize=(10, 6))
  • Use appropriate DPI for output medium:
    • Screen/notebook: 72-100 dpi
    • Web: 150 dpi
    • Print/publications: 300 dpi
  • 创建时设置figsize：
    fig, ax = plt.subplots(figsize=(10, 6))
  • 根据输出媒介使用合适的DPI：
    • 屏幕/笔记本：72-100 dpi
    • 网页：150 dpi
    • 打印/出版物：300 dpi

3. Layout Management

3. 布局管理

  • Use 
    constrained_layout=True
    or 
    tight_layout()
    to prevent overlapping elements
  • fig, ax = plt.subplots(constrained_layout=True)
    is recommended for automatic spacing
  • 使用
    constrained_layout=True
    或
    tight_layout()
    防止元素重叠
  • 推荐使用
    fig, ax = plt.subplots(constrained_layout=True)
    实现自动间距

4. Colormap Selection

4. 颜色映射选择

  • Sequential (viridis, plasma, inferno): Ordered data with consistent progression
  • Diverging (coolwarm, RdBu): Data with meaningful center point (e.g., zero)
  • Qualitative (tab10, Set3): Categorical/nominal data
  • Avoid rainbow colormaps (jet) - they are not perceptually uniform
  • 顺序型（viridis、plasma、inferno）：具有一致渐变的有序数据
  • 发散型（coolwarm、RdBu）：有意义中心点的数据（如零值）
  • 定性型（tab10、Set3）：分类/名义数据
  • 避免彩虹色映射（jet）- 它们不符合感知一致性

5. Accessibility

5. 可访问性

  • Use colorblind-friendly colormaps (viridis, cividis)
  • Add patterns/hatching for bar charts in addition to colors
  • Ensure sufficient contrast between elements
  • Include descriptive labels and legends
  • 使用适合色觉障碍者的颜色映射（viridis、cividis）
  • 除颜色外，为柱状图添加图案/阴影
  • 确保元素间有足够对比度
  • 包含描述性标签和图例

6. Performance

6. 性能

  • For large datasets, use 
    rasterized=True
    in plot calls to reduce file size
  • Use appropriate data reduction before plotting (e.g., downsample dense time series)
  • For animations, use blitting for better performance
  • 处理大型数据集时，在绘图调用中使用
    rasterized=True
    减小文件大小
  • 绘图前进行适当的数据缩减（如下采样密集时间序列）
  • 制作动画时，使用blitting提升性能

7. Code Organization

7. 代码组织

python
undefined
python
undefined

Good practice: Clear structure

良好实践：清晰的结构

def create_analysis_plot(data, title): """Create standardized analysis plot.""" fig, ax = plt.subplots(figsize=(10, 6), constrained_layout=True)
# Plot data
ax.plot(data['x'], data['y'], linewidth=2)

# Customize
ax.set_xlabel('X Axis Label', fontsize=12)
ax.set_ylabel('Y Axis Label', fontsize=12)
ax.set_title(title, fontsize=14, fontweight='bold')
ax.grid(True, alpha=0.3)

return fig, ax
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 Axis Label', fontsize=12)
ax.set_ylabel('Y Axis Label', fontsize=12)
ax.set_title(title, fontsize=14, fontweight='bold')
ax.grid(True, alpha=0.3)

return fig, ax

Use the function

使用函数

fig, ax = create_analysis_plot(my_data, 'My Analysis') plt.savefig('analysis.png', dpi=300, bbox_inches='tight')
undefined
fig, ax = create_analysis_plot(my_data, 'My Analysis') plt.savefig('analysis.png', dpi=300, bbox_inches='tight')
undefined

Quick Reference Scripts

快速参考脚本

This skill includes helper scripts in the 
scripts/
directory:
本技能在
scripts/
目录中包含辅助脚本：

plot_template.py

plot_template.py

Template script demonstrating various plot types with best practices. Use this as a starting point for creating new visualizations.
Usage:
bash
python scripts/plot_template.py
演示各类图表及最佳实践的模板脚本。可将其作为创建新可视化的起点。
使用方法：
bash
python scripts/plot_template.py

style_configurator.py

style_configurator.py

Interactive utility to configure matplotlib style preferences and generate custom style sheets.
Usage:
bash
python scripts/style_configurator.py
交互式工具，用于配置Matplotlib样式偏好并生成自定义样式表。
使用方法：
bash
python scripts/style_configurator.py

Detailed References

详细参考资料

For comprehensive information, consult the reference documents:
  • references/plot_types.md
     - Complete catalog of plot types with code examples and use cases
  • references/styling_guide.md
     - Detailed styling options, colormaps, and customization
  • references/api_reference.md
     - Core classes and methods reference
  • references/common_issues.md
     - Troubleshooting guide for common problems
如需全面信息，请查阅参考文档：
  • references/plot_types.md
     - 完整的图表类型目录，包含代码示例和适用场景
  • references/styling_guide.md
     - 详细的样式选项、颜色映射和自定义指南
  • references/api_reference.md
     - 核心类和方法参考
  • references/common_issues.md
     - 常见问题排查指南

Integration with Other Tools

与其他工具的集成

Matplotlib integrates well with:
  • NumPy/Pandas - Direct plotting from arrays and DataFrames
  • Seaborn - High-level statistical visualizations built on matplotlib
  • Jupyter - Interactive plotting with 
    %matplotlib inline
    or 
    %matplotlib widget
  • GUI frameworks - Embedding in Tkinter, Qt, wxPython applications
Matplotlib可与以下工具良好集成：
  • NumPy/Pandas - 直接从数组和DataFrame绘图
  • Seaborn - 基于Matplotlib构建的高级统计可视化库
  • Jupyter - 使用
    %matplotlib inline
    或
    %matplotlib widget
    实现交互式绘图
  • GUI框架 - 嵌入到Tkinter、Qt、wxPython应用程序中

Common Gotchas

常见陷阱

  1. Overlapping elements: Use 
    constrained_layout=True
    or 
    tight_layout()
  2. State confusion: Use OO interface to avoid pyplot state machine issues
  3. Memory issues with many figures: Close figures explicitly with 
    plt.close(fig)
  4. Font warnings: Install fonts or suppress warnings with 
    plt.rcParams['font.sans-serif']
  5. DPI confusion: Remember that figsize is in inches, not pixels: 
    pixels = dpi * inches
  1. 元素重叠：使用
    constrained_layout=True
    或
    tight_layout()
  2. 状态混淆：使用面向对象接口避免pyplot状态机问题
  3. 多图形内存问题：显式使用
    plt.close(fig)
    关闭图形
  4. 字体警告：安装字体或使用
    plt.rcParams['font.sans-serif']
    抑制警告
  5. DPI混淆：记住figsize单位是英寸而非像素：
    pixels = dpi * inches

Additional Resources

额外资源

Limitations

局限性

  • Use this skill only when the task clearly matches the scope described above.
  • Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
  • Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
  • 仅当任务明确符合上述描述的范围时使用本技能。
  • 不要将输出作为环境特定验证、测试或专家评审的替代方案。
  • 如果缺少所需输入、权限、安全边界或成功标准，请停止操作并请求澄清。