Skip to content
Fast multi-dimensional histogram with convenient interface for C++14
Branch: develop
Clone or download
Latest commit a759600 Apr 24, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
benchmark msvc fixes, simplification and bug-fixes of mp_int, more test coverage ( Feb 18, 2019
doc Replace boost::iterator_adaptor with private iterator_adaptor to redu… Apr 19, 2019
examples
include/boost Fix missing coverage and allocator-fail logic Apr 23, 2019
meta
test Fix missing coverage and allocator-fail logic Apr 23, 2019
tools
.appveyor.yml don't stop always Apr 16, 2019
.clang-format fix Jan 10, 2019
.clang_complete adding clang_complete Jan 10, 2019
.gitignore increase coverage Apr 22, 2019
.travis.yml increase coverage Apr 22, 2019
CMakeLists.txt increase coverage Apr 22, 2019
CONTRIBUTING.md removing cmake support Feb 24, 2019
Jamfile increase coverage Apr 22, 2019
LICENSE switch to boost license Apr 10, 2016
README.md Fix URL Apr 24, 2019
index.html adding index.html Feb 9, 2019

README.md

Histogram

Fast multi-dimensional histogram with convenient interface for C++14

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

Branch Linux and OSX Windows Coverage
develop Build Status Travis Build status codecov
master Build Status Travis Build status Appveyor codecov

Supported compiler versions gcc >= 5.5, clang >= 3.8, msvc >= 14.1

This header-only open-source library provides an easy-to-use state-of-the-art multi-dimensional histogram class for the professional statistician and everyone who needs to count things. The histogram is easy to use for the casual user and yet so customizable that it does not restrict the power-user. The library offers a unique safety guarantee: cell counts cannot overflow or be capped in the standard configuration [1]. And it can do more than counting. The histogram can be equipped with arbitrary accumulators to compute means, medians, and whatever you fancy in each cell. The library is very fast single-threaded (see benchmarks) and several parallelization options are provided for multi-threaded programming.

The library passed Boost review in September 2018 and was first released with Boost-1.70 on April 12th, 2019. The source code is licensed under the Boost Software License.

Check out the full documentation. Python bindings to this library are available elsewhere.

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)

#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 on an axis called "x"
    auto h = make_histogram(
      axis::regular<>(4, 0.0, 2.0, "x")
    );

    // 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

  • Extremely customisable multi-dimensional histogram
  • Simple, convenient, STL and Boost-compatible interface
  • Counters with high dynamic range, cannot overflow or be capped [1]
  • Better performance than other libraries (see benchmarks for details)
  • Efficient use of memory [1]
  • Support for custom axis types: define how input values should map to indices
  • Support for under-/overflow bins (can be disabled individually to reduce memory consumption)
  • Support for axes that grow automatically with input values [2]
  • Support for weighted increments
  • Support for profiles and more generally, user-defined accumulators in cells [3]
  • Support for completely stack-based histograms
  • Support for adding, subtracting, multiplying, dividing, and scaling histograms
  • Support for custom allocators
  • Support for programming with units [4]
  • Optional serialization based on Boost.Serialization

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 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'."

You can’t perform that action at this time.