axisartist 工具包#

警告

axisartist 使用一个自定义的 Axes 类(派生自 Matplotlib 的原始 Axes 类)。作为副作用,一些命令(主要是刻度相关的)可能无法工作。

axisartist 包含一个自定义的 Axes 类,旨在支持曲线网格(例如,天文学中的世界坐标系)。与 Matplotlib 的原始 Axes 类(其使用 Axes.xaxis 和 Axes.yaxis 绘制刻度、刻度线等)不同,axisartist 使用一个特殊的艺术家(AxisArtist)来处理弯曲坐标系中的刻度、刻度线等。

../../../_images/sphx_glr_demo_floating_axis_001.png

由于它使用了特殊的艺术家,一些作用于 Axes.xaxis 和 Axes.yaxis 的 Matplotlib 命令可能无法工作。

axisartist#

axisartist 模块提供了一个自定义的(且非常实验性的)Axes 类,其中每个轴(左、右、上、下)都有一个单独关联的艺术家,负责绘制轴线、刻度、刻度标签和标签。您还可以创建自己的轴,该轴可以穿过轴坐标中的固定位置,或数据坐标中的固定位置(即当视图限制变化时,轴会浮动)。

Axes 类默认将其 xaxis 和 yaxis 设置为不可见,并有 4 个额外的艺术家,负责绘制“左”、“右”、“下”和“上”的 4 个轴脊。它们通过 ax.axis["left"]、ax.axis["right"] 等方式访问,即 ax.axis 是一个包含艺术家的字典(请注意,ax.axis 仍然是一个可调用方法,其行为与 Matplotlib 中的原始 Axes.axis 方法相同)。

要创建一个 Axes,

import mpl_toolkits.axisartist as AA
fig = plt.figure()
fig.add_axes([0.1, 0.1, 0.8, 0.8], axes_class=AA.Axes)

或创建一个子图

fig.add_subplot(111, axes_class=AA.Axes)
# Given that 111 is the default, one can also do
fig.add_subplot(axes_class=AA.Axes)

例如,您可以使用以下方式隐藏右侧和顶部的轴脊:

ax.axis["right"].set_visible(False)
ax.axis["top"].set_visible(False)
../../../_images/sphx_glr_simple_axisline3_001.png

也可以添加水平轴。例如,您可以在 y=0 处(在数据坐标中)有一个水平轴。

ax.axis["y=0"] = ax.new_floating_axis(nth_coord=0, value=0)
../../../_images/sphx_glr_simple_axisartist1_001.png

或者一个带偏移量的固定轴

# make new (right-side) yaxis, but with some offset
ax.axis["right2"] = ax.new_fixed_axis(loc="right", offset=(20, 0))

axisartist 与 ParasiteAxes#

axes_grid1 工具包中的大多数命令都可以接受 axes_class 关键字参数,并且这些命令会创建给定类的 Axes。例如,要使用 axisartist.Axes 创建一个主子图:

import mpl_toolkits.axisartist as AA
from mpl_toolkits.axes_grid1 import host_subplot

host = host_subplot(111, axes_class=AA.Axes)

这是一个使用 ParasiteAxes 的示例。

../../../_images/sphx_glr_demo_parasite_axes2_001.png

曲线网格#

AxisArtist 模块背后的动机是支持曲线网格和刻度。

../../../_images/sphx_glr_demo_curvelinear_grid_001.png

浮动坐标轴#

AxisArtist 还支持浮动坐标轴,其外部坐标轴被定义为浮动轴。

../../../_images/sphx_glr_demo_floating_axes_001.png

axisartist 命名空间#

axisartist 命名空间包含一个派生的 Axes 实现。最大的区别在于,负责绘制轴线、刻度、刻度标签和轴标签的艺术家已从 Matplotlib 的 Axis 类中分离出来,这些艺术家比原始 Matplotlib 中的艺术家功能强大得多。这一改变的强烈动机是为了支持曲线网格。以下是 mpl_toolkits.axisartist.Axes 与 Matplotlib 原始 Axes 的几个不同之处:

  • 轴元素(轴线(轴脊)、刻度、刻度标签和轴标签)由 AxisArtist 实例绘制。与 Axis 不同,左、右、上、下轴由单独的艺术家绘制。它们各自可以有不同的刻度位置和不同的刻度标签。

  • 网格线由 Gridlines 实例绘制。这一改变的动机是,在曲线坐标中,网格线可能不会穿过轴线(即没有关联的刻度)。在原始 Axes 类中,网格线与刻度是绑定的。

  • 刻度线在必要时可以旋转(即沿着网格线)

总之,所有这些改变都是为了支持:

  • 曲线网格。

  • 浮动轴。

../../../_images/sphx_glr_demo_floating_axis_001.png

mpl_toolkits.axisartist.Axes 类定义了一个 axis 属性,它是一个 AxisArtist 实例的字典。默认情况下,该字典包含 4 个 AxisArtist 实例,分别负责绘制左、右、下和上轴。

xaxis 和 yaxis 属性仍然可用,但它们被设置为不可见。由于使用单独的艺术家来渲染轴,Matplotlib 中的一些与轴相关的方法可能无效。除了 AxisArtist 实例,mpl_toolkits.axisartist.Axes 还将具有 gridlines 属性 (Gridlines),它显然用于绘制网格线。

在 AxisArtist 和 Gridlines 中,刻度线和网格位置的计算被委托给 GridHelper 类的一个实例。mpl_toolkits.axisartist.Axes 类使用 GridHelperRectlinear 作为网格辅助器。GridHelperRectlinear 类是 Matplotlib 原始 Axes 的 xaxisyaxis 的包装器,旨在以 Matplotlib 原始轴的工作方式运行。例如,使用 set_ticks 方法等更改刻度位置应该按预期工作。但艺术家属性(例如颜色)的更改通常不起作用,尽管已做了一些努力,以便一些经常更改的属性(颜色等)能得到尊重。

AxisArtist#

AxisArtist 可以被视为一个容器艺术家,具有以下属性,用于绘制刻度、标签等:

  • line

  • major_ticks, major_ticklabels

  • minor_ticks, minor_ticklabels

  • offsetText

  • label

line#

派生自 Line2D 类。负责绘制轴脊线(?)。

major_ticks, minor_ticks#

派生自 Line2D 类。注意,刻度是标记。

major_ticklabels, minor_ticklabels#

派生自 Text。请注意,它不是 Text 艺术家的列表,而是一个单一的艺术家(类似于集合)。

axislabel#

派生自 Text。

默认 AxisArtists#

默认情况下,定义了以下轴艺术家:

ax.axis["left"], ax.axis["bottom"], ax.axis["right"], ax.axis["top"]

顶部和右侧轴的刻度标签和轴标签被设置为不可见。

例如,如果您想更改底部 x 轴主刻度标签的颜色属性:

ax.axis["bottom"].major_ticklabels.set_color("b")

类似地,要使刻度标签不可见:

ax.axis["bottom"].major_ticklabels.set_visible(False)

AxisArtist 提供了一个辅助方法来控制刻度、刻度标签和标签的可见性。要使刻度标签不可见:

ax.axis["bottom"].toggle(ticklabels=False)

要使所有刻度、刻度标签和(轴)标签不可见:

ax.axis["bottom"].toggle(all=False)

要关闭所有但保留刻度:

ax.axis["bottom"].toggle(all=False, ticks=True)

要打开所有但关闭(轴)标签:

ax.axis["bottom"].toggle(all=True, label=False)

ax.axis 的 __getitem__ 方法可以接受多个轴名称。例如,要打开“上”轴和“右”轴的刻度标签:

ax.axis["top", "right"].toggle(ticklabels=True)

请注意,ax.axis["top", "right"] 返回一个简单的代理对象,它将上述代码转换为以下形式。

for n in ["top", "right"]:
    ax.axis[n].toggle(ticklabels=True)

因此,for 循环中的任何返回值都会被忽略。您不应将其用于除简单方法之外的任何其他用途。

就像列表索引中的“:”表示所有项一样,即:

ax.axis[:].major_ticks.set_color("r")

更改所有轴上的刻度颜色。

操作指南#

  1. 更改刻度位置和标签。

    与 Matplotlib 原始 Axes 相同。

    ax.set_xticks([1, 2, 3])
    
  2. 更改轴属性,如颜色等。

    更改相应艺术家的属性。例如,要更改刻度标签的颜色:

    ax.axis["left"].major_ticklabels.set_color("r")
    
  3. 要更改多个轴的属性:

    ax.axis["left", "bottom"].major_ticklabels.set_color("r")
    

    或更改所有轴的属性:

    ax.axis[:].major_ticklabels.set_color("r")
    
  4. 要更改刻度大小(长度),您需要使用 axis.major_ticks.set_ticksize 方法。要更改刻度的方向(刻度默认与刻度标签方向相反),请使用 axis.major_ticks.set_tick_out 方法。

    要更改刻度与刻度标签之间的间距,请使用 axis.major_ticklabels.set_pad 方法。

    要更改刻度标签与轴标签之间的间距,请使用 axis.label.set_pad 方法。

刻度标签的旋转和对齐#

这也与标准的 Matplotlib 相当不同,可能会令人困惑。当您想旋转刻度标签时,首先考虑使用 "set_axis_direction" 方法。

ax1.axis["left"].major_ticklabels.set_axis_direction("top")
ax1.axis["right"].label.set_axis_direction("left")
../../../_images/sphx_glr_simple_axis_direction01_001.png

set_axis_direction 的参数是 ["left", "right", "bottom", "top"] 之一。

您必须理解一些方向的基本概念。

  • 有一个参考方向,它被定义为坐标增加时轴线的方向。例如,左侧 x 轴的参考方向是从下到上。

    刻度、刻度标签和轴标签的方向、文本角度和对齐方式是相对于参考方向确定的。

  • label_directionticklabel_direction 是参考方向的右侧(+)或左侧(-)。

  • 刻度默认朝向刻度标签的相反方向绘制。

  • 刻度标签和标签的文本旋转是分别参照 ticklabel_directionlabel_direction 确定的。刻度标签和标签的旋转是固定的。

../../../_images/sphx_glr_axis_direction_001.png

另一方面,还有一个“axis_direction”的概念。这是上述属性对每个“下”、“左”、“上”和“右”轴的默认设置。

axislabel 属性默认值#

参考方向

标签方向

标签旋转

水平对齐

垂直对齐

'-'

180

居中

'+'

0

居中

'+'

0

居中

'-'

180

居中

ticklabel 属性默认值#

参考方向

标签方向

标签旋转

水平对齐

垂直对齐

'-'

90

居中

'+'

0

居中

基线

'+'

-90

居中

'-'

180

居中

基线

此外,`set_axis_direction("top")` 意味着调整文本旋转等,以适应“上”轴的设置。轴方向的概念在弯曲轴的情况下可能更清晰。

../../../_images/sphx_glr_demo_axis_direction_001.png

axis_direction 可以在 AxisArtist 级别进行调整,或者在其子艺术家(即刻度、刻度标签和轴标签)级别进行调整。

ax1.axis["left"].set_axis_direction("top")

更改与“左”轴关联的所有艺术家的 axis_direction,而:

ax1.axis["left"].major_ticklabels.set_axis_direction("top")

仅更改 major_ticklabels 的 axis_direction。请注意,AxisArtist 级别的 set_axis_direction 会更改 ticklabel_direction 和 label_direction,而更改刻度、刻度标签和轴标签的 axis_direction 不会影响它们。

如果您想让刻度向外而刻度标签在轴内,请使用 invert_ticklabel_direction 方法。

ax.axis[:].invert_ticklabel_direction()

一个相关的方法是 "set_tick_out"。它使刻度向外(实际上,它使刻度朝向默认方向的相反方向)。

ax.axis[:].major_ticks.set_tick_out(True)
../../../_images/sphx_glr_simple_axis_direction03_001.png

综上所述:

  • AxisArtist 的方法

    • set_axis_direction: "left", "right", "bottom", or "top"

    • set_ticklabel_direction: "+" or "-"

    • set_axislabel_direction: "+" or "-"

    • invert_ticklabel_direction

  • 刻度的方法 (major_ticks 和 minor_ticks)

    • set_tick_out: True 或 False

    • set_ticksize: 大小(以点为单位)

  • 刻度标签的方法 (major_ticklabels 和 minor_ticklabels)

    • set_axis_direction: "left", "right", "bottom", or "top"

    • set_rotation: 相对于参考方向的角度

    • set_ha 和 set_va: 见下文

  • 轴标签的方法 (label)

    • set_axis_direction: "left", "right", "bottom", or "top"

    • set_rotation: 相对于参考方向的角度

    • set_ha 和 set_va

调整刻度标签对齐方式#

刻度标签的对齐方式有特殊处理。见下文。

../../../_images/sphx_glr_demo_ticklabel_alignment_001.png

调整间距#

更改刻度与刻度标签之间的间距:

ax.axis["left"].major_ticklabels.set_pad(10)

或刻度标签与轴标签之间的间距:

ax.axis["left"].label.set_pad(10)
../../../_images/sphx_glr_simple_axis_pad_001.png

GridHelper#

要实际定义曲线坐标,您必须使用自己的网格辅助器。这里提供了一个通用版本的网格辅助器类,此类别在大多数情况下应该足够。用户可以提供两个函数来定义从曲线坐标到(直线)图像坐标的变换(及其逆变换对)。请注意,虽然刻度和网格是为曲线坐标绘制的,但轴本身的数据变换(ax.transData)仍然是直线(图像)坐标。

from mpl_toolkits.axisartist.grid_helper_curvelinear \
     import GridHelperCurveLinear
from mpl_toolkits.axisartist import Axes

# from curved coordinate to rectlinear coordinate.
def tr(x, y):
    x, y = np.asarray(x), np.asarray(y)
    return x, y-x

# from rectlinear coordinate to curved coordinate.
def inv_tr(x, y):
    x, y = np.asarray(x), np.asarray(y)
    return x, y+x

grid_helper = GridHelperCurveLinear((tr, inv_tr))

fig.add_subplot(axes_class=Axes, grid_helper=grid_helper)

您也可以使用 Matplotlib 的 Transform 实例(但必须定义逆变换)。通常,曲线坐标系中的坐标范围可能有限,或者可能存在周期。在这些情况下,需要更定制化的网格辅助器版本。

import mpl_toolkits.axisartist.angle_helper as angle_helper

# PolarAxes.PolarTransform takes radian. However, we want our coordinate
# system in degree
tr = Affine2D().scale(np.pi/180., 1.) + PolarAxes.PolarTransform()

# extreme finder: find a range of coordinate.
# 20, 20: number of sampling points along x, y direction
# The first coordinate (longitude, but theta in polar)
#   has a cycle of 360 degree.
# The second coordinate (latitude, but radius in polar)  has a minimum of 0
extreme_finder = angle_helper.ExtremeFinderCycle(20, 20,
                                                 lon_cycle=360,
                                                 lat_cycle=None,
                                                 lon_minmax=None,
                                                 lat_minmax=(0, np.inf),
                                                 )

# Find a grid values appropriate for the coordinate (degree,
# minute, second). The argument is a approximate number of grids.
grid_locator1 = angle_helper.LocatorDMS(12)

# And also uses an appropriate formatter.  Note that the acceptable Locator
# and Formatter classes are different than that of Matplotlib's, and you
# cannot directly use Matplotlib's Locator and Formatter here (but may be
# possible in the future).
tick_formatter1 = angle_helper.FormatterDMS()

grid_helper = GridHelperCurveLinear(tr,
                                    extreme_finder=extreme_finder,
                                    grid_locator1=grid_locator1,
                                    tick_formatter1=tick_formatter1
                                    )

再次强调,轴的 transData 仍然是直线坐标(图像坐标)。您可以手动在两种坐标之间进行转换,或者为了方便起见使用 Parasite Axes。

ax1 = SubplotHost(fig, 1, 2, 2, grid_helper=grid_helper)

# A parasite axes with given transform
ax2 = ax1.get_aux_axes(tr, "equal")
# note that ax2.transData == tr + ax1.transData
# Anything you draw in ax2 will match the ticks and grids of ax1.
../../../_images/sphx_glr_demo_curvelinear_grid_001.png

FloatingAxis#

浮动轴是一种轴,其数据坐标之一是固定的,即其位置在 Axes 坐标中不是固定的,而是随着轴数据限制的变化而变化。可以使用 new_floating_axis 方法创建浮动轴。但是,您有责任将生成的 AxisArtist 正确添加到轴中。推荐的方法是将其作为 Axes 的 axis 属性的一个项添加。

# floating axis whose first (index starts from 0) coordinate
# (theta) is fixed at 60

ax1.axis["lat"] = axis = ax1.new_floating_axis(0, 60)
axis.label.set_text(r"$\theta = 60^{\circ}$")
axis.label.set_visible(True)

请参阅本页的第一个示例。

当前限制和待办事项#

代码需要进一步完善。以下是不完整的已知问题和待办事项列表:

  • 没有简单的方法支持用户自定义刻度位置(用于曲线网格)。需要创建一个新的 Locator 类。

  • FloatingAxis 可能具有坐标限制,例如,x=0 的浮动轴,但 y 仅从 0 跨越到 1。

  • FloatingAxis 的轴标签位置需要可选地作为坐标值给出。例如,x=0 的浮动轴,标签在 y=1。