nordisk/facett

Charting (plot + plotters + pop progress) — for idiots

Class: idiot. Every step, nothing assumed. Goal: build the chart crates, see their tests go green, and look at the charts running in the demo app. If you already know Rust, read plot-guide.md instead — this one spells out every keystroke.

What you need first

• A terminal (the black window where you type commands).
• The facett repo on disk. In the terminal, type this and press Enter:

cd /run/media/rickard/T9/git/facett

f0 — zero to green, the whole thing

There are three crates: facett-plot (line/bar charts), facett-plotters (box plot, violin, heatmap, treemap, candlesticks), and facett-pop (labelled progress bars). You will build and test all three, then look at each one drawn for real inside the demo app.

Step 1 — build all three

Type each line and press Enter after each one:

cargo build -p facett-plot
cargo build -p facett-plotters
cargo build -p facett-pop

Wait for each to finish. If you see red text, read what it names and fix it before moving on — usually a typo in code you were editing.

Step 2 — run the tests

Type each and press Enter:

cargo test -p facett-plot
cargo test -p facett-plotters
cargo test -p facett-pop

You should see test result: ok at the bottom of each. That's dozens of tests checking the math (percentiles, KDE curves, treemap tiling) and the click-behaviour (hover, zoom, progress) — all without opening a single window.

Step 3 — see them drawn for real

Type and press Enter:

cargo run -p facett-demo

This opens the showcase app. Along the left/top is a list of tabs — one per component. Click these seven, one at a time:

• pop — rows of progress bars, one per shipping region, each showing a done / total.
• plot — a line chart of fake throughput numbers. Try dragging inside it to pan, or scrolling to zoom — a "⤢ Fit" button appears once you do; click it to snap back.
• boxplot — one box-and-whiskers per team, showing their score spread.
• violin — the same score data as smooth "violin" density shapes instead of boxes.
• heatmap — a region × status grid, coloured by count, with a gradient legend on the right.
• treemap — rectangles sized by tonnage, one per region.
• candles — a candlestick (open/high/low/close) price chart.

Hover your mouse over any bar/box/candle/tile/cell — a small tooltip pops up with the exact numbers. Close the window (or Ctrl+C in the terminal) when you're done looking.

f1 — PlotView (the plot tab), every step

1. Open facett-plot/src/lib.rs in your editor.
2. Find pub struct PlotView near the top of the file's structs — this is the whole thing: a title, and a state (what kind of chart, the data series, the zoom, which series are hidden).
3. Every way the chart changes is one of the Msg variants just above it — SetKind, SetViewport, ResetViewport, ToggleSeries, ShowAllSeries. Read them; that list is the complete set of things a user (or a robot) can do to this chart.
4. To make your own line chart, in any Rust file write:

let plot = facett_plot::PlotView::line("my chart", vec![
    ("series one".into(), vec![(0.0, 1.0), (1.0, 3.0), (2.0, 2.0)]),
]);

PlotView::bars(...) instead of ::line(...) gives you a bar chart of the same shape.

f2 — the plotters charts (boxplot/violin/heatmap/treemap/candles), every step

1. Open facett-plotters/src/lib.rs. It lists five modules — boxplot, violin, heatmap, treemap, candlestick — one file each, same folder.
2. Pick one, e.g. facett-plotters/src/boxplot.rs, and open it.
3. Find pub struct BoxPlotView — title, the raw groups (name + numbers), and a state that only ever remembers which box the mouse is hovering.
4. To build one yourself:

let bp = facett_plotters::BoxPlotView::new("scores", vec![
    ("team a".into(), vec![62.0, 71.0, 88.0, 91.0]),
    ("team b".into(), vec![70.0, 74.0, 76.0, 80.0]),
]);

1. The other four charts are built the same way, just with different data shapes — check the top of each file's new(...) function for what it wants (a matrix of numbers for HeatmapView, (open, high, low, close) tuples for CandlestickView, weighted labels for TreemapView, groups of numbers for ViolinView).

f3 — ProgressView (the pop tab), every step

1. Open facett-pop/src/lib.rs. Find pub struct ProgressView — a title, a phase label, and a list of items (label, done, total).
2. Find the Msg enum just above it: SetPhase, SetItems, Upsert, Advance, Remove, Clear. This is the entire vocabulary a loading screen uses to report progress.
3. To build and drive one yourself, write:

let mut pop = facett_pop::ProgressView::new("ingest");
pop.update(facett_pop::Msg::SetPhase("loading".into()));
pop.update(facett_pop::Msg::Upsert { label: "Person".into(), done: 0, total: 100 });
pop.update(facett_pop::Msg::Advance { label: "Person".into(), delta: 40 });

1. Run and check pop.is_idle() — it comes back false here (40 out of 100 is not done yet). Add another Advance { delta: 60 } and it flips to true.

Step — save your work

If you changed any of these files, save your work the same way as any other facett change. Type these three, pressing Enter after each:

git add -A
git commit -m "facett-plot/plotters/pop: <describe your change>"
git push

A name mix-up worth knowing

There is an older, unrelated pair of docs in this folder — population-graph.md and population-graph-for-dummies.md — about a completely different thing: the Sverige tab in facett-demo, a graph-visualisation showcase of Sweden's synthetic population built on knut-popsim + facett-graphview. It has nothing to do with facett-pop's progress bars despite the similar-sounding name — don't confuse the two. This file (plot-for-idiots.md) is the one for the pop/plot/boxplot/violin/heatmap/treemap/candles tabs; the Sverige tab's own docs are unchanged.