search

boostorg / histogram

Fast multi-dimensional generalized histogram with convenient interface for C++14
Boost Software License 1.0
318 stars 71 forks source link
boost boost-libraries c-plus-plus c-plus-plus-14 convenient convenient-interface data-analysis header-only histogram statistics

readme

Multi-dimensional generalised histograms with convenient interface

Coded with ❤. Powered by the Boost community and the Scikit-HEP Project.

License

Distributed under the Boost Software License, Version 1.0.

Properties

Supported compiler versions gcc >= 5.5, clang >= 3.8, msvc >= 14.1 Supported C++ versions 14, 17, 20

Branch Linux, OSX, Windows Coverage
develop Fast Coveralls
master Fast Coveralls

Boost.Histogram is a very fast state-of-the-art multi-dimensional generalised histogram class for the beginner and expert alike.

Check out the full documentation.

💡 Boost.Histogram is a mature library with 100 % of code lines covered by unit tests, is benchmarked for performance, and has extensive documentation. If you still find some issue or find the documentation lacking, tell us about it by submitting an issue. Chat with us on the Boost channel on Slack and Gitter.

Code example

The following stripped-down example was taken from the Getting started section in the documentation. Have a look into the docs to see the full version with comments and more examples.

Example: Make and fill a 1d-histogram (try it live on Wandbox). The core of this example compiles into 53 lines of assembly code.

#include <boost/histogram.hpp>
#include <boost/format.hpp> // used here for printing
#include <iostream>

int main() {
    using namespace boost::histogram;

    // make 1d histogram with 4 regular bins from 0 to 2
    auto h = make_histogram( axis::regular<>(4, 0.0, 2.0) );

    // push some values into the histogram
    for (auto&& value : { 0.4, 1.1, 0.3, 1.7, 10. })
      h(value);

    // iterate over bins
    for (auto&& x : indexed(h)) {
      std::cout << boost::format("bin %i [ %.1f, %.1f ): %i\n")
        % x.index() % x.bin().lower() % x.bin().upper() % *x;
    }

    std::cout << std::flush;

    /* program output:

    bin 0 [ 0.0, 0.5 ): 2
    bin 1 [ 0.5, 1.0 ): 0
    bin 2 [ 1.0, 1.5 ): 1
    bin 3 [ 1.5, 2.0 ): 1
    */
}

Features

Note 1 In the standard configuration, if you don't use weighted increments. The counter capacity is increased dynamically as the cell counts grow. When even the largest plain integral type would overflow, the storage switches to a multiprecision integer similar to those in Boost.Multiprecision, which is only limited by available memory.

Note 2 An axis can be configured to grow when a value is encountered that is outside of its range. It then grows new bins towards this value so that the value ends up in the new highest or lowest bin.

Note 3 The histogram can be configured to hold an arbitrary accumulator in each cell instead of a simple counter. Extra values can be passed to the histogram, for example, to compute the mean and variance of values which fall into the same cell. This feature can be used to calculate variance estimates for each cell, which are useful when you need to fit a statistical model to the cell values.

Note 4 The library throws exceptions when exceptions are enabled. When exceptions are disabled, a user-defined exception handler is called instead upon a throw and the program terminates, see boost::throw_exception for details. Disabling exceptions improves performance by 10 % to 20 % in benchmarks. The library does not use RTTI (only CTTI) so disabling it has no effect.

Note 5 Builtin axis types can be configured to only accept dimensional quantities, like those from Boost.Units. This means you get a useful error if you accidentally try to fill a length where the histogram axis expects a time, for example.

Benchmarks

Boost.Histogram is more flexible and faster than other C/C++ libraries. It was compared to:

Details on the benchmark are given in the documentation.

What users say

John Buonagurio | Manager at Exponent®

"I just wanted to say 'thanks' for your awesome Histogram library. I'm working on a software package for processing meteorology data and I'm using it to generate wind roses with the help of Qt and QwtPolar. Looks like you thought of just about everything here – the circular axis type was practically designed for this application, everything 'just worked'."

More information