ADR 0029: Histograms store their bins and how they were made¶

Status: Accepted

Context¶

A histogram counts a sample into bins. The sample may be very large, and a reader of the figure wants to know the count and density of each bin and how the bins were chosen.

Decision¶

A histogram is binned when the figure is built, not when it is drawn. The figure stores the binned values on the bars, stairs or cells that draw them. With them it stores a record of how the bins were made: the bin specification, the resolved bin edges, the range, the normalisation, the number of samples counted and the number excluded. A datatip can then report the count and density of a bin without the sample, taking the width of the bin from the resolved edges rather than from what is drawn, which for a member of a grouped histogram is only part of the bin.

Alternatives considered¶

Storing the sample¶

Storing the raw sample would let the viewer rebin, but it would make the figure as large as the sample and put statistics into the model and the scene compiler.

Storing only the binned values¶

Storing only the binned values would keep the figure smallest. But a datatip could then report neither counts nor densities, and nothing would record how the bins were chosen.