break-axes 0.1.1

Implementing broken axis effect in matplotlib

break_axes

This is a test version and lacks English support.

install

pip install break_axes

基本说明

这是一个用于在matplotlib中实现坐标轴断裂的工具。相比之前的项目 mpl_fold_axis， 此项目不需要使用矩形白色色块填充折叠区域，来遮盖折叠区域， 而是使用路径裁剪的方式，来实现坐标轴的断裂，因此可以支持透明背景图片。

同时此项目修正了mpl_fold_axis中的一些Bug， 例如整数坐标可能出现位置错乱。

通常用户只需要使用如下两个函数即可：

• scale_axes：用于缩放坐标轴 参数： ax: 坐标轴

    x_interval: 要缩放的x轴区间，其为三元组列表，即`[(a0,b0,factor0),(a1,b1,factor1),...]`
  
    y_interval: 要缩放的y轴区间，其为三元组列表
  
    mode: 缩放模式，可选值为"linear"和"log"，默认值为"linear"
  

• broken_and_clip_axes：用于断裂坐标轴和裁剪坐标轴内的 artists 参数： ax: 坐标轴

    x: 要生成断点的 x 坐标列表
  
    y: 要生成断点的 y 坐标列表
  
    axes_clip: 是否裁剪坐标系内的 artists, 默认为 True
  
    which: 生成断裂标示的位置，可选`"lower", "upper", "both"`，默认值为"both"
            此时对于x方向，底部和顶部的坐标轴都会添加断裂标识，y方向同理
    
    gap: 断点之间的间距，默认为 5，单位为 磅(pt)
  
    dx: 断裂标识的半宽度，默认为 3，单位为 磅(pt)
  
    dy: 断裂标识的半高度，默认为 3，单位为 磅(pt)
  
    此外，还可以通过 `color, linewidth, zorder` 等关键字参数来自定义断裂标识的颜色和线宽，
    其中 zorder 设置为较大值，例如100，可以确保断裂标识在其他 artists 之上。
  

注意：在调用broken_and_clip_axes函数前，需要通过ax.set(xlim=..., ylim=...)或 ax.set_xlim(...)和ax.set_ylim(...)来固定坐标轴的显示范围。

下方是一个例子。

import

import matplotlib.pyplot as plt

from break_axes import __version__, scale_axes, broken_and_clip_axes

plt.rcParams['figure.figsize'] = (3,3)
plt.rcParams['figure.dpi'] = 200
plt.rcParams['axes.linewidth'] = 1.5

print(f"break_axes version: {__version__}")

多处断裂坐标轴 (Multiple Broken Axes)

fig, ax = plt.subplots(figsize=(4.5,3))
ax.set(xlim=(-32,32), ylim=(0,180), xlabel="x (unit)", ylabel="y (unit)")
ax.set_facecolor("#DDFFAA")
ax.grid(ls=':', lw=0.5, color='dimgray')

# scale x-axis and y-axis to reduce the blank space
scale_axes(ax,
           x_interval=[(-28, -2, 0.01), (2, 28, 0.01)],
           y_interval=[(40,100, 0.1), (100, 180, 0.6)], 
           mode="linear")


_ = ax.set_xticks([-31,-30,-29,-1,0,1,29,30,31])
_ = ax.set_yticks([0,20, 40, 100, 120, 140,160])

rects = ax.bar([-31,-30,-29,-1,0,1,31,30,29], [20,40,22,132,155,108,5,27,17] )
ax.bar_label(rects)

# Text and Annotation wont be clipped
ax.annotate("This is a very long long string.", xy=(-30, 80), xytext=(-30, 168), 
    arrowprops=dict(
        arrowstyle='-|>',
        connectionstyle="arc3,rad=0.1", 
        color='k', 
        shrinkA=5, shrinkB=5
    )
)

# Add broken line in x-axis and y-axis, clip spines and artists in axes
broken_and_clip_axes(ax, x=[-15,15], y=[70], axes_clip=True, which='lower',
                     gap=5, dx=3, dy=3)

# plt.savefig("break_axes_bar.png", transparent=False)

对数坐标系 (Log Axes)

import numpy as np

x = np.logspace(0, 4, 100)

fig, ax = plt.subplots(figsize=(4,3))
ax.set(xlim=(1,10000), ylim=(1,10000), facecolor="#DDFFAA")  
ax.plot(x, x)
ax.set_xticks([1, 10, 100, 500, 5000, 10000],
              [1, 10, 100, 500, 5000, r'$10^4$'])
ax.set_yticks([1, 10, 100, 500, 5000, 10000],
              [1, 10, 100, 500, 5000, r'$10^4$'])


ax.annotate("This is a very long long string.", xy=(5, 10), xytext=(10, 5000), 
    arrowprops=dict(
        arrowstyle='-|>',
        connectionstyle="arc3,rad=0.1", 
        color='k', 
        shrinkA=5, shrinkB=5
    )
)


ax.grid(ls=':')
ax.set_xlabel("X Label")
ax.set_ylabel("Y Label")
ax.set_title("Broken Axis Example - Log Mode")

scale_axes(ax, x_interval=[(600, 4000, 0.1)], y_interval=[(600, 4000, 0.1)],
           mode='log')
broken_and_clip_axes(ax, x=[1500], y=[1500], axes_clip=True, which='lower',
                     gap=5, dx=3, dy=3)

plt.show()

Basic Description

This is a tool for implementing axis breaks in matplotlib. Compared with the previous project mpl_fold_axis, this project does not require using white rectangular blocks to fill and cover the folded area. Instead, it adopts the path clipping method to achieve axis breaks, thus supporting transparent background images.

Meanwhile, this project fixes some bugs in mpl_fold_axis, such as the possible misalignment of integer coordinates.

Typically, users only need to use the following two functions:

• scale_axes: Used to scale the axes
  Parameters:
  ax: The axis object

    x_interval: A list of triples representing the x-axis intervals to be scaled, in the format `[(a0,b0,factor0),(a1,b1,factor1),...]`  
  
    y_interval: A list of triples representing the y-axis intervals to be scaled  
  
    mode: Scaling mode, optional values are "linear" and "log", default is "linear"  
  

• broken_and_clip_axes: Used to create axis breaks and clip artists within the axes
  Parameters:
  ax: The axis object

    x: A list of x-coordinates where break points are to be created  
  
    y: A list of y-coordinates where break points are to be created  
  
    axes_clip: Whether to clip artists within the coordinate system, default is True  
  
    which: Position to generate break marks, optional values are `"lower", "upper", "both"`, default is "both"  
            In this case, break marks will be added to both the bottom and top of the x-axis, and the same applies to the y-axis.  
  
    gap: Spacing between break points, default is 5, unit is **points (pt)**  
  
    dx: Half-width of the break mark, default is 3, unit is **points (pt)**  
  
    dy: Half-height of the break mark, default is 3, unit is **points (pt)**  
  
    Additionally, keyword arguments such as `color, linewidth, zorder` can be used to customize the color and line width of the break marks.  
    Setting `zorder` to a large value (e.g., 100) ensures the break marks are displayed above other artists.  
  

Note: Before calling the broken_and_clip_axes function, you need to fix the display range of the axes using ax.set(xlim=..., ylim=...), ax.set_xlim(...), or ax.set_ylim(...).

An example is provided below.