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.
pip install boost-histogramVerified import paths — ran on the pinned version, not inferred.
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.
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.
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.
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.
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.
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.
Instead of direct scaling, retrieve the slice as a view, modify it, and then set the contents of the slice with the modified view. Alternatively, apply operations to the full histogram or use explicit loops.
Upgrade to a newer version of `boost-histogram` (e.g., 1.0 or later), as this bug was fixed in subsequent releases.
Provide an integer index (or a sequence of indices) to the `value()` method, for example, `axis.value(0)` for the first bin, or use `axis.centers` or `axis.edges` to get arrays of bin centers or edges.
Initialize the `bh.axis.category` with at least one category, even if it's a placeholder, or ensure `growth=False` if an empty axis is genuinely intended (though an empty fixed-size category axis isn't very useful).