Unified Histogram Interface (UHI)

1.0.0 · active · verified Sat Apr 11

UHI provides a Unified Histogram Interface, a set of protocols and utilities to help library authors work with histograms consistently across different backends. It aims to standardize histogram operations, access, and serialization. The current version is 1.0.0, and it follows an active release cadence with regular updates.

Warnings

breaking UHI has dropped support for older Python versions across releases. v0.4.0 dropped Python 3.6, v0.5.0 requires Python 3.8+, and v1.0.0 requires Python 3.9+.
Fix: Ensure your environment is running Python 3.9 or newer. Upgrade Python if necessary.
gotcha The serialization schema was experimental in v0.5.0 and finalized in v1.0.0. Histograms serialized with v0.5.0's experimental API may not be compatible with v1.0.0+.
Fix: For production systems, ensure serialization and deserialization happen with v1.0.0 or later for stable compatibility. Re-serialize data if migrating from v0.5.0.
gotcha UHI (Unified Histogram Interface) provides protocols (like `uhi.typing.uhi.UHI`) and a concrete implementation (`uhi.hist.Histogram`). Users should instantiate `uhi.hist.Histogram` or wrap existing `hist` objects, not directly instantiate the `UHI` protocol.
Fix: Always use `from uhi.hist import Histogram` to create UHI-compliant histogram objects, or wrap an existing `hist` object: `uhi_histogram = Histogram(my_hist_object)`.

Install

pip install uhi Install stable version

Imports

Histogram
```
from uhi.hist import Histogram
```
Main concrete implementation to wrap a `hist` object or create a new UHI-compliant histogram.
serialize
```
from uhi.serialization import serialize
```
Used to save UHI-compliant histograms to various formats (HDF5, ZIP, JSON).
deserialize
```
from uhi.serialization import deserialize
```
Used to load UHI-compliant histograms from various formats.
UHI
```
from uhi.typing.uhi import UHI
```
UHI is a Protocol (Abstract Base Class) and cannot be directly instantiated. Use concrete implementations like `uhi.hist.Histogram`.

Quickstart

This quickstart demonstrates creating a histogram using the `hist` library, wrapping it with `uhi.hist.Histogram`, accessing its view, and then serializing and deserializing it using UHI's built-in functionality introduced in v1.0.0.

import numpy as np
import hist
from uhi.hist import Histogram
from uhi.serialization import serialize, deserialize
import tempfile
import os

# Create a sample histogram using the 'hist' library (uhi's recommended backend)
h = (
    hist.new.Reg(10, 0, 10, name="x", label="X-axis")
    .Reg(5, -5, 5, name="y", label="Y-axis")
    .Double()
)
h.fill(x=np.random.rand(100) * 10, y=np.random.randn(100) * 5)

# Wrap it in UHI Histogram for a consistent interface
uhi_h = Histogram(h)

# Access data view
print(f"Sum of entries: {uhi_h.view().sum()}")

# Serialization example (major feature in v1.0.0)
with tempfile.TemporaryDirectory() as tmpdir:
    filepath_hdf5 = os.path.join(tmpdir, "my_histogram.hdf5")
    serialize(uhi_h, filepath_hdf5) # Automatically infers format from extension
    print(f"Serialized histogram to {filepath_hdf5}")

    deserialized_uhi_h = deserialize(filepath_hdf5)
    print(f"Deserialized histogram. Sum: {deserialized_uhi_h.view().sum()}")
    assert np.allclose(uhi_h.view(), deserialized_uhi_h.view())

print("UHI quickstart complete!")

view raw JSON →