histogram/doc/getting_started.qbk

[section Getting started]

To get you started, here are some commented usage examples.

[section Make and use a static 1d-histogram in C++]

[c++]``
#include <boost/histogram.hpp>
#include <iostream>

int main(int, char**) {
    namespace bh = boost::histogram;
    using namespace bh::literals; // enables _c suffix

    // create static 1d-histogram with 10 equidistant bins from -1.0 to 2.0,
    // with axis of histogram labeled as "x"
    auto h = bh::make_static_histogram(
        bh::axis::regular<>(10, -1.0, 2.0, "x")
    );

    // fill histogram with data
    h.fill(-1.5); // put in underflow bin
    h.fill(-1.0); // included in first bin, bin interval is semi-open
    h.fill(-0.5);
    h.fill(1.1);
    h.fill(0.3);
    h.fill(1.7);
    h.fill(2.0);  // put in overflow bin, bin interval is semi-open
    h.fill(20.0); // put in overflow bin

    /*
        instead of calling h.fill(...) with same argument N times,
        use bh::count, which accepts an integer argument N
    */
    h.fill(1.0, bh::count(4));

    /*
        to fill a weighted entry, use bh::weight, which accepts a double
        argument; don't confuse with bh::count, it has a different effect
        on the variance (see Rationale for a section explaining weighted fills)
    */
    h.fill(0.1, bh::weight(2.5));

    /*
        iterate over bins, loop excludes under- and overflow bins
        - index 0_c is a compile-time number to make axis(...) return
          a different type for each axis
        - for-loop yields std::pair<[bin index], [bin type]>, where
          [bin type] usually is a semi-open interval representing the bin,
          whose edges can be accessed with methods lower() and upper(), but
          the [bin type] depends on the axis and could be something else
        - value(index) method returns the bin count at index,
        - variance(index) method returns a variance estimate of the bin count
          at index (see Rationale for a section explaining the variance)
    */
    for (const auto& bin : h.axis(0_c)) {
        std::cout << "bin " << bin.first
                  << " x in [" << bin.second.lower() << ", " << bin.second.upper() << "): "
                  << h.value(bin.first) << " +/- " << std::sqrt(h.variance(bin.first))
                  << std::endl;
    }

    /* program output:

    bin 0 x in [-1, -0.7): 1 +/- 1
    bin 1 x in [-0.7, -0.4): 1 +/- 1
    bin 2 x in [-0.4, -0.1): 0 +/- 0
    bin 3 x in [-0.1, 0.2): 2.5 +/- 2.5
    bin 4 x in [0.2, 0.5): 1 +/- 1
    bin 5 x in [0.5, 0.8): 0 +/- 0
    bin 6 x in [0.8, 1.1): 4 +/- 2
    bin 7 x in [1.1, 1.4): 1 +/- 1
    bin 8 x in [1.4, 1.7): 0 +/- 0
    bin 9 x in [1.7, 2): 1 +/- 1

    */
}
``

[endsect]

[section Make and use a dynamic 2d-histogram in C++]

Here we fill the histogram with some random numbers.

[c++]``
#include <boost/histogram.hpp>
#include <boost/random/mersenne_twister.hpp>
#include <boost/random/normal_distribution.hpp>
#include <cstdlib>

namespace br = boost::random;
namespace bh = boost::histogram;

int main() {
    /*
        create dynamic histogram using `make_dynamic_histogram`
        - axis can be passed directly, just like for `make_static_histogram`
        - in addition, also accepts iterators over a sequence of axes
    */
    std::vector<bh::axis::any<>> axes = {bh::axis::regular<>(5, -5, 5, "x"),
                                         bh::axis::regular<>(5, -5, 5, "y")};
    auto h = bh::make_dynamic_histogram(axes.begin(), axes.end());

    // fill histogram, random numbers are generated on the fly
    br::mt19937 gen;
    br::normal_distribution<> norm;
    for (int i = 0; i < 1000; ++i)
        h.fill(norm(gen), norm(gen));

    /*
        print histogram
        - for most axis types, the for loop looks just like for a static
          histogram, except that we can pass runtime numbers, too
        - in contrast to the static histogram, we need to cast axis::any
          to the held axis type before looping, if the [bin type] is not
          convertible to a double interval
    */
    for (const auto& ybin : h.axis(1)) { // rows
        for (const auto& xbin : h.axis(0)) { // columns
            std::printf("%3.0f ", h.value(xbin.first, ybin.first));
        }
        std::printf("\n");
    }
}
``

[section Make and use a 2d-histogram in Python]

You need to build the library with Numpy support to run this example.

[python]`import histogram as hg
import numpy as np

# create 2d-histogram with two axes with 10 equidistant bins from -3 to 3
h = hg.histogram(hg.axis.regular(10, -3, 3, "x"),
                 hg.axis.regular(10, -3, 3, "y"))

# generate some numpy arrays with data to fill into histogram,
# in this case normal distributed random numbers in x and y
x = np.random.randn(1000)
y = 0.5 * np.random.randn(1000)

# fill histogram with numpy arrays, this is very fast
h.fill(x, y)

# get representations of the bin edges as Numpy arrays, this representation
# differs from `list(h.axis(0))`, because it is optimised for compatibility
# with existing Numpy code, i.e. to replace numpy.histogram
x = np.array(h.axis(0))
y = np.array(h.axis(1))

# creates a view of the counts (no copy involved)
count_matrix = np.asarray(h)

# cut off the under- and overflow bins (no copy involved)
reduced_count_matrix = count_matrix[:-2,:-2]

try:
    # draw the count matrix
    import matplotlib.pyplot as plt
    plt.pcolor(x, y, reduced_count_matrix.T)
    plt.xlabel(h.axis(0).label)
    plt.ylabel(h.axis(1).label)
    plt.savefig("example_2d_python.png")
except ImportError:
    # ok, no matplotlib, then just print it
    print count_matrix
``

[endsect]

[endsect]