NumPy compatibility#

Histogram conversion#

Accessing the storage array#

You can access the storage of any Histogram using .view(), see Histogram.

NumPy tuple output#

You can directly convert a histogram into the tuple of outputs that np.histogram* would give you using .to_numpy() or .to_numpy(flow=True) on any histogram. This returns edges[0], edges[1], ..., values, and the edges are NumPy-style (upper edge inclusive).

NumPy adaptors#

You can use boost-histogram as a drop in replacement for NumPy histograms. All three histogram functions (bh.numpy.histogram, bh.numpy.histgoram2d, and bh.numpy.histogramdd) are provided. The syntax is identical, though boost-histogram adds three new keyword-only arguments; storage= to select the storage, histogram=bh.Histogram to produce a boost-histogram instead of a tuple, and threads=N to select a number of threads to fill with.

1D histogram example#

If you try the following in an IPython session, you will get:

import numpy as np
import boost_histogram as bh

norm_vals = np.concatenate(
    [
        np.random.normal(loc=5, scale=1, size=1_000_000),
        np.random.normal(loc=2, scale=0.2, size=200_000),
        np.random.normal(loc=8, scale=0.2, size=200_000),
    ]
)

%%timeit
bins, edges = np.histogram(norm_vals, bins=100, range=(0, 10))

17.4 ms ± 2.64 ms per loop (mean ± std. dev. of 7 runs, 100 loops each)

Of course, you then are either left on your own to compute centers, density, widths, and more, or in some cases you can change the computation call itself to add density=, or use the matching function inside Matplotlib, and the API is different if you want 2D or ND histograms. But if you already use NumPy histograms and you really don’t want to rewrite your code, boost-histogram has adaptors for the three histogram functions in NumPy:

%%timeit
bins, edges = bh.numpy.histogram(norm_vals, bins=100, range=(0, 10))

7.3 ms ± 55.7 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)

This is only a hair slower than using the raw boost-histogram API, and is still a nice performance boost over NumPy. You can even use the NumPy syntax if you want a boost-histogram object later:

hist = bh.numpy.histogram(norm_vals, bins=100, range=(0, 10), histogram=bh.Histogram)

You can later get a NumPy style output tuple from a histogram object:

bins, edges = hist.to_numpy()

So you can transition your code slowly to boost-histogram.

2D Histogram example#

data = np.random.multivariate_normal((0, 0), ((1, 0), (0, 0.5)), 10_000_000).T.copy()

We can check the performance against NumPy again; NumPy does not do well with regular spaced bins in more than 1D:

%%timeit
np.histogram2d(*data, bins=(400, 200), range=((-2, 2), (-1, 1)))

1.31 s ± 17.3 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

%%timeit
bh.numpy.histogram2d(*data, bins=(400, 200), range=((-2, 2), (-1, 1)))

101 ms ± 117 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)

For more than one dimension, boost-histogram is more than an order of magnitude faster than NumPy for regular spaced binning. Although optimizations may be added to boost-histogram for common axes combinations later, in 0.6.1, all axes combinations share a common code base, so you can expect at least this level of performance regardless of the axes types or number of axes! Threaded filling can give you an even larger performance boost if you have multiple cores and a large fill to perform.

NumPy compatibility

Contents