{"id":4307,"library":"uhi","title":"Unified Histogram Interface (UHI)","description":"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.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/Scikit-HEP/uhi","tags":["histogram","data visualization","scientific computing","physics","HEP","interface"],"install":[{"cmd":"pip install uhi","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"UHI works with and recommends the `hist` library as a primary backend for histogram objects.","package":"hist","optional":false},{"reason":"Required for array operations and data manipulation within histogram backends.","package":"numpy","optional":false}],"imports":[{"note":"Main concrete implementation to wrap a `hist` object or create a new UHI-compliant histogram.","symbol":"Histogram","correct":"from uhi.hist import Histogram"},{"note":"Used to save UHI-compliant histograms to various formats (HDF5, ZIP, JSON).","symbol":"serialize","correct":"from uhi.serialization import serialize"},{"note":"Used to load UHI-compliant histograms from various formats.","symbol":"deserialize","correct":"from uhi.serialization import deserialize"},{"note":"UHI is a Protocol (Abstract Base Class) and cannot be directly instantiated. Use concrete implementations like `uhi.hist.Histogram`.","wrong":"uhi.typing.uhi.UHI()","symbol":"UHI","correct":"from uhi.typing.uhi import UHI"}],"quickstart":{"code":"import numpy as np\nimport hist\nfrom uhi.hist import Histogram\nfrom uhi.serialization import serialize, deserialize\nimport tempfile\nimport os\n\n# Create a sample histogram using the 'hist' library (uhi's recommended backend)\nh = (\n    hist.new.Reg(10, 0, 10, name=\"x\", label=\"X-axis\")\n    .Reg(5, -5, 5, name=\"y\", label=\"Y-axis\")\n    .Double()\n)\nh.fill(x=np.random.rand(100) * 10, y=np.random.randn(100) * 5)\n\n# Wrap it in UHI Histogram for a consistent interface\nuhi_h = Histogram(h)\n\n# Access data view\nprint(f\"Sum of entries: {uhi_h.view().sum()}\")\n\n# Serialization example (major feature in v1.0.0)\nwith tempfile.TemporaryDirectory() as tmpdir:\n    filepath_hdf5 = os.path.join(tmpdir, \"my_histogram.hdf5\")\n    serialize(uhi_h, filepath_hdf5) # Automatically infers format from extension\n    print(f\"Serialized histogram to {filepath_hdf5}\")\n\n    deserialized_uhi_h = deserialize(filepath_hdf5)\n    print(f\"Deserialized histogram. Sum: {deserialized_uhi_h.view().sum()}\")\n    assert np.allclose(uhi_h.view(), deserialized_uhi_h.view())\n\nprint(\"UHI quickstart complete!\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your environment is running Python 3.9 or newer. Upgrade Python if necessary.","message":"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+.","severity":"breaking","affected_versions":"<1.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.","message":"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+.","severity":"gotcha","affected_versions":"0.5.0"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}