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`：分辨率（出版物用300dpi，网页用150dpi，屏幕显示用72dpi）
- `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

额外资源