快速入门指南

本教程涵盖了一些基本用法模式和最佳实践，以帮助你开始使用 Matplotlib。

import matplotlib.pyplot as plt
import numpy as np

一个简单的示例

Matplotlib 在 Figure（例如，窗口、Jupyter 小部件等）上绘制数据，每个都可以包含一个或多个 Axes，即一个可以根据 x-y 坐标（或极坐标图中的 theta-r，3D 图中的 x-y-z 等）指定点的区域。使用 pyplot.subplots 是创建带有 Axes 的 Figure 的最简单方法。然后，我们可以使用 Axes.plot 在 Axes 上绘制一些数据，并使用 show 显示图形

fig, ax = plt.subplots()             # Create a figure containing a single Axes.
ax.plot([1, 2, 3, 4], [1, 4, 2, 3])  # Plot some data on the Axes.
plt.show()                           # Show the figure.

根据您所处的工作环境，可以省略 plt.show()。例如，在 Jupyter 笔记本中就是这种情况，它会自动显示在代码单元格中创建的所有图形。

图形的部分

以下是 Matplotlib 图形组件。

Figure

整个图形。Figure 跟踪所有子 Axes、一组“特殊”Artist（标题、图形图例、颜色条等），甚至嵌套的子图形。

通常，你可以通过下列函数之一创建一个新图形

fig = plt.figure()             # an empty figure with no Axes
fig, ax = plt.subplots()       # a figure with a single Axes
fig, axs = plt.subplots(2, 2)  # a figure with a 2x2 grid of Axes
# a figure with one Axes on the left, and two on the right:
fig, axs = plt.subplot_mosaic([['left', 'right_top'],
                               ['left', 'right_bottom']])

subplots() 和 subplot_mosaic 是便捷函数，它们在图形中另外创建了轴对象，但是你也可以在稍后手动添加轴。

有关图形的更多信息，包括平移和缩放，请参阅 图形简介。

Axes

轴是附加到图形的艺术家，它包含一个用于绘制数据的区域，并且通常包括两个（或在 3D 的情况下为三个）Axis 对象（注意轴和轴线之间的差异），它们提供刻度和刻度标签，以便为轴中的数据提供刻度。每个Axes 还有一个标题（通过 set_title() 设置），一个 x 标签（通过 set_xlabel() 设置），和一个通过 set_ylabel() 设置的 y 标签。

Axes 方法是配置绘图大部分内容（添加数据、控制轴刻度和限制、添加标签等）的主要接口。

Axis

这些对象设置比例和限制，并生成刻度（轴上的标记）和刻度标签（标记刻度的字符串）。刻度的定位由 Locator 对象确定，刻度标签字符串由 Formatter 格式化。正确的 Locator 和 Formatter 组合可以非常精细地控制刻度位置和标签。

Artist

基本上，图形上可见的所有内容都是 Artist（甚至 Figure、Axes 和 Axis 对象）。这包括 Text 对象、Line2D 对象、collections 对象、Patch 对象等。在渲染图形时，所有 Artist 都会绘制到画布上。大多数 Artist 都与 Axes 绑定；此类 Artist 不能由多个 Axes 共享，也不能从一个 Axes 移动到另一个 Axes。

绘图函数的输入类型

绘图函数期望 numpy.array 或 numpy.ma.masked_array 作为输入，或可以传递给 numpy.asarray 的对象。与数组类似的类（“类数组”），如 pandas 数据对象和 numpy.matrix 可能无法按预期工作。常见的约定是在绘图前将这些转换为 numpy.array 对象。例如，要转换 numpy.matrix

b = np.matrix([[1, 2], [3, 4]])
b_asarray = np.asarray(b)

大多数方法还将解析字符串可索引对象，如 dict、结构化 numpy 数组 或 pandas.DataFrame。Matplotlib 允许您提供 data 关键字参数并生成绘图，传递对应于 x 和 y 变量的字符串。

np.random.seed(19680801)  # seed the random number generator.
data = {'a': np.arange(50),
        'c': np.random.randint(0, 50, 50),
        'd': np.random.randn(50)}
data['b'] = data['a'] + 10 * np.random.randn(50)
data['d'] = np.abs(data['d']) * 100

fig, ax = plt.subplots(figsize=(5, 2.7), layout='constrained')
ax.scatter('a', 'b', c='c', s='d', data=data)
ax.set_xlabel('entry a')
ax.set_ylabel('entry b')

编码样式

显式和隐式接口

如上所述，使用 Matplotlib 主要有两种方法

• 显式创建图形和坐标轴，并调用它们的方法（“面向对象 (OO) 样式”）。

• 依靠 pyplot 隐式创建和管理图形和坐标轴，并使用 pyplot 函数进行绘图。

参阅 Matplotlib 应用程序接口 (API) 以了解隐式和显式接口之间的权衡。

因此，可以使用面向对象 (OO) 样式

x = np.linspace(0, 2, 100)  # Sample data.

# Note that even in the OO-style, we use `.pyplot.figure` to create the Figure.
fig, ax = plt.subplots(figsize=(5, 2.7), layout='constrained')
ax.plot(x, x, label='linear')  # Plot some data on the Axes.
ax.plot(x, x**2, label='quadratic')  # Plot more data on the Axes...
ax.plot(x, x**3, label='cubic')  # ... and some more.
ax.set_xlabel('x label')  # Add an x-label to the Axes.
ax.set_ylabel('y label')  # Add a y-label to the Axes.
ax.set_title("Simple Plot")  # Add a title to the Axes.
ax.legend()  # Add a legend.

或 pyplot 样式

x = np.linspace(0, 2, 100)  # Sample data.

plt.figure(figsize=(5, 2.7), layout='constrained')
plt.plot(x, x, label='linear')  # Plot some data on the (implicit) Axes.
plt.plot(x, x**2, label='quadratic')  # etc.
plt.plot(x, x**3, label='cubic')
plt.xlabel('x label')
plt.ylabel('y label')
plt.title("Simple Plot")
plt.legend()

（此外，还有第三种方法，适用于将 Matplotlib 嵌入 GUI 应用程序的情况，该方法完全放弃 pyplot，即使用于创建图形也是如此。有关更多信息，请参阅图库中的相应部分：在图形用户界面中嵌入 Matplotlib。）

Matplotlib 的文档和示例同时使用面向对象 (OO) 和 pyplot 样式。一般来说，我们建议使用面向对象 (OO) 样式，特别是对于复杂绘图以及旨在作为更大项目一部分进行重复使用的函数和脚本。但是，pyplot 样式对于快速交互式工作非常方便。

注意

您可能会发现使用 pylab 接口的较早示例，通过 from pylab import *。强烈不建议使用这种方法。

制作辅助函数

如果您需要使用不同的数据集反复制作相同的绘图，或想要轻松包装 Matplotlib 方法，请使用下面推荐的签名函数。

def my_plotter(ax, data1, data2, param_dict):
    """
    A helper function to make a graph.
    """
    out = ax.plot(data1, data2, **param_dict)
    return out

然后，您将使用它两次来填充两个子绘图

data1, data2, data3, data4 = np.random.randn(4, 100)  # make 4 random data sets
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(5, 2.7))
my_plotter(ax1, data1, data2, {'marker': 'x'})
my_plotter(ax2, data3, data4, {'marker': 'o'})

请注意，如果您想将这些内容安装为 Python 包，或任何其他自定义内容，您可以使用网络上的众多模板之一；Matplotlib 在 mpl-cookiecutter 上有一个。

造型艺术家

大多数绘图方法都有艺术家的造型选项，可以在调用绘图方法时或从艺术家上的“设置器”访问这些选项。在下面的绘图中，我们手动设置 plot 创建的艺术家的颜色、线宽和线型，并且在事后使用 set_linestyle 设置第二条线的线型。

fig, ax = plt.subplots(figsize=(5, 2.7))
x = np.arange(len(data1))
ax.plot(x, np.cumsum(data1), color='blue', linewidth=3, linestyle='--')
l, = ax.plot(x, np.cumsum(data2), color='orange', linewidth=2)
l.set_linestyle(':')

颜色

Matplotlib 拥有一系列非常灵活的颜色，大多数 Artist 都接受这些颜色；请参阅 允许的颜色定义 以获取规范列表。一些 Artist 会采用多种颜色。例如，对于 scatter 图，标记的边缘可以与内部采用不同的颜色

fig, ax = plt.subplots(figsize=(5, 2.7))
ax.scatter(data1, data2, s=50, facecolor='C0', edgecolor='k')

线宽、线型和标记大小

线宽通常以印刷点为单位（1 pt = 1/72 英寸），并且适用于具有描边线的 Artist。类似地，描边线可以具有线型。请参阅 线型示例。

标记大小取决于所使用的方法。 plot 以点为单位指定标记大小，通常是标记的“直径”或宽度。 scatter 将标记大小指定为与标记的视觉区域大致成正比。有一系列标记样式可作为字符串代码使用（请参阅 markers），或者用户可以定义自己的 MarkerStyle（请参阅 标记参考）

fig, ax = plt.subplots(figsize=(5, 2.7))
ax.plot(data1, 'o', label='data1')
ax.plot(data2, 'd', label='data2')
ax.plot(data3, 'v', label='data3')
ax.plot(data4, 's', label='data4')
ax.legend()

标注图

坐标轴标签和文本

set_xlabel、set_ylabel 和 set_title 用于在指定位置添加文本（有关更多讨论，请参阅 Matplotlib 中的文本）。还可以使用 text 将文本直接添加到图中

mu, sigma = 115, 15
x = mu + sigma * np.random.randn(10000)
fig, ax = plt.subplots(figsize=(5, 2.7), layout='constrained')
# the histogram of the data
n, bins, patches = ax.hist(x, 50, density=True, facecolor='C0', alpha=0.75)

ax.set_xlabel('Length [cm]')
ax.set_ylabel('Probability')
ax.set_title('Aardvark lengths\n (not really)')
ax.text(75, .025, r'$\mu=115,\ \sigma=15$')
ax.axis([55, 175, 0, 0.03])
ax.grid(True)

所有 text 函数都返回一个 matplotlib.text.Text 实例。与上面的线条一样，您可以通过将关键字参数传递到文本函数中来定制属性

t = ax.set_xlabel('my data', fontsize=14, color='red')

这些属性在 文本属性和布局 中有更详细的介绍。

在文本中使用数学表达式

Matplotlib 在任何文本表达式中都接受 TeX 方程表达式。例如，要在标题中编写表达式 \(\sigma_i=15\)，您可以在美元符号包围的 TeX 表达式中编写

ax.set_title(r'$\sigma_i=15$')

其中标题字符串前面的 r 表示该字符串是一个原始字符串，而不是将反斜杠视为 python 转义符。Matplotlib 有一个内置的 TeX 表达式解析器和布局引擎，并附带自己的数学字体 - 有关详细信息，请参阅 编写数学表达式。您还可以直接使用 LaTeX 来格式化文本，并将输出直接合并到显示图形或保存的 PostScript 中 - 请参阅 使用 LaTeX 进行文本渲染。

注释

我们还可以注释绘图上的点，通常是通过连接指向xy的箭头到xytext处的文本

fig, ax = plt.subplots(figsize=(5, 2.7))

t = np.arange(0.0, 5.0, 0.01)
s = np.cos(2 * np.pi * t)
line, = ax.plot(t, s, lw=2)

ax.annotate('local max', xy=(2, 1), xytext=(3, 1.5),
            arrowprops=dict(facecolor='black', shrink=0.05))

ax.set_ylim(-2, 2)

在这个基本示例中，xy 和xytext 都在数据坐标中。可以选择各种其他坐标系 - 有关详细信息，请参阅 基本注释 和 高级注释。更多示例还可以在 注释绘图 中找到。

图例

我们经常希望使用 Axes.legend 识别线条或标记

fig, ax = plt.subplots(figsize=(5, 2.7))
ax.plot(np.arange(len(data1)), data1, label='data1')
ax.plot(np.arange(len(data2)), data2, label='data2')
ax.plot(np.arange(len(data3)), data3, 'd', label='data3')
ax.legend()

Matplotlib 中的图例在布局、位置和它们可以表示的艺术家方面非常灵活。它们在 图例指南 中进行了详细讨论。

轴刻度和刻度线

每个 Axes 有两个（或三个）Axis 对象，分别表示 x 轴和 y 轴。这些对象控制轴的刻度、刻度定位器和刻度格式化器。可以附加其他 Axes 以显示更多 Axis 对象。

刻度

除了线性刻度外，Matplotlib 还提供非线性刻度，例如对数刻度。由于对数刻度使用得如此频繁，因此还有直接的方法，例如 loglog、semilogx 和 semilogy。有许多刻度（请参见 刻度 以获取其他示例）。在此，我们手动设置刻度

fig, axs = plt.subplots(1, 2, figsize=(5, 2.7), layout='constrained')
xdata = np.arange(len(data1))  # make an ordinal for this
data = 10**data1
axs[0].plot(xdata, data)

axs[1].set_yscale('log')
axs[1].plot(xdata, data)

刻度设置从数据值到沿轴间距的映射。这在两个方向上都会发生，并组合成变换，这是 Matplotlib 从数据坐标映射到 Axes、Figure 或屏幕坐标的方式。请参见 变换教程。

刻度定位器和格式化器

每个 Axis 都具有一个刻度定位器和格式化器，用于选择在 Axis 对象的哪个位置放置刻度线。一个简单的界面是 set_xticks

fig, axs = plt.subplots(2, 1, layout='constrained')
axs[0].plot(xdata, data1)
axs[0].set_title('Automatic ticks')

axs[1].plot(xdata, data1)
axs[1].set_xticks(np.arange(0, 100, 30), ['zero', '30', 'sixty', '90'])
axs[1].set_yticks([-1.5, 0, 1.5])  # note that we don't need to specify labels
axs[1].set_title('Manual ticks')

不同的刻度可以使用不同的定位器和格式化器；例如，上面的对数刻度使用 LogLocator 和 LogFormatter。请参阅 刻度定位器 和 刻度格式化器 以了解其他格式化器和定位器，以及编写您自己的格式化器和定位器的信息。

绘制日期和字符串

Matplotlib 可以处理绘制日期数组和字符串数组，以及浮点数。这些数组会根据需要获得特殊的定位器和格式化器。对于日期

from matplotlib.dates import ConciseDateFormatter

fig, ax = plt.subplots(figsize=(5, 2.7), layout='constrained')
dates = np.arange(np.datetime64('2021-11-15'), np.datetime64('2021-12-25'),
                  np.timedelta64(1, 'h'))
data = np.cumsum(np.random.randn(len(dates)))
ax.plot(dates, data)
ax.xaxis.set_major_formatter(ConciseDateFormatter(ax.xaxis.get_major_locator()))

有关更多信息，请参阅日期示例（例如，日期刻度标签)

对于字符串，我们可以进行分类绘图（请参阅：绘制分类变量）。

fig, ax = plt.subplots(figsize=(5, 2.7), layout='constrained')
categories = ['turnips', 'rutabaga', 'cucumber', 'pumpkins']

ax.bar(categories, np.random.rand(len(categories)))

关于分类绘图的一个注意事项是，某些文本文件解析方法会返回字符串列表，即使这些字符串全部表示数字或日期。如果您传递 1000 个字符串，Matplotlib 会认为您表示 1000 个类别，并将 1000 个刻度添加到您的绘图中！

其他轴对象

在一个图表中绘制不同大小的数据可能需要一个额外的 y 轴。可以通过使用 twinx 来创建这样的轴，以添加一个具有不可见 x 轴和位于右侧的 y 轴的新轴（对于 twiny 类似）。请参阅 具有不同刻度的绘图 以了解另一个示例。

类似地，您可以添加 secondary_xaxis 或 secondary_yaxis，其具有与主轴不同的刻度，以用不同的刻度或单位表示数据。请参阅 辅助轴 以了解其他示例。

fig, (ax1, ax3) = plt.subplots(1, 2, figsize=(7, 2.7), layout='constrained')
l1, = ax1.plot(t, s)
ax2 = ax1.twinx()
l2, = ax2.plot(t, range(len(t)), 'C1')
ax2.legend([l1, l2], ['Sine (left)', 'Straight (right)'])

ax3.plot(t, s)
ax3.set_xlabel('Angle [rad]')
ax4 = ax3.secondary_xaxis('top', functions=(np.rad2deg, np.deg2rad))
ax4.set_xlabel('Angle [°]')

颜色映射数据

我们通常希望在绘图中使用颜色映射中的颜色表示第三个维度。Matplotlib 有许多可以做到这一点的绘图类型

from matplotlib.colors import LogNorm

X, Y = np.meshgrid(np.linspace(-3, 3, 128), np.linspace(-3, 3, 128))
Z = (1 - X/2 + X**5 + Y**3) * np.exp(-X**2 - Y**2)

fig, axs = plt.subplots(2, 2, layout='constrained')
pc = axs[0, 0].pcolormesh(X, Y, Z, vmin=-1, vmax=1, cmap='RdBu_r')
fig.colorbar(pc, ax=axs[0, 0])
axs[0, 0].set_title('pcolormesh()')

co = axs[0, 1].contourf(X, Y, Z, levels=np.linspace(-1.25, 1.25, 11))
fig.colorbar(co, ax=axs[0, 1])
axs[0, 1].set_title('contourf()')

pc = axs[1, 0].imshow(Z**2 * 100, cmap='plasma', norm=LogNorm(vmin=0.01, vmax=100))
fig.colorbar(pc, ax=axs[1, 0], extend='both')
axs[1, 0].set_title('imshow() with LogNorm()')

pc = axs[1, 1].scatter(data1, data2, c=data3, cmap='RdBu_r')
fig.colorbar(pc, ax=axs[1, 1], extend='both')
axs[1, 1].set_title('scatter()')

颜色映射

这些都是派生自 ScalarMappable 对象的艺术家示例。它们都可以将 vmin 和 vmax 之间的线性映射设置到 cmap 指定的色彩映射中。Matplotlib 有许多色彩映射可供选择 (在 Matplotlib 中选择色彩映射)，您可以制作自己的色彩映射 (在 Matplotlib 中创建色彩映射) 或作为 第三方包 下载。

归一化

有时我们希望将数据非线性映射到色彩映射，如上面的 LogNorm 示例。我们通过向 ScalarMappable 提供 norm 参数而不是 vmin 和 vmax 来实现这一点。更多归一化显示在 色彩映射归一化 中。

颜色条

添加 colorbar 提供了一个键，用于将颜色与基础数据关联起来。颜色条是图形级别的艺术家，并附加到 ScalarMappable（它们从中获取有关规范和色彩映射的信息），并且通常从父坐标轴中窃取空间。颜色条的放置可能很复杂：有关详细信息，请参见 放置颜色条。您还可以使用 extend 关键字更改颜色条的外观，以在末端添加箭头，并使用 shrink 和 aspect 控制大小。最后，颜色条将具有适用于规范的默认定位器和格式化程序。这些可以像其他坐标轴对象一样更改。

使用多个图形和坐标轴

您可以通过多次调用 fig = plt.figure() 或 fig2, ax = plt.subplots() 来打开多个图形和多个坐标轴。通过保留对象引用，您可以将艺术家添加到任一图形中。

可以通过多种方式添加多个轴，但最基本的是上面使用的 plt.subplots()。可以使用 subplot_mosaic 实现更复杂的布局，其中轴对象跨列或行。

fig, axd = plt.subplot_mosaic([['upleft', 'right'],
                               ['lowleft', 'right']], layout='constrained')
axd['upleft'].set_title('upleft')
axd['lowleft'].set_title('lowleft')
axd['right'].set_title('right')

Matplotlib 具有用于排列轴的非常精密的工具：请参见 在图形中排列多个轴 和 复杂且语义化的图形组合（subplot_mosaic）。

更多阅读

有关更多绘图类型，请参见 绘图类型 和 API 参考，尤其是 轴 API。