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 不会使其保持活动状态。

参数:

异常处理程序可调用，可选

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

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

信号列表，可选

如果不是 None，signals 是一个此注册表处理的信号列表：尝试对不在列表中的信号进行 process 或 connect 会抛出 ValueError。默认值 None 不限制处理的信号。

blocked(*, signal=None)

阻止回调信号被处理。

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

参数:

信号str, 可选

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

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

clean()

[已弃用] 从字典中清除无效的弱引用。

注释

自 3.8 版本弃用: 使用 none，你不再需要清理石斑鱼。

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)

joined(a, b)

class matplotlib.cbook.Stack(default=None)

基类：object

[已弃用] 带有可移动光标的元素堆栈。

模拟网页浏览器中的首页/后退/前进功能。

注释

自 3.8 版本弃用.

back()

将位置后移并返回当前元素。

bubble(o)

将所有 o 的引用提升到栈顶，并返回它。

引发:

ValueError

如果 o 不在栈中。

clear()

清空栈。

empty()

返回堆栈是否为空。

forward()

向前移动位置并返回当前元素。

home()

将第一个元素推到栈顶。

返回第一个元素。

push(o)

在当前位置将 o 推入栈中。丢弃所有后续元素。

o 被返回。

remove(o)

从栈中移除 o。

引发:

ValueError

如果 o 不在栈中。

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

返回用于使用 bxp 绘制一系列箱线图的统计字典列表。

参数:

X类数组

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

whisfloat 或 (float, float)，默认值：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)（覆盖整个数据范围）。

在须之外的数据被认为是异常值，并以单独的点的形式绘制。

引导程序int, 可选

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

标签list of str, 可选

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

autorangebool, 可选 (False)

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

返回:

列表字典

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

键	值 描述
标签	箱线图的刻度标签
平均	算术平均值
med	第50百分位数
q1	第一四分位数（第25百分位数）
q3	第三四分位数（第75百分位数）
iqr	四分位距
cilo	中位数附近的下凹
cihi	中位数周围的较高水平
whislo	下须的末端
whishi	上须的末端
传单	异常值

注释

非自举法的置信区间使用基于高斯的大样本近似：

\[\mathrm{中位数} \pm 1.57 \times \frac{\mathrm{四分位距}}{\sqrt{N}}\]

一般方法来自：McGill, R., Tukey, J.W., 和 Larsen, W.A. (1978) “箱线图的变体”，《美国统计学家》，32:12-16。

matplotlib.cbook.contiguous_regions(mask)

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

matplotlib.cbook.delete_masked_points(*args)

查找一组参数中的所有掩码和/或非有限点，并返回仅包含未掩码点的参数。

参数可以是以下五种类别中的任何一种：

1. 一维掩码数组

2. 一维 ndarrays

3. 多维的 ndarrays

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

5. 其他任何内容

第一个参数必须属于前四个类别之一；任何长度与第一个参数不同的参数（因此属于第五类）将保持不变。

掩码是从类别1、2和4中所有正确长度的参数中获得的；如果一个点在掩码数组中被掩码，或者它是nan或inf，那么它就是坏的。如果`numpy.isfinite`没有产生一个布尔数组，则不会尝试从类别2、3和4中提取掩码。

所有未被原样传递的输入参数在移除与任何参数中掩码对应的点或行后，将作为 ndarrays 返回。

这个函数的简化版本最初是为 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/ 和食谱 1.12

matplotlib.cbook.get_sample_data(fname, asfileobj=True, *, np_load=<deprecated parameter>)

返回一个示例数据文件。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)

帮助函数用于规范化关键字参数输入。

参数:

kw字典或无

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

别名映射字典或 Artist 子类或 Artist 实例，可选

从最低到最高优先级的规范名称到别名列表的映射。

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

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

引发:

类型错误

为了匹配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)

在给定的 objects 中打印循环引用循环。

通常将 gc.garbage 传递进去以找到阻止某些对象被垃圾回收的循环引用是很有用的。

参数:

对象

一个用于查找循环的对象列表。

输出流

输出流。

显示进度布尔

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

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)

将 dictview 对象转换为列表。其他输入保持不变。

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

基类：list

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

这是用于一个艺术家同质列表的，这样它们就不会产生冗长、无意义的输出。

而不是

[<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, ...)

步骤整数

返回:

数组

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

matplotlib.cbook.strip_math(s)

从 mathtext 中移除 latex 格式。

仅处理完全为数学表达式和完全非数学表达式的字符串。

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

将路径转换为打开的文件句柄，或传递类似文件的对象。

考虑使用 open_file_cm ，因为它可以更容易地正确关闭新创建的文件对象。

参数:

fnamestr 或 path-like 或 file-like

如果 str 或 os.PathLike，文件将使用 flag 和 encoding 指定的标志打开。如果是一个类文件对象，则直接传递。

标志str, 默认值: 'r'

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

return_openedbool, 默认值: False

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

编码str 或 None, 默认: None

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

返回:

fh类文件

已打开布尔

opened 仅在 return_opened 为 True 时返回。

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

返回一个数据字典列表，这些数据可用于绘制一系列小提琴图。

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

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

参数:

X类数组

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

方法可调用

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

点int, 默认值: 100

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

分位数类似数组，默认值：None

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

返回:

列表字典

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

• coords: 一个包含标量的列表，其中包含在此特定核密度估计中评估的坐标。

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

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

• 中位数: 该列数据的中位数值。

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

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

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