kuva 0.1.4

Scientific plotting library in Rust with various backends.
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

# kuva

[![CI](https://github.com/Psy-Fer/kuva/actions/workflows/ci.yml/badge.svg)](https://github.com/Psy-Fer/kuva/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![crates.io](https://img.shields.io/crates/v/kuva.svg)](https://crates.io/crates/kuva)
[![docs.rs](https://docs.rs/kuva/badge.svg)](https://docs.rs/kuva)
[![Downloads](https://img.shields.io/crates/d/kuva.svg)](https://crates.io/crates/kuva)

A scientific plotting library in Rust. 29 plot types, SVG output, optional PNG/PDF backends, and a CLI binary that renders plots directly from the shell — including in the terminal itself.

![All 27 plot types](docs/src/assets/overview/all_plots_complex.svg)

![kuva terminal — Sankey diagram](docs/src/assets/terminal/sankey.gif)

---

## Quick start

### Install the CLI

```bash
# From crates.io
cargo install kuva --features cli

# From source (SVG only)
cargo build --release --bin kuva --features cli

# From source (all backends)
cargo build --release --bin kuva --features cli,full
```

### Use as a library

Add to `Cargo.toml`:

```toml
[dependencies]
kuva = "0.1"

# Optional backends
kuva = { version = "0.1", features = ["png"] }   # PNG output
kuva = { version = "0.1", features = ["pdf"] }   # PDF output
kuva = { version = "0.1", features = ["full"] }  # PNG + PDF
```

Then in Rust:

```rust
use kuva::prelude::*;

let plot = ScatterPlot::new()
    .with_data(vec![(1.0_f64, 2.0), (3.0, 5.0), (5.0, 4.0)])
    .with_color("steelblue")
    .with_legend("samples");

let plots: Vec<Plot> = vec![plot.into()];
let layout = Layout::auto_from_plots(&plots)
    .with_title("My Plot")
    .with_x_label("X")
    .with_y_label("Y");

let svg = render_to_svg(plots, layout);
std::fs::write("my_plot.svg", svg).unwrap();
```

### Use the CLI

```bash
# Scatter plot to SVG
kuva scatter data.tsv --x x --y y -o plot.svg

# Volcano plot, label top 20 genes
kuva volcano gene_stats.tsv --name-col gene --x-col log2fc --y-col pvalue --top-n 20

# Ridgeline plot — stacked density curves, one per group
kuva ridgeline samples.tsv --group-by group --value expression --overlap 0.6

# Box plot rendered directly in the terminal
kuva box samples.tsv --group-col group --value-col expression --terminal
```

Input is auto-detected TSV or CSV. Columns are selectable by name or 0-based index. Pipe from stdin by omitting the file argument. Output defaults to SVG on stdout; use `-o file.svg/png/pdf` to write a file.

---

## Documentation

Full documentation — plot type reference, API guide, CLI flag reference, themes, palettes, and benchmarks — is at **[psy-fer.github.io/kuva](https://psy-fer.github.io/kuva)**.

---

## Development note

kuva was initially built by hand, with a working library and several plot types
already in place before AI tooling was introduced. From that point, development was
heavily assisted by Claude (Anthropic) — accelerating the addition of new plot types,
the CLI binary, tests, and documentation. The architecture, domain knowledge, and
direction remain the author's own; Claude was used as an accelerant, not an author.

*This disclaimer was written by Claude as an honest assessment of its own role in the project.*

## License

MIT