{"id":4035,"library":"hist","title":"Hist","description":"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.","status":"active","version":"2.10.1","language":"en","source_language":"en","source_url":"https://github.com/scikit-hep/hist","tags":["histogram","scientific-computing","data-analysis","plotting","physics","scikit-hep","boost-histogram"],"install":[{"cmd":"pip install hist","lang":"bash","label":"Base install"},{"cmd":"pip install \"hist[plot,fit,dask]\"","lang":"bash","label":"Full install with plotting, fitting, and Dask support"}],"dependencies":[{"reason":"Core backend for histogramming operations.","package":"boost-histogram","optional":false},{"reason":"Required for plotting features when installing with `[plot]` extra.","package":"matplotlib","optional":true},{"reason":"Required for Dask-backed histogram operations when installing with `[dask]` extra.","package":"dask","optional":true},{"reason":"Recommended for HEP-style plotting integration.","package":"mplhep","optional":true},{"reason":"Optional for certain functionalities, no longer strictly required by default since v2.5.0.","package":"scipy","optional":true},{"reason":"Optional for fitting functionalities, no longer strictly required by default since v2.5.0.","package":"iminuit","optional":true}],"imports":[{"note":"While 'import hist' is valid, the primary histogram class is 'Hist' and typically imported directly.","wrong":"import hist.Hist","symbol":"Hist","correct":"from hist import Hist"},{"note":"Quick construction method for creating histograms without explicit axis imports.","symbol":"Hist.new","correct":"from hist import Hist; h = Hist.new.Reg(10, 0, 1, name='x')"}],"quickstart":{"code":"from hist import Hist\nimport numpy as np\n\n# Create a histogram with one regular axis\nh = (Hist.new\n     .Reg(10, 0, 10, name=\"x\", label=\"X-axis [units]\")\n     .Double() # Storage type\n)\n\n# Fill the histogram with some data\ndata = np.random.normal(5, 1, 1000)\nh.fill(x=data)\n\n# Access counts and plot (requires matplotlib, optional install)\n# import matplotlib.pyplot as plt\n# h.plot()\n# plt.show()\n\nprint(h)","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your environment uses Python 3.10 or newer. Upgrade your Python version if necessary.","message":"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+.","severity":"breaking","affected_versions":">=2.8.0"},{"fix":"Upgrade `boost-histogram` to the latest compatible version (e.g., `pip install --upgrade boost-histogram`). Consult `hist` release notes for specific version requirements.","message":"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.","severity":"breaking","affected_versions":">=2.8.0"},{"fix":"Install with `pip install \"hist[plot,fit]\"` to ensure all previously available features are present.","message":"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.","severity":"deprecated","affected_versions":"<2.7.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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()`).","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}