Summary
Add figure.hist() for plotting frequency distributions from raw sample data, matching matplotlib's plt.hist().
Motivation
Histograms are the standard first step when analysing latency distributions from benchmark runs. The user passes raw measurement samples and the library handles binning automatically.
Proposed API
std::vector<double> latencies = /* ... benchmark samples ... */;
figure.hist(latencies.data(), latencies.size())
.bins(50) // number of bins (default: auto)
.range(0.0, 200.0) // optional clamp range
.color(sepia::Color{100, 200, 120})
.alpha(0.75)
.label("latency distribution (ns)");
Auto bin count should default to Sturges' rule: ceil(log2(n) + 1).
Implementation Notes
- Add
HistEntry (or tag PlotEntry with a kHistogram type)
- Binning logic: compute
[min, max] of data (or use user range), divide into k equal-width bins, count samples per bin — O(n) pass
- Rendering: call
canvas.fill_rect() + canvas.draw_rect() (outline) for each bin, similar to bar()
- Normalized mode (
density=true): divide counts by n * bin_width to get probability density
- Stacked histograms: multiple
hist() calls with alpha < 1 already work via existing alpha-blending
Acceptance Criteria
Summary
Add
figure.hist()for plotting frequency distributions from raw sample data, matching matplotlib'splt.hist().Motivation
Histograms are the standard first step when analysing latency distributions from benchmark runs. The user passes raw measurement samples and the library handles binning automatically.
Proposed API
Auto bin count should default to Sturges' rule:
ceil(log2(n) + 1).Implementation Notes
HistEntry(or tagPlotEntrywith akHistogramtype)[min, max]of data (or use user range), divide intokequal-width bins, count samples per bin — O(n) passcanvas.fill_rect()+canvas.draw_rect()(outline) for each bin, similar tobar()density=true): divide counts byn * bin_widthto get probability densityhist()calls with alpha < 1 already work via existing alpha-blendingAcceptance Criteria
range()clampdensity(true)normalizationexamples/histogram.cppwith synthetic latency samples