---
id: uhi
version: "1.1.1"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# uhi — Unified Histogram Interface: tools to help library authors work with histograms

License: permissive · Maintenance: active · Downloads: 430.4K/mo

## What it is and what it does

UHI is a standards library that defines how histogram objects should behave across different scientific Python libraries. It provides type protocols—especially PlottableHistogram—that libraries like boost-histogram, hist, and uproot conform to, enabling code to work with histograms from multiple sources without knowing their concrete type. The package includes runtime-checkable protocols so you can use isinstance() to verify conformance, plus a utility to convert NumPy-style histogram tuples (counts, edges) into objects that match the standard interface.

The package is designed primarily as a dependency for library authors and type checkers rather than end-user code, though it does expose a few useful runtime tools. It depends only on numpy and typing-extensions, making it lightweight to include in projects that need histogram interoperability. The active maintenance and support for current Python versions (3.10+) ensures it stays aligned with modern scientific Python practices.

Use it for:

- Type-check histogram objects from different libraries to ensure they conform to a common interface before passing them to plotting functions.
- Adapt NumPy histogram tuples (counts, edges) into standardized PlottableHistogram objects for compatibility with libraries expecting the protocol.
- Document and enforce histogram indexing conventions across a multi-library scientific computing project.
- Support library development by providing reference protocols that new histogram implementations can conform to.
- Enable runtime verification that a histogram object supports the expected methods and attributes without tight coupling to a specific library.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

UHI defines and documents a standard interface for histogram objects across libraries, providing type protocols for runtime checking and tools to adapt NumPy-style histogram tuples into a common format.

Yes, if you are building libraries that work with histograms from multiple sources or need to enforce histogram interface standards. Install as a type-checking or testing dependency in projects that depend on histogram libraries like boost-histogram or hist. Not necessary for end-user code that only uses a single histogram library, but adds minimal friction and provides real value in interoperability scenarios.

## Install

pip install uhi
uv add uhi
poetry add uhi

## Installing uhi

Before you install: Low install friction with only numpy and typing-extensions as runtime dependencies. Actively maintained with recent releases; primarily designed as a type-checking and testing dependency for other libraries rather than a direct runtime requirement.

License in practice: BSD-3-Clause is permissive and places no significant restrictions on use or redistribution in commercial or open-source contexts.

Quickstart:

pip install uhi

import uhi.typing.plotting
from uhi.numpy_plottable import ensure_plottable_histogram

# Check if an object conforms to PlottableHistogram protocol
isinstance(histogram_obj, uhi.typing.plotting.PlottableHistogram)

# Adapt NumPy-style histogram tuple to PlottableHistogram
plottable = ensure_plottable_histogram(counts, edges)

Requires Python 3.10 or later.

Verify before relying:

- Whether the runtime-usable components (numpy_plottable adapter, protocol runtime checking) are sufficient for direct use or if this is primarily a transitive dependency.
- Performance characteristics when using isinstance() checks against PlottableHistogram at runtime in tight loops.

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 430.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

histogram interface standard, plottable histogram protocol, cross-library histogram compatibility, histogram type checking, numpy histogram adapter, histogram indexing standard, scikit-hep histogram tools, histogram-interop, type-protocols, scikit-hep

[View on SkillFed](https://skillfed.io/packages/uhi) · [View on PyPI](https://pypi.org/project/uhi/)