kuva 0.1.0

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
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

# Band Plot

A band plot fills the region between two y-curves over a shared x-axis. It is used to display **confidence intervals**, prediction bands, IQR envelopes, or any shaded range around a central estimate.

**Import path:** `kuva::plot::BandPlot`

---

## Standalone band

`BandPlot::new(x, y_lower, y_upper)` creates a filled area independently. Pair it with a `LinePlot` or `ScatterPlot` by placing both in the same `plots` vector — the band is drawn behind the line.

```rust,no_run
use kuva::plot::{BandPlot, LinePlot};
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let x: Vec<f64> = (0..60).map(|i| i as f64 * 0.2).collect();
let y: Vec<f64> = x.iter().map(|&v| v.sin()).collect();
let lower: Vec<f64> = y.iter().map(|&v| v - 0.35).collect();
let upper: Vec<f64> = y.iter().map(|&v| v + 0.35).collect();

let band = BandPlot::new(x.clone(), lower, upper)
    .with_color("steelblue")
    .with_opacity(0.25);

let line = LinePlot::new()
    .with_data(x.iter().copied().zip(y.iter().copied()))
    .with_color("steelblue");

// Band must come before the line so it renders behind it
let plots = vec![Plot::Band(band), Plot::Line(line)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Band Plot — Standalone")
    .with_x_label("x")
    .with_y_label("y");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
std::fs::write("band.svg", svg).unwrap();
```

<img src="../assets/band/standalone.svg" alt="Standalone band paired with a line" width="560">

The band fills between `y_lower` and `y_upper`. Placing `Plot::Band` before `Plot::Line` in the vector ensures it is drawn first and appears behind the line.

---

## Band attached to a line

`LinePlot::with_band(y_lower, y_upper)` is a one-call shorthand. It creates the `BandPlot` internally, using the line's x positions and inheriting its color automatically.

```rust,no_run
use kuva::plot::LinePlot;
# use kuva::render::plots::Plot;

let line = LinePlot::new()
    .with_data(x.iter().copied().zip(y.iter().copied()))
    .with_color("firebrick")
    .with_band(lower, upper);  // band color = "firebrick", opacity = 0.2

let plots = vec![Plot::Line(line)];
```

<img src="../assets/band/attached_line.svg" alt="Band attached to a line — damped cosine with confidence envelope" width="560">

The band is always rendered behind the line. No ordering in the `plots` vector is needed.

---

## Band attached to a scatter plot

`ScatterPlot::with_band(y_lower, y_upper)` works identically: the band inherits the scatter color and renders behind the points.

```rust,no_run
use kuva::plot::ScatterPlot;
# use kuva::render::plots::Plot;

let scatter = ScatterPlot::new()
    .with_data(x.iter().copied().zip(y.iter().copied()))
    .with_color("seagreen")
    .with_band(lower, upper);

let plots = vec![Plot::Scatter(scatter)];
```

<img src="../assets/band/attached_scatter.svg" alt="Band attached to a scatter plot — linear trend with prediction band" width="560">

---

## Multiple series with bands

Each `LinePlot` carries its own independent band. Combine all series in one `plots` vector — they share the same axes automatically.

```rust,no_run
use kuva::plot::LinePlot;
# use kuva::render::plots::Plot;

let line1 = LinePlot::new()
    .with_data(x.iter().copied().zip(y1.iter().copied()))
    .with_color("steelblue")
    .with_band(y1.iter().map(|&v| v - 0.25), y1.iter().map(|&v| v + 0.25))
    .with_legend("sin(x)");

let line2 = LinePlot::new()
    .with_data(x.iter().copied().zip(y2.iter().copied()))
    .with_color("darkorange")
    .with_band(y2.iter().map(|&v| v - 0.25), y2.iter().map(|&v| v + 0.25))
    .with_legend("0.8 · cos(0.5x)");

let plots = vec![Plot::Line(line1), Plot::Line(line2)];
```

<img src="../assets/band/multi.svg" alt="Two series each with their own confidence band" width="560">

---

## Opacity

`.with_opacity(f)` sets the fill transparency. The default `0.2` is deliberately light so that overlapping bands and the underlying line remain readable.

| Opacity | Effect |
|---------|--------|
| `0.1`–`0.2` | Light; line and overlapping bands visible **(default `0.2`)** |
| `0.3`–`0.5` | Moderate; band is prominent |
| `1.0` | Fully opaque; hides anything behind it |

---

## API reference

| Method | Description |
|--------|-------------|
| `BandPlot::new(x, y_lower, y_upper)` | Create a standalone band from three parallel iterables |
| `.with_color(s)` | Fill color (default `"steelblue"`) |
| `.with_opacity(f)` | Fill opacity in `[0.0, 1.0]` (default `0.2`) |
| `.with_legend(s)` | Add a legend entry |
| `LinePlot::with_band(lower, upper)` | Attach a band to a line (inherits color) |
| `ScatterPlot::with_band(lower, upper)` | Attach a band to a scatter plot (inherits color) |