Skip to content

Add histogram support (figure.hist()) #5

Description

@MoonFlowww

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

  • Auto bin count via Sturges' rule
  • User-supplied bin count
  • Optional range() clamp
  • Optional density(true) normalization
  • Multiple overlapping histograms with alpha blending work
  • Example: examples/histogram.cpp with synthetic latency samples

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions