kuva 0.1.6

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

//! Waterfall plot documentation examples.
//!
//! Generates canonical SVG outputs used in the kuva documentation.
//! Run with:
//!
//! ```bash
//! cargo run --example waterfall
//! ```
//!
//! SVGs are written to `docs/src/assets/waterfall/`.

use kuva::plot::WaterfallPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

const OUT: &str = "docs/src/assets/waterfall";

fn main() {
    std::fs::create_dir_all(OUT).expect("could not create docs/src/assets/waterfall");

    basic();
    totals();
    connectors_values();
    difference();

    println!("Waterfall SVGs written to {OUT}/");
}

/// Classic delta-only waterfall — a running total that rises and falls.
fn basic() {
    let wf = WaterfallPlot::new()
        .with_delta("Revenue",        850.0)
        .with_delta("Cost of goods", -340.0)
        .with_delta("Personnel",     -180.0)
        .with_delta("Operations",     -90.0)
        .with_delta("Marketing",      -70.0)
        .with_delta("Other income",    55.0)
        .with_delta("Tax",            -85.0);

    let plots = vec![Plot::Waterfall(wf)];
    let layout = Layout::auto_from_plots(&plots)
        .with_title("Revenue Breakdown")
        .with_y_label("USD (thousands)");

    let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
    std::fs::write(format!("{OUT}/basic.svg"), svg).unwrap();
}

/// Waterfall with intermediate totals — the classic income-statement layout.
///
/// Each `with_total()` bar drops to zero and shows the accumulated running
/// total at that point, making subtotals visible alongside the individual items.
fn totals() {
    let wf = WaterfallPlot::new()
        .with_delta("Revenue",       850.0)
        .with_delta("Cost of goods",-340.0)
        .with_total("Gross profit")
        .with_delta("Personnel",    -180.0)
        .with_delta("Operations",    -90.0)
        .with_delta("Marketing",     -70.0)
        .with_total("EBITDA")
        .with_delta("Depreciation",  -40.0)
        .with_delta("Interest",      -20.0)
        .with_delta("Tax",           -65.0)
        .with_total("Net income");

    let plots = vec![Plot::Waterfall(wf)];
    let layout = Layout::auto_from_plots(&plots)
        .with_title("Income Statement")
        .with_y_label("USD (thousands)");

    let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
    std::fs::write(format!("{OUT}/totals.svg"), svg).unwrap();
}

/// Connectors and value labels — dashed lines link bar tops, values annotate bars.
fn connectors_values() {
    let wf = WaterfallPlot::new()
        .with_delta("Q1 sales",    420.0)
        .with_delta("Q2 sales",    380.0)
        .with_delta("Returns",    -95.0)
        .with_delta("Discounts",  -60.0)
        .with_total("H1 net")
        .with_delta("Q3 sales",   410.0)
        .with_delta("Q4 sales",   455.0)
        .with_delta("Returns",   -105.0)
        .with_delta("Discounts",  -70.0)
        .with_total("H2 net")
        .with_connectors()
        .with_values();

    let plots = vec![Plot::Waterfall(wf)];
    let layout = Layout::auto_from_plots(&plots)
        .with_title("Sales – Connectors + Values")
        .with_y_label("USD (thousands)");

    let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
    std::fs::write(format!("{OUT}/connectors_values.svg"), svg).unwrap();
}

/// Difference bars — anchored at explicit [from, to] values, independent of
/// the running total.
///
/// The clearest use is when `from` and `to` match the heights of existing
/// Total bars so the reader can trace the connection directly.
/// Here both period totals are 320 and 730 respectively — the difference bar
/// sits exactly between those two reference levels and shows the +410 gain.
fn difference() {
    let wf = WaterfallPlot::new()
        .with_delta("Revenue",   500.0)   // RT = 500
        .with_delta("Costs",    -180.0)   // RT = 320
        .with_total("Period A")           // total bar: 0 → 320
        .with_delta("Revenue",   600.0)   // RT = 920
        .with_delta("Costs",    -190.0)   // RT = 730
        .with_total("Period B")           // total bar: 0 → 730
        // from = Period A total (320), to = Period B total (730)
        .with_difference("Period A→B", 320.0, 730.0)
        .with_values();

    let plots = vec![Plot::Waterfall(wf)];
    let layout = Layout::auto_from_plots(&plots)
        .with_title("Period-over-Period Change")
        .with_y_label("USD (thousands)");

    let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
    std::fs::write(format!("{OUT}/difference.svg"), svg).unwrap();
}