cAutoRangeHistogramStrategy Class Reference¶

A generic, very configurable histogram strategy that is meant to provide a good quality histogram for practical distributions, and creates uniform bins. This strategy uses precollection to gather input information about the distribution before setting up the bins.

Several parameters and constraints can be specified for setting up the bins: range lower and/or upper endpoint, bin size, number of bins, mode (integers or reals), and whether bin size rounding is to be used. If bin size rounding is turned on, a bin size of the form {1|2|5}*10^n is chosen, i.e. a power of ten, or two or five times a power of ten. When both endpoints of the range are left unspecified, the histogram range is derived by taking the range of the precollected observations and extending it symmetrically by a range extension factor. If one of the endpoints is specified by the user, that value is used instead of the computed one. The number of observations to precollect as well as the range extension factor can be configured. If the histogram mode (integers vs. reals) is left unspecified, it will be determined by examining the precollected values. In integers mode, bin edges will be whole numbers. If the histogram range and mode are all specified by the user, the precollection phase is skipped.

If there are inconsistent or conflicting settings, e.g. an explicitly given histogram range is not multiple of the bin size in integers mode, the bin setup algorithm will do "best effort" to set up the histogram instead of stopping with an exception.

This histogram strategy can auto-extend the histogram range by adding new bins at either end. One can also set up an upper limit to the number of histogram bins to prevent it from growing indefinitely. Bin merging can also be enabled: it will cause every two (or N) adjacent bins to be merged to reduce the number of bins if their number grows too high.

Collected infinities are counted as underflows/overflows, and they do not affect the histogram layout in any way.