charton 0.5.1

A high-performance, layered charting system for Rust, featuring a flexible data core and multi-backend rendering.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169

[English](./README.md) | [简体中文](./README_zh.md)

# Charton - 一个多功能的 Rust 绘图库

**Rust 版 Altair 风格声明式绘图。高性能、Polars 原生支持、且兼容 Wasm。**
> *“非常棒的项目。... 作为一个生态系统运行得非常完美。”*
> — [**Ritchie Vink**](https://github.com/pola-rs/polars/issues/25941), Polars 创始人

[![Crates.io](https://img.shields.io/crates/v/charton.svg)](https://crates.io/crates/charton)
[![Documentation](https://docs.rs/charton/badge.svg)](https://docs.rs/charton)
[![Build Status](https://github.com/wangjiawen2013/charton/actions/workflows/ci.yml/badge.svg)](https://github.com/wangjiawen2013/charton/actions)
[![License](https://img.shields.io/badge/license-Apache2.0-blue.svg)](LICENSE)

**Charton** 是一款高性能 Rust 绘图库，其声明式 API 灵感源自 [Altair](https://altair-viz.github.io/)。它提供原生 [Polars](https://github.com/pola-rs/polars) 支持，并填补了 Rust 与 Python 可视化生态系统（Altair/Matplotlib）之间的空白。通过与 evcxr_jupyter 集成，还可以在 Notebook 中实现交互式数据探索。

<table>
    <tr>
        <td><img src="docs/src/images/altair.svg" alt="Altair" /><p align="center">Altair</p></td>
        <td><img src="docs/src/images/matplotlib.png" alt="Matplotlib" /><p align="center">Matplotlib</p></td>
        <td><img src="docs/src/images/stacked_bar.svg" alt="Stacked Bar Chart" /><p align="center">Stacked Bar Chart</p></td>
        <td><img src="docs/src/images/grouped_bar_with_errorbar_2.svg" alt="Grouped Bar Chart with Errorbar" /><p align="center">Grouped Bar With Errorbar</p></td>
        <td><img src="docs/src/images/density.svg" alt="Density" /><p align="center">Density</p></td>
    </tr>
    <tr>
        <td><img src="docs/src/images/histogram.svg" alt="Histogram" /><p align="center">Histogram</p></td>
        <td><img src="docs/src/images/2d_density.svg" alt="2d Density" /><p align="center">2d Density Chart</p></td>
        <td><img src="docs/src/images/heatmap.svg" alt="Heatmap" /><p align="center">Heatmap</p></td>
        <td><img src="docs/src/images/grouped_boxplot.svg" alt="Grouped Boxplot" /><p align="center">Grouped Boxplot</p></td>
        <td><img src="docs/src/images/cumulative_frequency.svg" alt="Cumulative Frequency" /><p align="center">Cumulative Frequency</p></td>
    </tr>
    <tr>
        <td><img src="docs/src/images/distribution.svg" alt="Distribution" /><p align="center">Distribution</p></td>
        <td><img src="docs/src/images/pie.svg" alt="Pie" /><p align="center">Pie</p></td>
        <td><img src="docs/src/images/donut.svg" alt="Donut" /><p align="center">Donut</p></td>
        <td><img src="docs/src/images/rose.svg" alt="Rose" /><p align="center">Rose</p></td>
        <td><img src="docs/src/images/nightingale.svg" alt="Nightingale" /><p align="center">Nightingale</p></td>
    </tr>
    <tr>
        <td><img src="docs/src/images/simple_stacked_area.svg" alt="Simple Stacked Area" /><p align="center">Simple Stack Area</p></td>
        <td><img src="docs/src/images/normalized_stacked_area.svg" alt="Normalized Stacked Area" /><p align="center">Normalized Stacked Area</p></td>
        <td><img src="docs/src/images/steamgraph.svg" alt="Steamgraph" /><p align="center">Steamgraph</p></td>
        <td><img src="docs/src/images/rule.svg" alt="Rule" /><p align="center">Rule</p></td>
        <td><img src="docs/src/images/strip.svg" alt="Strip" /><p align="center">Strip</p></td>
    </tr>
</table>

## 安装

在 `Cargo.toml` 中添加：

```toml
[dependencies]
charton = "0.5"                                         # 标准版 (默认开启并行计算)
charton = { version = "0.5", default-features = false } # 用于 WASM / 单线程环境
charton = { version = "0.5", features = ["resvg"] }     # 支持导出 PNG
charton = { version = "0.5", features = ["bridge"] }    # 支持 Altair/Matplotlib 互操作
```

## 快速上手

Charton 提供了高级声明式 API。通过一行代码就可以实现可视化：

```rust
use charton::prelude::*;

// 数据：身体指标（身高 vs. 体重）
let height = vec![160.0, 165.0, 170.0, 175.0, 180.0];
let weight = vec![55.0, 62.0, 68.0, 75.0, 82.0];

// 一行代码绘图
chart!(height, weight)?.mark_point()?.encode((alt::x("height"), alt::y("weight")))?.save("out.svg")?;
```

## 从宏到生产级 API

虽然 `chart!` 宏在快速原型设计和书写简单脚本时非常方便，但在需要显式处理数据的生产环境中，建议使用底层的 `Chart::build` API。

### 1. 专业构建 API

对于复杂的应用程序，使用 `Chart::build` 可以完全控制 `Dataset` 的生命周期。

```rust
let ds = Dataset::new()
    .with_column("height", height)?
    .with_column("weight", weight)?;

Chart::build(ds)? // 等价于 chart!(ds)?
    .mark_point()?
    .encode((alt::x("height"), alt::y("weight")))?
    .save("out.svg")?;
```

> **提示**：如果需要在循环或条件逻辑中动态添加列，请使用 `add_column`。

### 2. Polars 集成

针对 Polars 用户，Charton 提供了 `load_polars_df!` 宏，可将 `DataFrame` 转换为 Charton 内部专用的 `Dataset`。

```rust
use polars::prelude::*;

let df = df![
    "height" => vec![160.0, 165.0, 170.0, 175.0, 180.0],
    "weight" => vec![55.0, 62.0, 68.0, 75.0, 82.0]
]?;

// 将 Polars DataFrame 转换为 Charton Dataset
let ds = load_polars_df!(df)?;

Chart::build(ds)? // 等价于 chart!(ds)?
    .mark_point()?
    .encode((alt::x("height"), alt::y("weight")))?
    .save("out.svg")?;
```

**兼容性说明**: 由于 Polars API 变化频繁，Charton 使用带版本标记的宏来处理兼容性。不再支持 0.42 以下的版本。

|Polars 版本          |使用的宏                   |状态          |
|:--------------------|:-------------------------|:-------------|
|0.53+                |`load_polars_df!(df)?`    |最新（标准）   |
|0.42 - 0.52          |`load_polars_v42_52!(df)?`|旧版支持       |
|< 0.42               |N/A                       |不支持        |

## 分层语法

受图形语法（如 `ggplot2` 和 `Altair`）影响，Charton 用模块化的图层系统取代了固定模板。通过组合原子标记（Marks）能构建出丰富的图表类型，极大的提高了作图灵活性。

```rust
// 创建独立图层
let line = chart!(height, weight)?
    .mark_line()?
    .encode((alt::x("height"), alt::y("weight")))?;

let point = chart!(height, weight)?
    .mark_point()?
    .encode((alt::x("height"), alt::y("weight")))?;

// 组合成复合图表
line.and(point).save("layered.svg")?;
```

## 交互式作图 (Jupyter)

Charton 与 evcxr_jupyter 集成，支持交互式数据探索。将 `.save()` 替换为 `.show()` 即可直接在 jupyter notebook 单元格中显示 SVG：

![evcxr jupyter](assets/evcxr_jupyter.png)

## WebAssembly 与前端

Charton 支持 WebAssembly 和现代 Web 前端；详情请参考 [Charton Docs](https://wangjiawen2013.github.io/charton)。

## 利用第三方可视化生态

Charton 通过高速 IPC 将 Rust 与成熟的可视化生态（如 **Altair** 和 **Matplotlib**）连接起来，使用户能够在统一的工作流中利用多样化、专业级的绘图工具。详情请参考 [Charton Docs](https://wangjiawen2013.github.io/charton)。

## 原生图层同步

Charton 基于**单一事实来源**处理标度映射，能组合不同来源的数据，并保持所有图表元素与坐标轴的逻辑一致性。

![Comparison](assets/comparison.png)

*该图展示了 Charton 中的语义同步。来自不同数据源的点集与条形图被锚定在统一的标度体系下，确保了数据与色彩、空间位置映射关系的精准对齐。*

## 出版级质量

Charton 作图精准，提供对复杂标记的像素级控制。无论是用于生物医学研究的多层误差线（ErrorBar），还是用于金融领域的高密度散点图，Charton 都能提供顶尖期刊所需的审美严谨性。

<table>
    <tr>
        <td><img src="docs/src/images/weight_loss_curve_NEJM.png" alt="NEJM" /><p align="center">NEJM</p></td>
        <td><img src="docs/src/images/weight_loss_curve.svg" alt="Charton" /><p align="center">Charton</p></td>
    </tr>
</table>

*使用 Charton 复现了 2021 年新英格兰医学杂志上发表的使用减肥药司美格鲁肽进行体重管理的研究论文中的图 1A。*

## 文档

请访问 [Charton Docs](https://wangjiawen2013.github.io/charton) 查看完整文档。

## License

Charton 基于 **Apache License 2.0** 许可证开源。