matplotlib.cbook

实用函数和类的集合。最初，许多（但不是全部）来自于Python食谱——因此得名cBook。

此模块可以从Matplotlib中的任何位置安全导入；它仅在运行时导入Matplotlib。

class matplotlib.cbook.CallbackRegistry(exception_handler=<function _exception_printer>)[源代码]

基类：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

在实践中，当不再需要回调以避免挂起引用（从而导致内存泄漏）时，应该始终断开它们。然而，Matplotlib中的真实代码很少这样做，而且由于其设计，很难放置此类代码。为了解决这个问题并防止此类内存泄漏，我们只存储对绑定方法的弱引用，因此当目标对象需要死亡时，回调注册表不会使其保持活动状态。

参数:
exception_handler可调用，可选

如果提供，必须有签名：

def handler(exc: Exception) -> None:

如果没有，将使用任何 Exception 回调引发的子类 CallbackRegistry.process . 处理程序可以使用异常，也可以重新引发异常。

可调用的必须是可酸洗的。

默认处理程序为：

def h(exc):
    traceback.print_exc()
connect(s, func)[源代码]

寄存器 func 当信号发出时被呼叫 s 是生成的。

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)
>>> sorted(map(tuple, grp))
[(a, b, c), (d, e)]
>>> grp.joined(a, b)
True
>>> grp.joined(a, c)
True
>>> grp.joined(a, d)
False
clean()[源代码]

从字典中清除死的弱引用。

get_siblings(a)[源代码]

返回所有与 a 包括它自己。

join(a, *args)[源代码]

将给定的参数联接到同一集合中。接受一个或多个参数。

joined(a, b)[源代码]

返回是否 a 和 b 是同一组的成员。

remove(a)[源代码]
exception matplotlib.cbook.IgnoredKeywordWarning(*args, **kwargs)[源代码]

基类：UserWarning

[Deprecated] 一个类，用于发出有关Matplotlib将忽略的关键字参数的警告。

笔记

3.3 版后已移除.

class matplotlib.cbook.Stack(default=None)[源代码]

基类：object

具有可移动光标的元素堆栈。

在Web浏览器中模拟主页/后退/前进。

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最初对boxplots的定义。

如果一对浮点数，它们表示绘制胡须的百分位数（例如，（5，95））。尤其是，将此值设置为（0，100）会导致胡须覆盖整个数据范围。”range”是（0，100）的已弃用同义词。

在边缘的情况下，在哪里 Q1 == Q3 ， whis 如果 奥特罗姆 是True。

在触须之外，数据被视为异常值，并绘制为单独的点。

bootstrap可选的

应该引导中位数周围的置信区间的次数（百分比法）。

labels类似数组，可选

每个数据集的标签。长度必须与以下尺寸兼容： X .

autorangebool，可选（假）

什么时候？ True 数据的分布使得25%和75%相等， whis 设置为（0，100），使得晶须末端位于数据的最小值和最大值。
返回:
DICT列表

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

键 价值描述
标签 箱线图的勾号标签
意思是 算术平均值
地中海 第五十百分位数
Q1 第一个四分位数（25%）
Q3 第三个四分位数（75%）
西洛 中间带周围的下凹口
齐希 中间带周围的上凹口
威士忌 下胡须末端
惠施 上胡须末端
传单 离群点

笔记

置信区间的非自举方法使用基于高斯的渐近近似：

\[\ Mathrm Med \pm 1.57\次\frac \mathrm iqr \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() 是真的，我们覆盖了所有这些地区。

matplotlib.cbook.delete_masked_points(*args)[源代码]

在一组参数中查找所有屏蔽点和/或非有限点，并返回只剩下未屏蔽点的参数。

参数可以分为5类：

  1. 一维屏蔽数组
  2. 一维中子线
  3. 具有多个维度的ndarrays
  4. 其他非字符串iterables
  5. 别的

第一个参数必须在前四个类别中的一个类别中；任何长度与第一个参数不同的参数（因此第5类中的任何内容）都将以不变的方式传递。

屏蔽是从类别1、2和4中长度正确的所有参数中获取的；如果屏蔽在屏蔽数组中或是NaN或Inf中，则点是不好的。如果 numpy.isfinite 不生成布尔数组。

在删除任何参数中与遮罩对应的点或行后，未通过更改传递的所有输入参数将以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 Blisset的合成，来自：https://code.activestate.com/recipes/121294/和食谱1.12

matplotlib.cbook.get_realpath_and_stat(path)[源代码]

[Deprecated]

笔记

3.3 版后已移除:

matplotlib.cbook.get_sample_data(fname, asfileobj=True, *, np_load=False)[源代码]

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

示例数据文件存储在Matplotlib包中的“mpl data/Sample_data”目录中。

如果文件名以.gz结尾，则该文件将被隐式解压缩。如果文件名以.npy或.npz结尾， AsSeriObjo 是真的，而且 np_load 如果为True，则文件将加载 numpy.load . np_load 当前默认为False，但在将来的版本中将默认为True。

matplotlib.cbook.index_of(y)[源代码]

一个帮助函数，为给定的 y .

如果没有明确给出x值，则用于绘制（x，y）。

第一次尝试 y.index （假设） y 是一个 pandas.Series )，如果失败，请使用 range(len(y)) .

这将在将来扩展以处理更多类型的标记数据。

参数:
y浮点数或类似数组的
返回:
x, y恩达雷

要绘制的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 看起来像一个文件对象 写 方法。

matplotlib.cbook.local_over_kwdict(local_var, kwargs, *keys)[源代码]

[Deprecated] 强制局部变量的优先级高于来自kwargs dict的潜在冲突参数。将按优先级顺序考虑以下可能的输出值：

local_var > kwargs[keys[0]] > ... > kwargs[keys[-1]]

其中第一个值不是“无”的将被返回。如果全部都不存在，则不会返回任何信息。每把钥匙都将从Kwargs dict中取出。

参数:
local_var任何物体

局部变量（最高优先级）。

kwargs双关语

关键字参数字典；就地修改。

keys结构

要处理的关键字参数的名称，按优先级降序排列。
返回:
任何物体

本地变量或一个Kwarg [key] 用于钥匙插入。
加薪:
IgnoredKeywordWarning

对于从kwargs中移除但未用作输出值的键中的每个键。

笔记

3.3 版后已移除.

class matplotlib.cbook.maxdict(maxsize)[源代码]

基类：dict

最大尺寸的词典。

笔记

这并不是覆盖所有相关的方法来约束大小，只是 __setitem__ ，请谨慎使用。

matplotlib.cbook.normalize_kwargs(kw, alias_mapping=None, required=<deprecated parameter>, forbidden=<deprecated parameter>, allowed=<deprecated parameter>)[源代码]

帮助函数来规范化kwarg输入。

它们的解决顺序是：

  1. 混叠
  2. 必修的
  3. 被禁止的
  4. 允许

这个顺序意味着只有规范名称需要出现在 允许 ， 被禁止的 ， 必修的 .

参数:
kw双关语

关键字参数的字典。

alias_mappingdict或Artist子类或Artist实例，可选

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

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

如果传递了艺术家子类或实例，请使用其属性别名映射。

requiredstr列表，可选

必须在 kws . 此参数已弃用。

forbiddenstr列表，可选

可能不在 kw . 此参数已弃用。

allowedstr列表，可选

允许字段的列表。如果这不是没有，那么提高如果 kw 包含不在的联合中的任何键 必修的 和 允许 . 只允许必需字段传入空元组 allowed=() . 此参数已弃用。
加薪:
TypeError

如果将无效的args/kwargs传递给可调用文件，则匹配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 查找阻止某些对象被垃圾回收的循环。

参数:
objects

要在其中查找循环的对象列表。

outstream

输出流。

show_progress布尔

如果为真，则打印找到时达到的对象数。
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.report_memory(i=0)[源代码]

返回进程消耗的内存。

matplotlib.cbook.safe_first_element(obj)[源代码]

返回中的第一个元素 obj .

该协议是一种独立的或同时支持该访问类型的访问方式。

matplotlib.cbook.safe_masked_invalid(x, copy=False)[源代码]
matplotlib.cbook.sanitize_sequence(data)[源代码]

将dictview对象转换为list。其他输入返回不变。

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>
matplotlib.cbook.simple_linear_interpolation(a, steps)[源代码]

对数组重新取样 steps - 1 原始点对之间的点。

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

参数:
a数组，形状（n，…）
steps利息
返回:
数组

形状 ((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 和 编码 . 如果是一个类似于文件的对象，它将被传递。

flagstr，默认'r'

作为 mode 参数 open 什么时候？ 文件名 是 str 或 os.PathLike ；忽略如果 文件名 像文件一样。

return_openedbool，默认为False

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

encodingstr或None，默认为None

作为 mode 参数 open 什么时候？ 文件名 是 str 或 os.PathLike ；忽略如果 文件名 像文件一样。
返回:
fh类文件
opened布尔

开的 仅在以下情况下返回 return_opened 是True。
matplotlib.cbook.violin_stats(X, method, points=100, quantiles=None)[源代码]

返回可用于绘制一系列曲线图的数据字典列表。

见 Returns 要查看下面的“关键字”部分所需的字典。

用户可以跳过此函数，并将具有相同键的用户定义词典集传递给 violinplot 而不是使用Matplotlib进行计算。见 返回 下面一节介绍字典中必须出现的键。

参数:
X类数组

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

method可赎回的

用于计算每列数据的核密度估计的方法。当被呼叫通过时 method(v, coords) ，它应该返回以coords中指定的值计算的kde值的向量。

pointsint，默认值：100

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

quantiles类似数组，默认值：无

定义（如果不是没有）间隔中的浮动列表 [0, 1] 对于每列数据，它表示将为该列数据呈现的分位数。必须有2个或更少的维度。1D数组将被视为包含它们的单例列表。
返回:
DICT列表

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

  • coords：一个包含这个特定内核密度估计的坐标的标量列表。
  • VAL：一个包含内核密度估计值的标量列表，其中每个坐标在 坐标 .
  • mean：此列数据的平均值。
  • 中间值：此数据列的中间值。
  • 最小值：此数据列的最小值。
  • max：此数据列的最大值。
  • 分位数：此数据列的分位数值。
exception matplotlib.cbook.deprecation.MatplotlibDeprecationWarning[源代码]

基类：UserWarning

用于为Matplotlib用户发出弃用警告的类。

鉴于Python内置的DeprecationWarnings在python2.7中默认被忽略（参见下面的链接），这个类的加入是为了允许deprecation的信号传递，但是通过UserWarnings，默认情况下不会被忽略。

https://docs.python.org/dev/whatsnew/2.7.html-未来python-2-x

matplotlib.cbook.deprecation.deprecated(since, *, message='', name='', alternative='', pending=False, obj_type=None, addendum='', removal='')[源代码]

Decorator将函数、类或属性标记为已弃用。

当弃用classmethod、staticmethod或属性时 @deprecated 装潢师应该走了 在下面 @classmethod 和 @staticmethod （即， deprecated 应该直接修饰底层的（可调用的），但是 over @property .

参数:
sinceSTR

此API被弃用的版本。

message可选的STR

重写默认的弃用消息。这个 %(since)s ， %(name)s ， %(alternative)s ， %(obj_type)s ， %(addendum)s 和 %(removal)s 格式说明符将被传递给该函数的各个参数的值替换。

name可选的STR

在不推荐使用的消息中使用的名称；如果未提供，则该名称将自动从不推荐使用的对象中确定。

alternative可选的STR

用户可以使用的替代API来代替不推荐使用的API。如果提供了此选项，则不推荐使用警告将告诉用户此选项。

pending可选的布尔

如果为True，则使用PendingDeprecationWarning而不是DeprecationWarning。不能与一起使用 去除 .

obj_type可选的STR

不推荐使用的对象类型；默认情况下，如果装饰类，则为“class”；如果装饰属性，则为“attribute”；否则为“function”。

addendum可选的STR

直接附加到最终消息的附加文本。

removal可选的STR

预期的删除版本。计算的是空字符串（默认为从中删除） 自从 . 设置为其他Falsy值以不安排删除日期。不能与一起使用 悬而未决的 .

实例

基本示例：

@deprecated('1.4.0')
def the_function_to_deprecate():
    pass
matplotlib.cbook.deprecation.mplDeprecation

alias of matplotlib.cbook.deprecation.MatplotlibDeprecationWarning

matplotlib.cbook.deprecation.warn_deprecated(since, *, message='', name='', alternative='', pending=False, obj_type='', addendum='', removal='')[源代码]

显示标准化的弃用。

参数:
sinceSTR

此API被弃用的版本。

message可选的STR

重写默认的弃用消息。这个 %(since)s ， %(name)s ， %(alternative)s ， %(obj_type)s ， %(addendum)s 和 %(removal)s 格式说明符将被传递给该函数的各个参数的值替换。

name可选的STR

不推荐使用的对象的名称。

alternative可选的STR

用户可以使用的替代API来代替不推荐使用的API。如果提供了此选项，则不推荐使用警告将告诉用户此选项。

pending可选的布尔

如果为True，则使用PendingDeprecationWarning而不是DeprecationWarning。不能与一起使用 去除 .

obj_type可选的STR

不推荐使用的对象类型。

addendum可选的STR

直接附加到最终消息的附加文本。

removal可选的STR

预期的删除版本。计算的是空字符串（默认为从中删除） 自从 . 设置为其他Falsy值以不安排删除日期。不能与一起使用 悬而未决的 .

实例

基本示例：

# To warn of the deprecation of "matplotlib.name_of_module"
warn_deprecated('1.4.0', name='matplotlib.name_of_module',
                obj_type='module')