UHI: Universal Histogram Interface

This is a package meant primarily for documenting histogram indexing and the PlottableHistogram Protocol and any future cross-library standards. It also contains the code for the PlottableHistogram Protocol, to be used in type checking libraries wanting to conform to the protocol, and uhi.testing, a set of tools for testing conformance to UHI indexing. It is not usually a runtime dependency, but only a type checking, testing, and/or docs dependency in support of other libraries (such as boost-histogram 0.13+, hist 2.1+, mplhep 0.2.15+, uproot 4+, and histoprint 2+). There are a few useful runtime usable components (listed below). Older versions are available for Python 3.6+. See what's new.

To assist plotting libraries in accepting Histograms from classic sources, see uhi.numpy_plottable.ensure_plottable_histogram, which will adapt NumPy style tuples into a simple PlottableHistogram.

The uhi.io module can read and write histograms in JSON, ZIP, HDF5, and ROOT (with uproot or PyROOT), and uhi.io.ops.add sums histograms bin-by-bin. The uhi add command does the same for files, like ROOT's hadd. The uhi validate command checks files against the schema (needs the schema extra).

The Protocols provided do support runtime checking, so isinstance(h, uhi.typing.plottable.PlottableHistogram) is valid at runtime and might be simpler than manually checking for the expected methods.