matplotlib

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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:

Figure - The top-level container for all plot elements
Axes - The actual plotting area where data is displayed (one Figure can contain multiple Axes)
Artist - Everything visible on the figure (lines, text, ticks, etc.)
Axis - The number line objects (x-axis, y-axis) that handle ticks and labels

Matplotlib采用分层的对象结构：

Figure - 所有图表元素的顶级容器
Axes - 用于显示数据的实际绘图区域（一个Figure可包含多个Axes）
Artist - 图表中所有可见元素（线条、文本、刻度等）
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))

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

Customize

自定义设置

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)

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)

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

Vector format for publications (scalable)

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

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

3D scatter

3D散点图

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

3D line plot

3D折线图

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

Labels

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

常见陷阱

Overlapping elements: Use
```
constrained_layout=True
```
or
```
tight_layout()
```
State confusion: Use OO interface to avoid pyplot state machine issues
Memory issues with many figures: Close figures explicitly with
```
plt.close(fig)
```
Font warnings: Install fonts or suppress warnings with
```
plt.rcParams['font.sans-serif']
```
DPI confusion: Remember that figsize is in inches, not pixels:
```
pixels = dpi * inches
```

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

Additional Resources

额外资源

Official documentation: https://matplotlib.org/
Gallery: https://matplotlib.org/stable/gallery/index.html
Cheatsheets: https://matplotlib.org/cheatsheets/
Tutorials: https://matplotlib.org/stable/tutorials/index.html

官方文档：https://matplotlib.org/
图库：https://matplotlib.org/stable/gallery/index.html
速查表：https://matplotlib.org/cheatsheets/
教程：https://matplotlib.org/stable/tutorials/index.html

matplotlib

Original

Translation

Matplotlib

Matplotlib

Overview

概述

When to Use This Skill

适用场景

Core Concepts

核心概念

The Matplotlib Hierarchy

Matplotlib层级结构

Two Interfaces

两种接口

Common Workflows

常见工作流

1. Basic Plot Creation

1. 基础图表创建

Create figure and axes (OO interface - RECOMMENDED)

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

Generate and plot data

生成并绘制数据

Customize

自定义设置

Save and/or display

保存和/或显示图表

2. Multiple Subplots

2. 多子图创建

Method 1: Regular grid

方法1：规则网格

Method 2: Mosaic layout (more flexible)

方法2：马赛克布局（更灵活）

Method 3: GridSpec (maximum control)

方法3：GridSpec（最大控制度）

3. Plot Types and Use Cases

3. 图表类型及适用场景

For horizontal bars:

水平柱状图：

4. Styling and Customization

4. 样式与自定义设置

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

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

5. Saving Figures

5. 保存图表

High-resolution PNG for presentations/papers

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

Vector format for publications (scalable)

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

Transparent background

透明背景

6. Working with 3D Plots

6. 3D图表制作

Surface plot

曲面图

3D scatter

3D散点图

3D line plot

3D折线图

Labels

标签

Best Practices

最佳实践

1. Interface Selection

1. 接口选择

2. Figure Size and DPI

2. 图表尺寸与DPI

3. Layout Management

3. 布局管理

4. Colormap Selection

4. 颜色映射选择

5. Accessibility

5. 可访问性

6. Performance

6. 性能优化

7. Code Organization

7. 代码组织

Good practice: Clear structure

最佳实践：清晰的结构

Use the function

`plot_template.py`

`plot_template.py`

`style_configurator.py`

`style_configurator.py`