Uniplot

轻量级终端绘图工具。通过 Unicode 实现 4 倍分辨率。

在处理生产环境的数据科学代码时，拥有一个不依赖图形库且不仅限于 Jupyter notebook 的绘图工具会很方便。

这个工具的使用场景是将绘图作为数据科学/机器学习 CI/CD 流程的一部分 - 这样当出现问题时，你不仅能得到错误信息和回溯，还能通过图表直观地看到问题所在。

特性

• 使用 Unicode 绘图，分辨率（像素）是普通 ASCII 图的 4 倍
• 极简 API
• 交互模式（传入 interactive=True）
• 彩色模式（传入 color=True），特别适用于绘制多个数据系列
• 速度快：得益于 NumPy 魔法，绘制 100 万个数据点只需 100 毫秒
• 只有一个依赖：NumPy（不过你应该已经安装了吧）

请注意，Unicode 绘图只有在使用完全支持制表符字符集的字体时才能正确显示。请参考此页面查看（不完整的）支持字体列表。

示例

注意，所有示例都不使用彩色，且只绘制单个数据系列。有关使用彩色的示例，请参看上面的 GIF。

绘制正弦波

import math
x = [math.sin(i/20)+i/300 for i in range(600)]
from uniplot import plot
plot(x, title="正弦波")

结果：

                          正弦波
┌────────────────────────────────────────────────────────────┐
│                                                    ▟▀▚     │
│                                                   ▗▘ ▝▌    │
│                                       ▗▛▜▖        ▞   ▐    │
│                                       ▞  ▜       ▗▌    ▌   │ 2
│                           ▟▀▙        ▗▘  ▝▌      ▐     ▜   │
│                          ▐▘ ▝▖       ▞    ▜      ▌     ▝▌  │
│              ▗▛▜▖        ▛   ▜      ▗▌    ▝▌    ▐▘      ▜  │
│              ▛  ▙       ▗▘   ▝▖     ▐      ▚    ▞       ▝▌ │
│  ▟▀▖        ▐▘  ▝▖      ▟     ▚     ▌      ▝▖  ▗▌        ▜▄│ 1
│ ▐▘ ▐▖       ▛    ▙      ▌     ▐▖   ▗▘       ▚  ▞           │
│ ▛   ▙      ▗▘    ▐▖    ▐       ▙   ▞        ▝▙▟▘           │
│▐▘   ▐▖     ▐      ▌    ▛       ▐▖ ▗▘                       │
│▞     ▌     ▌      ▐   ▗▘        ▜▄▛                        │
│▌─────▐────▐▘───────▙──▞────────────────────────────────────│ 0
│       ▌   ▛        ▝▙▟▘                                    │
│       ▜  ▐▘                                                │
│        ▙▄▛                                                 │
└────────────────────────────────────────────────────────────┘
         100       200       300       400       500       600

绘制全球温度数据

这里我们使用 Pandas 从 Our World in Data GitHub 仓库 加载和准备全球温度数据。

首先我们加载数据，重命名列并过滤数据：

import pandas as pd
uri = "https://github.com/owid/owid-datasets/raw/master/datasets/Global%20average%20temperature%20anomaly%20-%20Hadley%20Centre/Global%20average%20temperature%20anomaly%20-%20Hadley%20Centre.csv"
data = pd.read_csv(uri)
data = data.rename(columns={"Global average temperature anomaly (Hadley Centre)": "Global"})
data = data[data.Entity == "median"]

然后我们可以绘制图表：

from uniplot import plot
plot(xs=data.Year, ys=data.Global, lines=True, title="全球标准化陆地-海洋温度异常", y_unit=" °C")

结果：

        全球标准化陆地-海洋温度异常
┌────────────────────────────────────────────────────────────┐
│                                                          ▞▀│
│                                                         ▐  │
│                                                         ▐  │
│                                                     ▗   ▌  │ 0.6 °C
│                                           ▙  ▗▄ ▛▄▖▗▘▌ ▞   │
│                                          ▗▜  ▌ ▜  ▚▞ ▚▞    │
│                                          ▐▝▖▐      ▘       │
│                                    ▗   ▗ ▌ ▙▌              │ 0.3 °C
│                                    ▛▖  ▞▙▘  ▘              │
│                              ▖  ▗▄▗▘▐ ▐▘▜                  │
│                            ▟ █  ▞ ▜ ▝▄▘                    │
│   ▗▚   ▗    ▖       ▗   ▖▗▞ █▐  ▌    ▘                     │
│▁▁▁▞▐▁▁▗▘▜▗▀▀▌▁▁▁▁▙▁▁▟▁▁▁▙▐▁▁▜▁▌▞▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁│ 0 °C
│▚ ▐ ▝▖ ▐  ▛  ▌ ▗▄▐ ▌▗▘▌ ▐▝▌    ▝▘                           │
│ ▌▌  ▌ ▞     ▐▗▘ ▛ ▐▞ ▌ ▐                                   │
│ ▝   ▝▖▌     ▐▞    ▝▌ ▚▜▐                                   │
│      ▗▌     ▝        ▝ ▌                                   │
└────────────────────────────────────────────────────────────┘
1,950    1,960    1,970   1,980    1,990    2,000   2,010

参数

plot 函数接受多个参数，全部列举如下。注意只有 ys 是必需的，其他都是可选的。

还有一个 plot_to_string 函数，签名相同，如果你想将结果作为字符串列表获取以在其他地方使用。唯一的区别是 plot_to_string 不支持交互模式。

数据

• xs - 要绘制的点的 x 坐标。可以是 None，或者是用于绘制单个系列的列表或 NumPy 数组，或者是用于绘制多个系列的这些类型的列表。默认为 None，表示 x 轴将只是 ys 的样本索引。
• ys - 要绘制的点的 y 坐标。可以是用于绘制单个系列的列表或 NumPy 数组，或者是用于绘制多个系列的这些类型的列表。

在这两种情况下，NaN 值都会被忽略。

注意，从 v0.12.0 开始，你还可以传入时间戳的列表或 NumPy 数组，轴标签应该会被正确格式化。限制见下文。

选项

按字母顺序排列：

• color - 以彩色绘制系列。绘制单个系列时默认为 False，绘制多个系列时默认为 True。也接受字符串列表，用于修改默认顺序 ["blue", "magenta", "green", "yellow", "cyan", "red"]。
• force_ascii - 强制仅使用 ASCII 字符绘图。这在兼容性方面很有用，例如在不支持 Unicode 的 CI/CD 系统中使用 uniplot 时。默认为 False。
• force_ascii_characters - 在 force_ascii 模式下使用的字符列表。默认为 ["+", "x", "o", "*", "~", "."]。
• height - 绘图区域的高度，以字符为单位。默认为 17。
• interactive - 启用交互模式。默认为 False。
• legend_labels - 系列的标签。可以是 None 或字符串列表。默认为 None。
• lines - 在点之间启用线条。可以是 True 或 False，或者是用于绘制多个系列的这些值的列表。默认为 False。
• line_length_hard_cap - 强制限制绘图区域每行的最大字符数。如果空间不足，这可能会覆盖 width 选项。默认为 None。
• title - 图表标题。默认为 None。
• width - 绘图区域的宽度，以字符为单位。默认为 60。注意，如果使用了 line_length_hard_cap 选项且空间不足，实际宽度可能会更小。
• x_as_log - 将 x 轴绘制为对数刻度。默认为 False。
• x_gridlines - 用于更好定位的垂直线的 x 值列表。默认为 [0]，如果启用了 x_as_log，则默认为 []。
• x_max - 视图的最大 x 值。默认为显示所有数据点的值。
• x_min - 视图的最小 x 值。默认为显示所有数据点的值。
• x_unit - x 轴的单位。这是一个附加到轴标签的字符串。默认为 ""。
• y_as_log - 将 y 轴绘制为对数刻度。默认为 False。
• y_gridlines - 用于更好定位的水平线的 y 值列表。默认为 [0]，如果启用了 y_as_log，则默认为 []。
• y_max - 视图的最大 y 值。默认为显示所有数据点的值。
• y_min - 视图的最小 y 值。默认为显示所有数据点的值。
• y_unit - y 轴的单位。这是一个附加到轴标签的字符串。默认为 ""。

更改默认参数

uniplot 不存储配置参数的状态。但是，你可以通过定义一个 partial 来创建一个具有新默认值的绘图函数。请看以下示例：

from functools import partial
from uniplot import plot as default_plot
plot = partial(default_plot, height=25, width=80)

这定义了一个新的plot函数，与原始函数完全相同，只是width和height的默认值现在不同。

实验性功能

绘制直方图

为了方便，还有一个histogram函数，它接受一个或多个数列并绘制类似条形图的直方图。它会自动将数列离散化为由bins选项指定的若干个区间，并显示结果。

其他选项按字母顺序排列：

• bins - 使用的区间数。默认为20。
• bins_min - 第一个区间的下限。默认为数列的最小值。
• bins_max - 最后一个区间的上限。默认为数列的最大值。

调用histogram函数时，lines选项默认为True。

示例：

import numpy as np
x = np.sin(np.linspace(1, 1000))
from uniplot import histogram
histogram(x)

结果：

┌────────────────────────────────────────────────────────────┐
│   ▛▀▀▌                       │                   ▐▀▀▜      │ 5
│   ▌  ▌                       │                   ▐  ▐      │
│   ▌  ▌                       │                   ▐  ▐      │
│   ▌  ▀▀▀▌                    │                ▐▀▀▀  ▝▀▀▜   │
│   ▌     ▌                    │                ▐        ▐   │
│   ▌     ▌                    │                ▐        ▐   │
│   ▌     ▙▄▄▄▄▄▖              │          ▗▄▄▄  ▐        ▐   │
│   ▌           ▌              │          ▐  ▐  ▐        ▐   │
│   ▌           ▌              │          ▐  ▐  ▐        ▐   │
│   ▌           ▌              │          ▐  ▐  ▐        ▐   │
│   ▌           ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▜  ▐▀▀▀  ▝▀▀▀        ▐   │
│   ▌                          │    ▐  ▐                 ▐   │
│   ▌                          │    ▐  ▐                 ▐   │
│   ▌                          │    ▐▄▄▟                 ▐   │
│   ▌                          │                         ▐   │
│   ▌                          │                         ▐   │
│▄▄▄▌▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁│▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▐▄▄▄│ 0
└────────────────────────────────────────────────────────────┘
     -1                        0                       1

绘制时间序列

目前初步支持使用时间戳作为轴标签。它应该适用于大多数格式。

目前还缺少更美观的时间戳轴标签，以及时区支持。

示例：

import numpy as np
dates =  np.arange('2024-02-17T12:10', 4*60, 60, dtype='M8[m]')
from uniplot import plot
plot(xs=dates, ys=[1,2,3,2])

结果：

┌────────────────────────────────────────────────────────────┐
│                                       ▝                    │ 3
│                                                            │
│                                                            │
│                                                            │
│                                                            │
│                                                            │
│                                                            │
│                                                            │
│                    ▘                                      ▝│ 2
│                                                            │
│                                                            │
│                                                            │
│                                                            │
│                                                            │
│                                                            │
│                                                            │
│▖                                                           │ 1
└────────────────────────────────────────────────────────────┘
               13:00               14:00               15:00

安装

通过pip安装：

pip install uniplot

贡献

克隆此仓库，并通过poetry install安装依赖。

你可以通过poetry run ./run_tests运行测试，确保你的设置正确。然后按常规方式处理问题、提交PR等。