快速入门指南

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

import matplotlib as mpl
import matplotlib.pyplot as plt
import numpy as np

一个简单的例子

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

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()，具体取决于您的后端。有关图形和后端的更多详细信息，请参阅
创建、查看和保存 Matplotlib 图形。

图的一部分

以下是 Matplotlib 图的组件。

../../_images/anatomy.png

Figure

整个图。Figure 跟踪所有 child Axes、一组“特殊”艺术家（标题、人物图例、颜色条等），甚至嵌套子图。

创建新图形的最简单方法是使用 pyplot：

与图形一起创建轴通常很方便，但您也可以稍后手动添加轴。请注意，许多
Matplotlib 后端支持在图形窗口上缩放和平移。

有关图的更多信息，请参阅创建、查看和保存 Matplotlib 图。

Axes

Axes 是附加到 Figure 的 Artist，它包含一个用于绘制数据的区域，通常包括两个（或三个在 3D 情况下）提供
刻度和刻度标签的Axis对象（注意Axes和Axis之间的区别）轴中数据的比例。每个Axes还有一个标题（通过 设置set_title()）、一个 x 标签（通过 设置
set_xlabel()）和一个 y 标签（通过 设置
set_ylabel()）。

该类Axes及其成员函数是使用 OOP 接口的主要入口点，并且在其上定义了大部分绘图方法（例如，如上ax.plot()所示，使用该plot方法）

Axis

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

Artist

基本上，图形上可见的所有内容都是艺术家（甚至
Figure、Axes和Axis对象）。这包括
Text对象、Line2D对象、collections对象、Patch
对象等。当 Figure 被渲染时，所有的 Artists 都被绘制到画布上。大多数艺术家都与轴相关；这样的 Artist 不能被多个 Axes 共享，也不能从一个 Axes 移动到另一个 Axes。

绘图函数的输入类型

绘制函数 expectnumpy.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、 a
numpy.recarray或 a pandas.DataFrame。Matplotlib 允许您提供关键字参数并生成传递与x和ydata变量对应的字符串的图。

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

简单的情节

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

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

笔记

您可能会找到使用该接口的旧示例pylab，通过. 强烈反对这种方法。from pylab import *

制作辅助函数

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

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

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有一个

造型师

大多数绘图方法都有艺术家的样式选项，可以在调用绘图方法时访问，也可以从艺术家的“setter”访问。在下图中，我们手动设置了Artists 创建的颜色、线宽和线型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 有一组非常灵活的颜色，大多数艺术家都可以接受；有关规格列表，请参阅颜色教程。有些艺术家会采用多种颜色。即对于scatter绘图，标记的边缘可以与内部颜色不同：

快速开始

线宽、线型和标记大小

线宽通常以印刷点数表示（1 磅 = 1/72 英寸），适用于具有描边线的美工人员。同样，描边线可以有线型。请参阅线型示例。

标记大小取决于所使用的方法。plot以磅为单位指定标记大小，通常是标记的“直径”或宽度。scatter将 markersize 指定为与​​标记的可视区域大致成比例。有一组标记样式可用作字符串代码（参见 参考资料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
实例。正如上面的行一样，您可以通过将关键字参数传递给文本函数来自定义属性：

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

在文本中使用数学表达式

Matplotlib 接受任何文本表达式中的 TeX 方程表达式。例如写表达式在标题中，你可以写一个用美元符号包围的 TeX 表达式：

标题字符串前面r表示该字符串是
原始字符串，而不是将反斜杠视为 python 转义。Matplotlib 有一个内置的 TeX 表达式解析器和布局引擎，并提供自己的数学字体——有关详细信息，请参阅
编写数学表达式。您还可以直接使用 LaTeX 来格式化您的文本，并将输出直接合并到您的显示图形或保存的后记中——请参阅使用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 都有两个（或三个）Axis对象代表 x 轴和 y 轴。这些控制轴的比例、刻度定位器和刻度格式化程序。可以附加附加轴以显示更多轴对象。

鳞片

除了线性标度之外，Matplotlib 还提供非线性标度，例如对数标度。由于对数尺度的使用如此之多，因此还有直接方法loglog，如semilogx、 和
semilogy。有许多比例尺（有关其他示例，请参阅
比例尺）。这里我们手动设置比例：

快速开始

比例设置从数据值到轴间距的映射。这发生在两个方向上，并组合成一个transform，这是 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 可以处理绘制日期数组和字符串数组，以及浮点数。这些会根据需要获得特殊的定位器和格式化程序。对于日期：

快速开始

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

对于字符串，我们得到分类绘图（请参阅：
绘制分类变量）。

快速开始

关于分类绘图的一个警告是，某些解析文本文件的方法会返回一个字符串列表，即使这些字符串都代表数字或日期。如果您传递 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 有许多绘图类型可以执行此操作：

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=mpl.colors.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()')

pcolormesh()、contourf()、imshow() 和 LogNorm()、scatter()

颜色图

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

规范化

有时我们需要数据到颜色图的非线性映射，如上例所示LogNorm。我们通过为 ScalarMappable 提供norm参数而不是vmin和vmax来做到这一点。更多规范化显示在Colormap Normalization中。

彩条

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

使用多个图形和轴

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

可以通过多种方式添加多个轴，但最基本的方法
plt.subplots()如上所示。可以实现更复杂的布局，使用 Axes 对象跨越列或行，使用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)。