1.4.x 中的 API 变更#

代码变更#

  • 对 axes 模块进行了重大重构。axes 模块已被拆分为更小的模块

    • _base 模块，其中包含一个新的私有 _AxesBase 类。该类包含除绘图和标注方法之外的所有方法。

    • axes 模块，其中包含 axes.Axes 类。该类继承自 _AxesBase，并包含所有绘图和标注方法。

    • _subplot 模块，包含所有与子图（subplotting）相关的类。

    有一些内容不再存在于 axes 模块的命名空间中。如果您使用它们，则需要从其原始位置导入：

    • math -> import math

    • ma -> from numpy import ma

    • cbook -> from matplotlib import cbook

    • docstring -> from matplotlib import docstring

    • is_sequence_of_strings -> from matplotlib.cbook import is_sequence_of_strings

    • is_string_like -> from matplotlib.cbook import is_string_like

    • iterable -> from matplotlib.cbook import iterable

    • itertools -> import itertools

    • martist -> from matplotlib import artist as martist

    • matplotlib -> import matplotlib

    • mcoll -> from matplotlib import collections as mcoll

    • mcolors -> from matplotlib import colors as mcolors

    • mcontour -> from matplotlib import contour as mcontour

    • mpatches -> from matplotlib import patches as mpatches

    • mpath -> from matplotlib import path as mpath

    • mquiver -> from matplotlib import quiver as mquiver

    • mstack -> from matplotlib import stack as mstack

    • mstream -> from matplotlib import stream as mstream

    • mtable -> from matplotlib import table as mtable

  • 作为启用 Qt5 支持重构的一部分，模块 matplotlib.backends.qt4_compat 已重命名为 matplotlib.backends.qt_compat。qt4_compat 在 1.4 版中已弃用，并将在 1.5 版中移除。

  • errorbar() 方法已更改，使得上限和下限（lolims、uplims、xlolims、xuplims）现在指向正确的方向。

  • errorbar() 的 fmt kwarg 现在支持字符串 'none' 来抑制线条和标记的绘制；为此使用 None 对象已被弃用。默认的 fmt 值已更改为空字符串（''），因此线条和标记由 plot() 默认值控制。

  • 修复了字体路径效果渲染中的一个错误，这意味着字体大小现在与非路径效果字体保持一致。详情请参阅 matplotlib/matplotlib#2889。

  • Sphinx 扩展 ipython_directive 和 ipython_console_highlighting 已移至 IPython 项目本身。虽然它们在此版本中仍保留在 Matplotlib 中，但已被弃用。请更新您在 conf.py 中的扩展，使其指向 IPython.sphinxext.ipython_directive 而非 matplotlib.sphinxext.ipython_directive。

  • 在 matplotlib.finance 中，几乎所有函数都已被弃用，并替换为一对名为 *_ochl 和 *_ohlc 的函数。前者是此模块中先前使用的 '开-收-高-低' 报价顺序，后者是金融中标准的 '开-高-低-收' 顺序。

  • 为了保持一致性，matplotlib.patheffects.SimplePatchShadow 的 face_alpha 关键字已弃用，取而代之的是 alpha 关键字。同样，关键字 offset_xy 在所有 AbstractPathEffect 中现在都命名为 offset。matplotlib.patheffects._Base 已重命名为 matplotlib.patheffects.AbstractPathEffect。matplotlib.patheffect.ProxyRenderer 已重命名为 matplotlib.patheffects.PathEffectRenderer，现在是完整的 RendererBase 子类。

  • 用于绘制 Figure.colorbar 轮廓的 artist 已从 matplotlib.lines.Line2D 更改为 matplotlib.patches.Polygon，因此 colorbar.ColorbarBase.outline 现在是一个 matplotlib.patches.Polygon 对象。

  • 图例处理程序接口已从可调用对象更改为实现 legend_artists 方法的任何对象（弃用阶段将确保此接口在 v1.4 中保持不变）。更多详情请参阅图例指南。进一步的图例变更包括：

    • matplotlib.axes.Axes._get_legend_handles 现在返回一个句柄生成器，而不是一个列表。

    • legend() 函数的 loc 位置参数已弃用。请改用 loc 关键字参数。

  • 已添加 rcParams["savefig.transparent"]（默认值：False），用于控制保存图形时的默认透明度。

  • 对 Annotation 系列进行了轻微重构。Annotation 中的文本位置现在完全由底层的 Text 对象处理，因此 .set_position 按预期工作。属性 xytext 和 textcoords 已弃用，取而代之的是 xyann 和 anncoords，以便 Annotation 和 AnnotationBbox 可以共享一个共同的、命名合理的 API 来获取/设置文本或框的位置。

    • xyann -> 设置标注的位置

    • xy -> 设置箭头指向的位置

    • anncoords -> 设置标注位置的单位

    • xycoords -> 设置点位置的单位

    • set_position() -> Annotation 仅设置标注的位置

  • matplotlib.mlab.specgram、matplotlib.mlab.psd、matplotlib.mlab.csd、matplotlib.mlab.cohere、matplotlib.mlab.cohere_pairs、matplotlib.pyplot.specgram、matplotlib.pyplot.psd、matplotlib.pyplot.csd 和 matplotlib.pyplot.cohere 现在会在它们以前引发 AssertionError 的地方引发 ValueError。

  • 对于 matplotlib.mlab.psd、matplotlib.mlab.csd、matplotlib.mlab.cohere、matplotlib.mlab.cohere_pairs、matplotlib.pyplot.specgram、matplotlib.pyplot.psd、matplotlib.pyplot.csd 和 matplotlib.pyplot.cohere，在返回形状为 (n, 1) 的数组时，现在会将其转换为 (n, ) 数组。以前，(n, m) 数组会平均为 (n, ) 数组，但 (n, 1) 数组会保持不变。此更改使这两种情况下的维度保持一致。

  • 已添加 rcParams["axes.formatter.useoffset"]（默认值：True），用于控制 ticker.ScalarFormatter 中 useOffset 的默认值。

  • 添加了 Formatter 子类 StrMethodFormatter，它与 FormatStrFormatter 的功能完全相同，但用于新式格式化字符串。

  • matplotlib.testing.image_util 及其唯一函数 matplotlib.testing.image_util.autocontrast 已弃用。它们将在 v1.5.0 中完全移除。

  • plot_date() 的 fmt 参数已从 bo 更改为仅 o，因此默认情况下可以进行颜色循环。

  • 已移除类 FigureManagerQTAgg 并弃用 NavigationToolbar2QTAgg，后者将在 1.5 版中移除。

  • 已从 FigureCanvasQTAgg 中移除了以前的公共（无前缀）属性 rect 和 drawRect；它们始终是（保留的）drawRectangle() 函数的实现细节。

  • matplotlib.tight_bbox.adjust_bbox 和 matplotlib.tight_bbox.process_figure_for_rasterizing 的函数签名已更改。新的 fixed_dpi 参数允许覆盖 figure.dpi 设置，而不是尝试从文件格式推断预期行为。

  • 已为 mpl_toolkits.axes_grid1.axes_grid.ImageGrid 添加了对水平/垂直轴填充的支持 — 如果需要单独的轴填充，参数 axes_pad 现在可以是元组状的（tuple-like）。原始行为得以保留。

  • 已为 matplotlib.transforms.Affine2D 添加了对倾斜变换（skewed transforms）的支持，可以使用 skew 和 skew_deg 方法创建这些变换。

  • 已在 axes.Axes.pie 中添加了 clockwise 参数来控制扇区方向。

  • 在 matplotlib.lines.Line2D 中，markevery 功能已得到扩展。以前，可以使用两元素列表或两元素元组来指定整数起始索引和步长。现在，这只能通过两元素元组来完成。如果使用两元素列表，则将其视为 NumPy 高级索引，并且仅显示与给定索引对应的两个标记。

  • 已从 mpl_toolkits.axes_grid1.anchored_artists.AnchoredSizeBar 调用中移除了 prop 关键字参数。它曾被传递到基类的 __init__ 中，仅用于设置填充。现在，fontproperties（它才是真正用于设置 AnchoredSizeBar 字体属性的参数）会代替 prop 传递。如果未传入 fontproperties 但传入了 prop，则 prop 将代替 fontproperties 使用。如果两者都传入，则 prop 将被静默忽略。

  • pyplot.subplot 及相关命令中使用索引 0 的方式已弃用。由于缺少验证，调用 plt.subplots(2, 2, 0) 不会引发异常，而是将轴放置在_最后_一个位置。这是因为 subplot 中的索引是基于 1 的（为了模仿 MATLAB），所以在索引到用于确定轴位置的 GridSpec 对象之前会减去 1。传入 0 会导致向 GridSpec 传入 -1，从而返回最后一个位置。尽管这种行为显然是错误的且非预期，但我们正在谨慎地进行弃用周期，以防有用户利用此“功能”。在 1.4 版中，使用 0 作为索引将引发警告，在 1.5 版中将引发异常。

  • 偏移框上的裁剪现在默认关闭。

  • Matplotlib 现在在关闭图形时使用侵入性较低的 gc.collect(1) 调用，以避免内存中存在大量用户对象时出现严重的延迟。

  • 所有饼图 artist 的默认剪裁值现在默认为 False。

代码移除#

  • 已移除 mlab.levypdf。该代码会引发 NumPy 错误（并且长期如此），并且不是 Levy 分布的标准形式。应改用 scipy.stats.levy。

在此页