Boost-histogram

1.7.2 · active · verified Sat Apr 11

Boost-histogram is a high-performance Python library providing bindings for the C++14 Boost.Histogram library, designed for fast, multi-dimensional generalized histogramming. It treats histograms as first-class objects, enabling easy filling, manipulation, slicing, and projection. The library is currently at version 1.7.2 and maintains an active release cadence with frequent updates and new features, often driven by the Scikit-HEP project.

Warnings

breaking Python version support has significantly changed across recent versions. Python 3.7 support was removed in `1.5.0`, Python 3.8 support was dropped after `1.5.2` (meaning `1.6.0` and later do not support 3.8), and Python 3.10+ is now required as of `1.7.0`.
Fix: Ensure your Python environment is 3.10 or newer when using `boost-histogram` version `1.7.0` or later. For older `boost-histogram` versions, check the specific Python requirements.
deprecated The internal `_storage_type` attribute changed from a `PendingDeprecationWarning` to a full `DeprecationWarning`.
Fix: Avoid direct reliance on `_storage_type` and use documented API for storage interaction if available, or upgrade to a more recent version and check alternatives if this was for advanced use cases.
gotcha Filling integer-based axes with floating-point arrays (or single floats) is now explicitly disallowed to prevent rounding issues around 0.
Fix: When filling axes designed for integers (e.g., `bh.axis.Integer`), ensure your input data are actual integers or integer-like values, not floats. Cast floats to integers explicitly if needed.
breaking Serialization behavior and format have seen several fixes and changes across versions, particularly around metadata and complex storages. This could lead to issues when loading histograms saved with older versions or in different environments.
Fix: Ensure that the `boost-histogram` version used for saving and loading histograms is consistent. If upgrading, re-save any critical histograms after the upgrade, or verify compatibility with the `uhi` library for unified serialization.
gotcha With the introduction of `MultiCell` storage and generic histogram types, advanced type checking might require updating type hints. Histograms are now generic, meaning `Hist` may need to be `Hist[Any]` in strict type-checked code.
Fix: If you are using a type checker with strictness enabled, you might need to adjust your type annotations, e.g., using `Hist[Any]` instead of `Hist` for more flexible typing where the specific storage type is not known or needs to be generic.

Install

pip install boost-histogram Install with pip
conda install -c conda-forge boost-histogram Install with Conda

Imports

boost_histogram
```
import boost_histogram as bh
```
Histogram
```
bh.Histogram(...)
```
The common pattern is to import `boost_histogram` as `bh` and then access `Histogram` and axis types through `bh.Histogram` and `bh.axis.*`.
axis.Regular
```
bh.axis.Regular(...)
```

Quickstart

This quickstart demonstrates how to create a 1D histogram using a regular axis, fill it with random data, and then access its bin counts and axis centers.

import boost_histogram as bh
import numpy as np

# Create a 1D histogram with 10 bins from 0 to 1
hist = bh.Histogram(bh.axis.Regular(10, 0, 1))

# Fill the histogram with data
data = np.random.rand(1000)
hist.fill(data)

# Access histogram values (counts)
counts = hist.view()
print(f"Histogram counts: {counts[:5]}...")

# Access axis centers
centers = hist.axes[0].centers
print(f"Axis centers: {centers[:5]}...")

view raw JSON →