Matplotlib 应用程序接口 (API)#

Matplotlib 有两个主要的应用程序接口，或者说使用库的风格：

  • 一个显式的 "坐标轴 (Axes)" 接口，它使用 Figure 或 Axes 对象的方法来创建其他艺术家 (Artists)，并逐步构建可视化效果。 这也被称为“面向对象”接口。

  • 一个隐式的 "pyplot" 接口，它跟踪最后创建的 Figure 和 Axes，并将艺术家添加到它认为用户想要的对象中。

此外，许多下游库（如 pandas 和 xarray）在其数据类上直接提供了一个 plot 方法，以便用户可以调用 data.plot()。

这些接口之间的差异可能有点令人困惑，特别是考虑到网络上的代码片段有时会使用其中一个，或者有时在同一个示例中使用多个接口。 在这里，我们尝试指出“pyplot”和下游接口如何与显式的“Axes”接口相关联，以帮助用户更好地浏览库。

原生 Matplotlib 接口#

显式 "坐标轴 (Axes)" 接口#

“Axes” 接口是 Matplotlib 的实现方式，许多自定义和微调最终都会在此级别完成。

此接口的工作方式是实例化一个 Figure 类（下面的 fig），使用该对象的 subplots 方法（或类似方法）来创建一个或多个 Axes 对象（下面的 ax），然后在 Axes 上调用绘图方法（此示例中的 plot）

import matplotlib.pyplot as plt

fig = plt.figure()
ax = fig.subplots()
ax.plot([1, 2, 3, 4], [0, 0.5, 1, 0.2])

（源代码, 2x.png, png）

我们称此为“显式”接口，因为每个对象都被显式引用，并用于创建下一个对象。保留对对象的引用非常灵活，并且允许我们在创建对象后但在显示它们之前自定义它们。

隐式 "pyplot" 接口#

pyplot 模块隐藏了大部分 Axes 绘图方法，以实现与上述相同的功能，其中 Figure 和 Axes 的创建由用户完成

import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4], [0, 0.5, 1, 0.2])

（源代码, 2x.png, png）

这可能很方便，尤其是在进行交互式工作或编写简单脚本时。 可以使用 gcf 检索对当前 Figure 的引用，并使用 gca 检索对当前 Axes 的引用。 pyplot 模块保留一个 Figure 列表，并且每个 Figure 保留一个 Figure 上 Axes 的列表，供用户使用，以便以下代码

import matplotlib.pyplot as plt

plt.subplot(1, 2, 1)
plt.plot([1, 2, 3], [0, 0.5, 0.2])

plt.subplot(1, 2, 2)
plt.plot([3, 2, 1], [0, 0.5, 0.2])

（源代码, 2x.png, png）

等效于

import matplotlib.pyplot as plt

plt.subplot(1, 2, 1)
ax = plt.gca()
ax.plot([1, 2, 3], [0, 0.5, 0.2])

plt.subplot(1, 2, 2)
ax = plt.gca()
ax.plot([3, 2, 1], [0, 0.5, 0.2])

（源代码, 2x.png, png）

在显式接口中，这将是

import matplotlib.pyplot as plt

fig, axs = plt.subplots(1, 2)
axs[0].plot([1, 2, 3], [0, 0.5, 0.2])
axs[1].plot([3, 2, 1], [0, 0.5, 0.2])

（源代码, 2x.png, png）

在 Axes 接口和 pyplot 接口之间进行转换#

您可能会在现有代码中找到任一接口，不幸的是，有时甚至是混合使用。 本节介绍两种接口中特定操作的模式，以及如何从一种接口转换为另一种接口。

  • 对于两种接口，创建图形是相同的：使用各自的 pyplot 函数 plt.figure()、plt.subplots()、plt.subplot_mosaic()。 对于 Axes 接口，您通常将创建的 Figure（以及可能的 Axes）存储在变量中以供以后使用。 使用 pyplot 接口时，这些值通常不存储。 示例

    • Axes: fig, ax = plt.subplots()

    • pyplot: plt.subplots()

  • “绘图”函数，即添加数据的函数，在 Axes 和 pyplot 中名称相同且参数相同。例如

    • Axes: ax.plot(x, y)

    • pyplot: plt.plot(x, y)

  • 检索属性的函数在 pyplot 中以属性名称命名，在 Axes 中以 get_ 为前缀。例如

    • Axes: label = ax.get_xlabel()

    • pyplot: label = plt.xlabel()

  • 设置属性的函数在 pyplot 中以属性名称命名，在 Axes 中以 set_ 为前缀。例如

    • Axes: ax.set_xlabel("time")

    • pyplot: plt.xlabel("time")

下面再次简要总结示例，并进行并排比较

操作

Axes 接口

pyplot 接口

创建图形

fig, ax = plt.subplots()

plt.subplots()

绘制数据

ax.plot(x, y)

plt.plot(x, y)

获取属性

label = ax.get_xlabel()

label = plt.xlabel()

设置属性

ax.set_xlabel("time")

plt.xlabel("time")

为什么要显式？#

如果您必须回溯并操作未被 plt.gca() 引用的旧 axes，会发生什么？一种简单的方法是使用相同的参数再次调用 subplot。但是，这很快就会变得不优雅。您还可以检查 Figure 对象并获取其 Axes 对象列表，但是，这可能会产生误导（颜色条也是 Axes！）。最好的解决方案可能是保存您创建的每个 Axes 的句柄，但是，如果您这样做，为什么不一开始就创建所有 Axes 对象呢？

第一种方法是再次调用 plt.subplot

import matplotlib.pyplot as plt

plt.subplot(1, 2, 1)
plt.plot([1, 2, 3], [0, 0.5, 0.2])

plt.subplot(1, 2, 2)
plt.plot([3, 2, 1], [0, 0.5, 0.2])

plt.suptitle('Implicit Interface: re-call subplot')

for i in range(1, 3):
    plt.subplot(1, 2, i)
    plt.xlabel('Boo')

(源代码, 2x.png, png)

第二种方法是保存句柄

import matplotlib.pyplot as plt

axs = []
ax = plt.subplot(1, 2, 1)
axs += [ax]
plt.plot([1, 2, 3], [0, 0.5, 0.2])

ax = plt.subplot(1, 2, 2)
axs += [ax]
plt.plot([3, 2, 1], [0, 0.5, 0.2])

plt.suptitle('Implicit Interface: save handles')

for i in range(2):
    plt.sca(axs[i])
    plt.xlabel('Boo')

(源代码, 2x.png, png)

但是，建议的方法是从一开始就明确地进行操作

import matplotlib.pyplot as plt

fig, axs = plt.subplots(1, 2)
axs[0].plot([1, 2, 3], [0, 0.5, 0.2])
axs[1].plot([3, 2, 1], [0, 0.5, 0.2])
fig.suptitle('Explicit Interface')
for i in range(2):
    axs[i].set_xlabel('Boo')

(源代码, 2x.png, png)

第三方库“数据对象”接口#

一些第三方库选择为它们的数据对象实现绘图，例如，data.plot()，在 pandas, xarray 和其他第三方库中可以看到。为了说明，下游库可能会实现一个简单的数据容器，该容器将 x 和 y 数据存储在一起，然后实现一个 plot 方法

import matplotlib.pyplot as plt

# supplied by downstream library:
class DataContainer:

    def __init__(self, x, y):
        """
        Proper docstring here!
        """
        self._x = x
        self._y = y

    def plot(self, ax=None, **kwargs):
        if ax is None:
            ax = plt.gca()
        ax.plot(self._x, self._y, **kwargs)
        ax.set_title('Plotted from DataClass!')
        return ax


# what the user usually calls:
data = DataContainer([0, 1, 2, 3], [0, 0.2, 0.5, 0.3])
data.plot()

(源代码, 2x.png, png)

因此，该库可以向用户隐藏所有细节，并且可以生成适合数据类型的可视化，通常具有良好的标签、颜色映射选择和其他便利功能。

但是，在上面的示例中，我们可能不喜欢库提供的标题。值得庆幸的是，它们通过 plot() 方法将 Axes 返回给我们，并且在理解了显式 Axes 接口后，我们可以调用：ax.set_title('My preferred title') 来自定义标题。

许多库还允许它们的 plot 方法接受可选的 *ax* 参数。这允许我们将可视化放置在我们放置并可能自定义的 Axes 中。

总结#

总的来说，理解显式“Axes”接口非常有用，因为它是最灵活的，并且是其他接口的基础。用户通常可以弄清楚如何切换到显式接口并对底层对象进行操作。虽然显式接口的设置可能有点冗长，但复杂的绘图通常比尝试使用隐式的“pyplot”接口更简单。

注意

人们有时会感到困惑，因为我们为两个接口都导入 pyplot。目前，pyplot 模块实现了“pyplot”接口，但它也提供了顶级 Figure 和 Axes 创建方法，如果正在使用图形用户界面，则最终会启动图形用户界面。因此，无论选择哪个接口，仍然需要 pyplot。

类似地，合作伙伴库提供的声明式接口使用“Axes”接口可访问的对象，并且通常将这些对象作为参数接受或从方法中返回。通常必须使用显式的“Axes”接口来执行对默认可视化的任何自定义，或者将数据解压到 NumPy 数组中并直接传递给 Matplotlib。

附录：“Axes”接口与数据结构#

大多数 Axes 方法允许通过将 *data* 对象传递给方法并将参数指定为字符串来寻址另一个 API

import matplotlib.pyplot as plt

data = {'xdat': [0, 1, 2, 3], 'ydat': [0, 0.2, 0.4, 0.1]}
fig, ax = plt.subplots(figsize=(2, 2))
ax.plot('xdat', 'ydat', data=data)

(源代码, 2x.png, png)

附录：“pylab”接口#

还有一个不太推荐的接口，那就是基本上执行 from matplotlib.pylab import *。这将从 matplotlib.pyplot、numpy、numpy.fft、numpy.linalg 和 numpy.random 以及一些额外的函数导入所有函数到全局命名空间。

这种模式在现代 python 中被认为是不好的做法，因为它会污染全局命名空间。更严重的是，在 pylab 的情况下，这将覆盖一些内置函数（例如，内置的 sum 将被 numpy.sum 替换），这可能导致意外的行为。

本页内容