Hist

2.10.1 · active · verified Sat Apr 11

Hist is an analyst-friendly front-end for boost-histogram, providing enhanced classes and utilities for histogramming in Python. It offers features like named axes, quick construction shortcuts, and integrated plotting capabilities, building on the performance of boost-histogram. The library is actively maintained, with its current version being 2.10.1, and typically releases updates to align with Python and boost-histogram version changes.

Warnings

breaking Support for older Python versions is periodically dropped. As of v2.10.0, Python 3.9 is no longer supported. v2.9.0 dropped Python 3.8, and v2.8.0 dropped Python 3.7. The library requires Python 3.10+.
Fix: Ensure your environment uses Python 3.10 or newer. Upgrade your Python version if necessary.
breaking The minimum required version of `boost-histogram` has increased. For example, v2.10.0 dropped support for `boost-histogram` 1.5, requiring 1.7.0 or later. Earlier versions also saw similar increases.
Fix: Upgrade `boost-histogram` to the latest compatible version (e.g., `pip install --upgrade boost-histogram`). Consult `hist` release notes for specific version requirements.
deprecated The `[plot]` extra was split, with some functionalities moving to a new `[fit]` extra. If you previously installed with `[plot]` and relied on fitting tools, you might need to adjust your installation.
Fix: Install with `pip install "hist[plot,fit]"` to ensure all previously available features are present.
gotcha When working with Dask-backed histograms (e.g., `hist.dask.Hist`), the histogram object represents a computation graph. The actual histogram data is only materialized when `.compute()` is explicitly called on the object or a dask `compute()` function is used.
Fix: Always remember to call `.compute()` on Dask-backed `hist` objects to get the final in-memory histogram for inspection, plotting, or further non-Dask operations.
gotcha Using named axes is highly recommended as it enables more powerful indexing and manipulation shortcuts. While unnamed axes are allowed, many advanced features and syntactic sugars are designed around named axes. The `NamedHist` class forces names to be used in most places.
Fix: When creating histograms, always provide a `name` argument for each axis (e.g., `Hist.new.Reg(..., name='my_axis')`). Consider using `from hist import NamedHist` for stricter enforcement.
gotcha If filling an unweighted storage with weights, `hist.variances()` will return `None` as variances cannot be correctly computed. This can lead to unexpected behavior if you rely on variance calculations.
Fix: If you intend to use weighted fills and need variance calculations, ensure you initialize your histogram with a weighted storage type (e.g., `hist.storage.Weight()`).

Install

pip install hist Base install
pip install "hist[plot,fit,dask]" Full install with plotting, fitting, and Dask support

Imports

Hist
```
from hist import Hist
```
While 'import hist' is valid, the primary histogram class is 'Hist' and typically imported directly.
Hist.new
```
from hist import Hist; h = Hist.new.Reg(10, 0, 1, name='x')
```
Quick construction method for creating histograms without explicit axis imports.

Quickstart

This quickstart demonstrates how to create a simple 1D histogram using Hist's `Hist.new` quick construction, fill it with NumPy array data, and print its representation. The example also shows how to define named and labeled axes. Plotting functionality is available with the `[plot]` extra.

from hist import Hist
import numpy as np

# Create a histogram with one regular axis
h = (Hist.new
     .Reg(10, 0, 10, name="x", label="X-axis [units]")
     .Double() # Storage type
)

# Fill the histogram with some data
data = np.random.normal(5, 1, 1000)
h.fill(x=data)

# Access counts and plot (requires matplotlib, optional install)
# import matplotlib.pyplot as plt
# h.plot()
# plt.show()

print(h)

view raw JSON →