Vega-Lite V4 for Rust
A Rust API for Vega-Lite V4 to build chart with a rusty API.
Similar to the Altair project in python, this crate build upon Vega-Lite specifications. Vega-Lite is a high-level grammar of interactive graphics. It provides a concise JSON syntax for rapidly generating visualizations to support analysis. Vega-Lite specifications can be compiled to Vega specifications. Those specifications are then parsed by Vega’s JavaScript runtime to generate both static images or interactive web-based views. This crate has a complete mapping of Vega-Lite 3.4 specification and can be found in src/schema.rs. With all the types and structs, it's possible to create your Rust Vegalite graph that will be serialize into a Vega-Lite JSON. Thanks to Showata the resulting visualization can be display in your Web-Browser or in a Rust Jupyter Notebook. It's also possible to use an existing Vega-Lite json and plug your data source seamlessly. This way you can leverage existing vizualisation and adapt it to your design.
Examples
In order to have a complete mapping of the Vega-Lite V4 specification the code for the schema was automaticlly generated. To help describe all the possible features a gallery of example is provided on github
To launch all examples
cargo install cargo-make
cargo make run-all-examples
Simple chart using ndarray generated data
let values: Array2<f64> = Array::random((100, 2), StandardNormal);
let chart = VegaliteBuilder::default()
.title("Random points")
.data(values)
.mark(Mark::Point)
.encoding(
EncodingBuilder::default()
.x(XClassBuilder::default()
.field("data.0")
.def_type(StandardType::Quantitative)
.build()?)
.y(YClassBuilder::default()
.field("data.1")
.def_type(StandardType::Quantitative)
.build()?)
.build()?,
)
.build()?;
chart.show()?;
Simple chart using existing json definition with new data
// Use existing vega-lite json specification
let spec = r##"{
"$schema": "https://vega.github.io/schema/vega-lite/v4.0.json",
"encoding": {
"x": {
"field": "data.0",
"type": "quantitative"
},
"y": {
"field": "data.1",
"type": "quantitative"
}
},
"mark": "point",
"title": "Random points"
}"##;
// Use you own data to populate the chart
let values: Array2<f64> = Array::random((100, 2), StandardNormal);
let mut chart: Vegalite = serde_json::from_str(spec)?;
chart.data = values.into();
// display the chart using `showata`
chart.show()?;
Features
| name | enabled by default | functionnality | related crate |
|---|---|---|---|
| show_vega | yes | can display charts in the browser or in a notebook | showata |
| csv | yes | can load data from a csv | csv |
| ndarray | yes | can load data from a ndarray | ndarray |
| nalgebra | no | can load data from a nalgebra::Matrix | nalgebra |
| rulinalg | no | can load data from a rulinalg::matrix::Matrix | rulinalg |
Links
- Wiki - AGuideToRustGraphicsLibraries2019
- A Dramatic Tour through Python’s Data Visualization Landscape (including ggplot and Altair) – Regress to Impress
- Specifying Data in Altair — Altair 3.0.0 documentation
- Visualization — list of Rust libraries/crates // Lib.rs
- Quicktype (got issue with the alternative) was used to bootstrap
src/schema.rsfrom the vega-lite's json schema
Troubleshoot
Stack size
The vegalite json schema is large with lot of alternative, so the typed rust version create a large set of struct and enum (the generated source file before macro expension is 28K lines). So the size of a model in stack could be large (it's also why Box is used in the struct).
On wasm32, with the default stack size (~ 1 MB), using vegalite_4 can raise error like:
- crash tab with
SIGSEVG(on chromium based browser) Uncaught (in promise) RuntimeError: memory access out of boundsor simplyUncaught (in promise) RuntimeError
The current work arround is to increase the stacksize (eg ~ 1.5 MB). For cargo based project you can add into .cargo/config file of the project:
[target.wasm32-unknown-unknown]
rustflags = [
"-C", "link-args=-z stack-size=1500000",
]
20 Dec 12, 2022
2.3k Jan 2, 2023
417 Dec 31, 2022
671 Jan 8, 2023
2.7k Jan 4, 2023
12 Jan 4, 2023
353 Dec 26, 2022
398 Dec 14, 2022
2 Jul 17, 2022
25 Sep 10, 2022
4 Jan 7, 2022
186 Dec 29, 2022
468 Jan 6, 2023
4 Dec 4, 2022
6 Jan 31, 2022
4 Aug 28, 2022
24 Feb 13, 2023
294 Dec 23, 2022
128 Dec 24, 2022
62 Dec 6, 2022