matplotlib.cbook

一组实用函数和类。最初，其中许多（但并非全部）来源于 Python Cookbook——因此得名 cbook。

class matplotlib.cbook.CallbackRegistry(exception_handler=<function _exception_printer>, *, signals=None)

基类: object

处理一套信号和回调的注册、处理、阻止和断开连接。

>>> def oneat(x):
...     print('eat', x)
>>> def ondrink(x):
...     print('drink', x)

>>> from matplotlib.cbook import CallbackRegistry
>>> callbacks = CallbackRegistry()

>>> id_eat = callbacks.connect('eat', oneat)
>>> id_drink = callbacks.connect('drink', ondrink)

>>> callbacks.process('drink', 123)
drink 123
>>> callbacks.process('eat', 456)
eat 456
>>> callbacks.process('be merry', 456)   # nothing will be called

>>> callbacks.disconnect(id_eat)
>>> callbacks.process('eat', 456)        # nothing will be called

>>> with callbacks.blocked(signal='drink'):
...     callbacks.process('drink', 123)  # nothing will be called
>>> callbacks.process('drink', 123)
drink 123

实际上，当不再需要时，应始终断开所有回调，以避免悬空引用（从而导致内存泄漏）。然而，Matplotlib 中的实际代码很少这样做，并且由于其设计，这种代码很难放置。为了解决这个问题，并防止这类内存泄漏，我们只存储对绑定方法的弱引用，这样当目标对象需要销毁时，CallbackRegistry 就不会使其保持活跃。

参数:

exception_handler可调用对象, 可选

如果不是 None，exception_handler 必须是一个函数，它接受一个 Exception 作为唯一参数。它会在 CallbackRegistry.process 期间被回调引发的任何 Exception 调用，并且可以重新抛出异常或以其他方式处理它。

如果交互式事件循环正在运行，默认处理程序会打印异常（使用 traceback.print_exc）；如果没有交互式事件循环运行，它会重新抛出异常。

signals列表, 可选

如果不是 None，signals 是此注册表处理的信号列表：尝试 处理 或 连接 到不在列表中的信号会抛出 ValueError。默认值 None 不限制处理的信号。

blocked(*, signal=None)

阻止回调信号被处理。

一个上下文管理器，用于临时阻止/禁用回调信号被注册的监听器处理。

参数:

signal字符串, 可选

要阻止的回调信号。默认是阻止所有信号。

connect(signal, func)

注册 func，以便在信号 signal 生成时被调用。

disconnect(cid)

断开与回调 ID cid 注册的回调。

如果此类回调不存在，不会引发错误。

process(s, *args, **kwargs)

处理信号 s。

所有注册用于接收 s 上的回调的函数都将使用 *args 和 **kwargs 进行调用。

class matplotlib.cbook.Grouper(init=())

基类: object

一个不相交集数据结构。

可以使用 join() 连接对象，使用 joined() 测试连通性，并且可以通过将对象用作迭代器来检索所有不相交集。

被连接的对象必须是可哈希的和可弱引用的。

示例

>>> from matplotlib.cbook import Grouper
>>> class Foo:
...     def __init__(self, s):
...         self.s = s
...     def __repr__(self):
...         return self.s
...
>>> a, b, c, d, e, f = [Foo(x) for x in 'abcdef']
>>> grp = Grouper()
>>> grp.join(a, b)
>>> grp.join(b, c)
>>> grp.join(d, e)
>>> list(grp)
[[a, b, c], [d, e]]
>>> grp.joined(a, b)
True
>>> grp.joined(a, c)
True
>>> grp.joined(a, d)
False

get_siblings(a)

返回所有与 a 连接的项，包括它自己。

join(a, *args)

将给定参数加入同一集合。接受一个或多个参数。

joined(a, b)

返回 a 和 b 是否属于同一集合。

remove(a)

从分组器中移除 a，如果不存在则不执行任何操作。

class matplotlib.cbook.GrouperView(grouper)

基类: object

Grouper 的不可变视图。

get_siblings(a)

返回所有与 a 连接的项，包括它自己。

joined(a, b)

返回 a 和 b 是否属于同一集合。

matplotlib.cbook.boxplot_stats(X, whis=1.5, bootstrap=None, labels=None, autorange=False)

返回一个字典列表，其中包含用于使用 bxp 绘制一系列箱线图的统计数据。

参数:

X类数组

将用于箱线图表示的数据。应具有 2 个或更少的维度。

whis浮点数或 (浮点数, 浮点数), 默认值: 1.5

触须的位置。

如果是一个浮点数，下触须位于 Q1 - whis*(Q3-Q1) 以上的最低数据点，上触须位于 Q3 + whis*(Q3-Q1) 以下的最高数据点，其中 Q1 和 Q3 分别是第一和第三四分位数。 whis = 1.5 的默认值对应于 Tukey 对箱线图的原始定义。

如果是一对浮点数，它们表示绘制触须的百分位数（例如，(5, 95)）。特别是，将其设置为 (0, 100) 会使触须覆盖数据的整个范围。

在 Q1 == Q3 的极端情况下，如果 autorange 为 True，则 whis 自动设置为 (0, 100)（覆盖数据的整个范围）。

超出触须的数据被视为异常值并作为单独的点绘制。

bootstrap整型, 可选

围绕中位数应进行自举（百分位数法）的置信区间的次数。

labels字符串列表, 可选

每个数据集的标签。长度必须与 X 的维度兼容。

autorange布尔型, 可选 (False)

当 True 且数据分布使得第 25 和 75 百分位数相等时，whis 设置为 (0, 100)，使触须末端位于数据的最小值和最大值。

返回:

字典列表

一个字典列表，包含每列数据的结果。每个字典的键如下：

键	值描述
label	箱线图的刻度标签
mean	算术平均值
med	第 50 百分位数
q1	第一四分位数（第 25 百分位数）
q3	第三四分位数（第 75 百分位数）
iqr	四分位距
cilo	中位数周围的下刻槽
cihi	中位数周围的上刻槽
whislo	下触须的末端
whishi	上触须的末端
fliers	异常值

备注

计算置信区间的非自举方法使用基于高斯分布的渐近近似

\[\mathrm{med} \pm 1.57 \times \frac{\mathrm{iqr}}{\sqrt{N}}\]

通用方法来自：McGill, R., Tukey, J.W., and Larsen, W.A. (1978) "Variations of Boxplots", The American Statistician, 32:12-16。

matplotlib.cbook.contiguous_regions(mask)

返回一个 (ind0, ind1) 列表，使得 mask[ind0:ind1].all() 为 True 并且我们覆盖所有此类区域。

matplotlib.cbook.delete_masked_points(*args)

找到一组参数中所有被遮罩和/或非有限的点，并返回仅保留未被遮罩点的参数。

参数可分为以下 5 类：

1. 一维遮罩数组

2. 一维 ndarray

3. 多维 ndarray

4. 其他非字符串可迭代对象

5. 其他任何类型

第一个参数必须属于前四类之一；任何长度与第一个参数不同的参数（因此是第五类中的任何内容）将原样传递。

遮罩从类别 1、2 和 4 中所有长度正确的参数中获取；如果一个点在遮罩数组中被遮罩，或者它是 nan 或 inf，则该点是无效的。如果 numpy.isfinite 不生成布尔数组，则不尝试从类别 2、3 和 4 中提取遮罩。

所有未原样传递的输入参数在移除对应于任何参数中遮罩的点或行后，作为 ndarray 返回。

此函数的一个大大简化的版本最初是作为 Axes.scatter() 的辅助函数编写的。

matplotlib.cbook.file_requires_unicode(x)

返回给定的可写类文件对象是否需要写入 Unicode。

matplotlib.cbook.flatten(seq, scalarp=<function is_scalar_or_string>)

返回一个用于扁平化嵌套容器的生成器。

例如：

>>> from matplotlib.cbook import flatten
>>> l = (('John', ['Hunter']), (1, 23), [[([42, (5, 23)], )]])
>>> print(list(flatten(l)))
['John', 'Hunter', 1, 23, 42, 5, 23]

作者：Holger Krekel 和 Luther Blissett 的合成作品 来源：https://code.activestate.com/recipes/121294-simple-generator-for-flattening-nested-containers/ 以及 Cookbook 中的 Recipe 1.12

matplotlib.cbook.get_sample_data(fname, asfileobj=True)

返回一个示例数据文件。fname 是相对于 mpl-data/sample_data 目录的路径。如果 asfileobj 为 True，则返回一个文件对象，否则只返回文件路径。

示例数据文件存储在 Matplotlib 包内的 'mpl-data/sample_data' 目录中。

如果文件名以 .gz 结尾，则文件会自动解压。如果文件名以 .npy 或 .npz 结尾，并且 asfileobj 为 True，则文件将使用 numpy.load 加载。

matplotlib.cbook.index_of(y)

一个辅助函数，用于为给定的 y 创建合理的 x 值。

当 x 值未明确给出时，它用于绘制 (x, y)。

首先尝试 y.index（假设 y 是一个 pandas.Series），如果失败，则使用 range(len(y))。

将来会扩展此功能，以处理更多类型的带标签数据。

参数:

y浮点数或类数组

返回:

x, yndarray

要绘制的 x 和 y 值。

matplotlib.cbook.is_math_text(s)

返回字符串 s 是否包含数学表达式。

这是通过检查 s 是否包含偶数个未转义的美元符号来完成的。

matplotlib.cbook.is_scalar_or_string(val)

返回给定对象是否是标量或字符串类型。

matplotlib.cbook.is_writable_file_like(obj)

返回 obj 是否像具有 write 方法的文件对象。

matplotlib.cbook.ls_mapper = {'-': 'solid', '--': 'dashed', '-.': 'dashdot', ':': 'dotted'}

将线条样式的短代码映射到后端使用的完整名称。

matplotlib.cbook.ls_mapper_r = {'dashdot': '-.', 'dashed': '--', 'dotted': ':', 'solid': '-'}

将后端使用的线条样式的完整名称映射到它们的短代码。

matplotlib.cbook.normalize_kwargs(kw, alias_mapping=None)

用于规范化 kwarg 输入的辅助函数。

参数:

kw字典或 None

一个关键字参数字典。明确支持 None 并将其视为空字典，以支持带有可选参数 props=None 形式的函数。

alias_mapping字典或 Artist 子类或 Artist 实例, 可选

规范名称到别名列表的映射，按优先级从低到高排序。

如果规范值不在列表中，则假定它具有最高优先级。

如果传递了 Artist 子类或实例，则使用其属性别名映射。

引发:

TypeError

与 Python 在将无效参数/关键字参数传递给可调用对象时引发的错误相匹配。

matplotlib.cbook.open_file_cm(path_or_file, mode='r', encoding=None)

传递文件对象并以上下文管理路径对象。

matplotlib.cbook.print_cycles(objects, outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, show_progress=False)

打印给定对象中的循环引用。

通常将 gc.garbage 传入很有用，以查找阻止某些对象被垃圾回收的循环。

参数:

对象

要查找循环的对象列表。

输出流

输出的流。

show_progress布尔型

如果为 True，则在找到对象时打印已到达的对象数量。

matplotlib.cbook.pts_to_midstep(x, *args)

将连续线转换为中间步长。

给定 N 个点，将其转换为 2N 个点，这些点在线性连接时会形成一个阶梯函数，该函数在区间的中间改变值。

参数:

x数组

阶梯的 x 位置。可能为空。

y1, ..., yp数组

要转换为阶梯的 y 数组；所有数组的长度必须与 x 相同。

返回:

数组

X 和 Y 值转换为阶梯点，与输入顺序相同；可解包为 x_out, y1_out, ..., yp_out。如果输入长度为 N，则这些数组的每个长度都将是 2N。

示例

>>> x_s, y1_s, y2_s = pts_to_midstep(x, y1, y2)

matplotlib.cbook.pts_to_poststep(x, *args)

将连续线转换为后阶梯点。

给定一组 N 个点，将其转换为 2N + 1 个点，这些点在线性连接时会形成一个在区间末尾改变值的阶梯函数。

参数:

x数组

阶梯的 x 位置。可能为空。

y1, ..., yp数组

要转换为阶梯的 y 数组；所有数组的长度必须与 x 相同。

返回:

数组

X 和 Y 值转换为阶梯点，与输入顺序相同；可解包为 x_out, y1_out, ..., yp_out。如果输入长度为 N，则这些数组的每个长度都将是 2N + 1。对于 N=0，长度将为 0。

示例

>>> x_s, y1_s, y2_s = pts_to_poststep(x, y1, y2)

matplotlib.cbook.pts_to_prestep(x, *args)

将连续线转换为前阶梯点。

给定一组 N 个点，将其转换为 2N - 1 个点，这些点在线性连接时会形成一个在区间开头改变值的阶梯函数。

参数:

x数组

阶梯的 x 位置。可能为空。

y1, ..., yp数组

要转换为阶梯的 y 数组；所有数组的长度必须与 x 相同。

返回:

数组

X 和 Y 值转换为阶梯点，与输入顺序相同；可解包为 x_out, y1_out, ..., yp_out。如果输入长度为 N，则这些数组的每个长度都将是 2N + 1。对于 N=0，长度将为 0。

示例

>>> x_s, y1_s, y2_s = pts_to_prestep(x, y1, y2)

matplotlib.cbook.safe_first_element(obj)

返回 obj 中的第一个元素。

这是一种与类型无关的获取第一个元素的方式，支持索引访问和迭代器协议。

matplotlib.cbook.safe_masked_invalid(x, copy=False)

matplotlib.cbook.sanitize_sequence(data)

将字典视图对象转换为列表。其他输入保持不变返回。

class matplotlib.cbook.silent_list(type, seq=None)

基类: list

一个具有简短 repr() 的列表。

这旨在用于同构的 artist 列表，以避免产生冗长、无意义的输出。

而不是

[<matplotlib.lines.Line2D object at 0x7f5749fed3c8>,
 <matplotlib.lines.Line2D object at 0x7f5749fed4e0>,
 <matplotlib.lines.Line2D object at 0x7f5758016550>]

你会得到

<a list of 3 Line2D objects>

如果 self.type 为 None，则类型名称从列表中的第一个元素（如果有的话）获取。

matplotlib.cbook.simple_linear_interpolation(a, steps)

对数组进行重采样，在原始点对之间插入 steps - 1 个点。

沿着 a 的每一列，在每个原始值之间插入 (steps - 1) 个点；这些值进行线性插值。

参数:

a数组, 形状 (n, ...)

steps整型

返回:

数组

形状 ((n - 1) * steps + 1, ...)

matplotlib.cbook.strip_math(s)

从数学文本中移除 LaTeX 格式。

只处理完全是数学公式和完全是非数学公式的字符串。

matplotlib.cbook.to_filehandle(fname, flag='r', return_opened=False, encoding=None)

将路径转换为已打开的文件句柄或透传文件类对象。

建议使用 open_file_cm 代替，因为它允许更容易地正确关闭新创建的文件对象。

参数:

fname字符串或路径类或文件类

如果为 str 或 os.PathLike，则使用 flag 和 encoding 指定的标志打开文件。如果为文件类对象，则透传。

flag字符串, 默认: 'r'

当 fname 为 str 或 os.PathLike 时，作为 mode 参数传递给 open>；如果 fname 是文件类对象，则忽略。

return_opened布尔值, 默认: False

如果为 True，则同时返回文件对象和一个布尔值，指示这是否是一个新文件（调用者需要关闭）。如果为 False，则只返回新文件。

encoding字符串或 None, 默认: None

当 fname 为 str 或 os.PathLike 时，作为 mode 参数传递给 open>；如果 fname 是文件类对象，则忽略。

返回:

fh文件类

opened布尔值

opened 仅在 return_opened 为 True 时返回。

matplotlib.cbook.violin_stats(X, method, points=100, quantiles=None)

返回一个字典列表，其中包含可用于绘制一系列小提琴图的数据。

请参阅下面的 Returns 部分以查看字典的必需键。

用户可以跳过此函数，并向 violinplot 传递一组用户定义的具有相同键的字典，而不是使用 Matplotlib 进行计算。有关字典中必须存在的键，请参阅下面的 Returns 部分。

参数:

X类数组

用于生成高斯核密度估计的样本数据。必须具有 2 维或更少维。

method可调用对象

用于计算每列数据的核密度估计的方法。当通过 method(v, coords) 调用时，它应返回一个 KDE 值向量，这些值在 coords 中指定的值处进行评估。

points整型, 默认: 100

定义评估每个高斯核密度估计的点数。

quantiles数组类对象, 默认: None

定义（如果不是 None）一个包含每列数据在区间 [0, 1] 中浮点数的列表，它表示将为该列数据渲染的分位数。必须具有 2 维或更少维。一维数组将被视为包含它们的单例列表。

返回:

字典列表

一个字典列表，包含每列数据的结果。字典至少包含以下内容：

• coords: 包含此特定核密度估计被评估的坐标的标量列表。

• vals: 包含在 coords 中给定的每个坐标处核密度估计值的标量列表。

• mean: 此列数据的平均值。

• median: 此列数据的中位值。

• min: 此列数据的最小值。

• max: 此列数据的最大值。

• quantiles: 此列数据的分位数。