[Python][UHI] Start introducing UHI serialization

Author: siliataider

bindings/pyroot/pythonizations/CMakeLists.txt

@@ -128,6 +128,7 @@ set(py_sources
   ROOT/_pythonization/_uhi/tags.py
   ROOT/_pythonization/_uhi/indexing.py
   ROOT/_pythonization/_uhi/plotting.py
+  ROOT/_pythonization/_uhi/serialization.py
   ${PYROOT_EXTRA_PYTHON_SOURCES}
 )
 

bindings/pyroot/pythonizations/python/ROOT/_pythonization/_th1.py

@@ -249,7 +249,7 @@ def _FillWithNumpyArray(self, *args):
 def pythonize_th1(klass):
     # Parameters:
     # klass: class to be pythonized
-    from ROOT._pythonization._uhi.main import _add_indexing_features
+    from ROOT._pythonization._uhi.main import _add_indexing_features, _add_serialization_features
 
     # Support hist *= scalar
     klass.__imul__ = _imul
@@ -261,7 +261,8 @@ def pythonize_th1(klass):
     klass._Original_SetDirectory = klass.SetDirectory
     klass.SetDirectory = _SetDirectory_SetOwnership
 
-    # Add UHI indexing features
+    # Add UHI indexing and serialization features
     _add_indexing_features(klass)
+    _add_serialization_features(klass)
 
     inject_clone_releasing_ownership(klass)

bindings/pyroot/pythonizations/python/ROOT/_pythonization/_uhi/main.py

@@ -64,3 +64,14 @@ def _add_plotting_features(klass: Any) -> None:
     klass.counts = _counts
     klass.axes = property(_axes)
     klass.values = values_func_dict.get(klass.__name__, _values_default)
+
+
+"""
+Implementation of the serialization component of the UHI
+"""
+
+
+def _add_serialization_features(klass: Any) -> None:
+    from .serialization import _to_uhi_
+
+    klass._to_uhi_ = _to_uhi_

bindings/pyroot/pythonizations/python/ROOT/_pythonization/_uhi/plotting.py

@@ -38,6 +38,14 @@ def circular(self) -> bool:
     def discrete(self) -> bool:
         return self._discrete
 
+    @property
+    def underflow(self) -> bool:
+        return True
+
+    @property
+    def overflow(self) -> bool:
+        return True
+
 
 class PlottableAxisBase(ABC):
     def __init__(self, tAxis: Any) -> None:
@@ -104,7 +112,7 @@ def _hasWeights(hist: Any) -> bool:
 def _axes(self) -> Tuple[Union[PlottableAxisContinuous, PlottableAxisDiscrete], ...]:
     return tuple(PlottableAxisFactory.create(_get_axis(self, i)) for i in range(self.GetDimension()))
 
-
+# TODO this is not correct?
 def _kind(self) -> Kind:
     return Kind.COUNT if not _hasWeights(self) else Kind.MEAN
 
@@ -174,6 +182,8 @@ def _counts(self) -> np.typing.NDArray[Any]:  # noqa: F821
         where=sum_of_weights_squared != 0,
     )
 
+def _get_sum_of_weights(self) -> np.typing.NDArray[Any]:  # noqa: F821
+    return self.values()
 
 def _get_sum_of_weights_squared(self) -> np.typing.NDArray[Any]:  # noqa: F821
     import numpy as np

bindings/pyroot/pythonizations/python/ROOT/_pythonization/_uhi/serialization.py

@@ -0,0 +1,81 @@
+# Author: Silia Taider CERN  10/2025
+
+################################################################################
+# Copyright (C) 1995-2025, Rene Brun and Fons Rademakers.                      #
+# All rights reserved.                                                         #
+#                                                                              #
+# For the licensing terms see $ROOTSYS/LICENSE.                                #
+# For the list of contributors see $ROOTSYS/README/CREDITS.                    #
+################################################################################
+from __future__ import annotations
+
+from typing import Any
+
+import ROOT
+
+from .plotting import PlottableAxisBase, _get_sum_of_weights, _get_sum_of_weights_squared, _hasWeights
+from .tags import _get_axis
+
+"""
+Implementation of the serialization component of the UHI
+"""
+
+
+def _axis_to_dict(root_axis: ROOT.TAxis, uhi_axis: PlottableAxisBase) -> dict[str, Any]:
+    return {
+        "type": "regular",
+        "lower": root_axis.GetBinLowEdge(root_axis.GetFirst()),
+        "upper": root_axis.GetBinUpEdge(root_axis.GetLast()),
+        "bins": root_axis.GetNbins(),
+        "underflow": uhi_axis.traits.underflow,
+        "overflow": uhi_axis.traits.overflow,
+        "circular": uhi_axis.traits.circular,
+    }
+
+
+def _storage_to_dict(hist: Any) -> dict[str, Any]:
+    """
+    Logic:
+    - If histogram is a profile (TProfile*) --> Kind="MEAN":
+        - if histogram has Sumw2: type is weighted_mean_storage (if _hasWeights(hist))
+        - else: storage type is mean_storage
+    - Else (TH1*/TH2*/TH3*) --> Kind="COUNT":
+        - if histogram has Sumw2: type is weighted_storage
+        - else if histogram is TH*I: type is int_storage
+        - else: type is double_storage
+    """
+    storage_dict = {
+        "values": hist.values(),
+    }
+
+    if hist.kind == "MEAN":
+        storage_dict["variances"] = hist.variances()
+
+        if _hasWeights(hist):
+            storage_dict["type"] = "weighted_mean"
+            storage_dict["sum_of_weights"] = _get_sum_of_weights(hist)
+            storage_dict["sum_of_weights_squared"] = _get_sum_of_weights_squared(hist)
+        else:
+            storage_dict["type"] = "mean"
+            storage_dict["counts"] = hist.counts()
+
+    else:  # COUNT
+        if _hasWeights(hist):
+            storage_dict["type"] = "weighted"
+            storage_dict["variances"] = hist.variances()
+        else:
+            if hist.ClassName().endswith("I"):
+                storage_dict["type"] = "int"
+            else:
+                storage_dict["type"] = "double"
+
+    return storage_dict
+
+
+def _to_uhi_(self) -> dict[str, Any]:
+    return {
+        "uhi_schema": 1,
+        "writer_info": {"ROOT": {"version": ROOT.__version__, "class": self.ClassName()}},
+        "axes": [_axis_to_dict(_get_axis(self, i), self.axes[i]) for i in range(self.GetDimension())],
+        "storage": _storage_to_dict(self),
+    }

tutorials/hist/repro_uhi_serialization.py

@@ -0,0 +1,17 @@
+import json
+
+import ROOT
+import uhi.io.json
+
+import hist
+
+h = ROOT.TH1D("h", "h", 10, -5, 5)
+h[...] = range(10)
+print("\nh=", h)
+print("values=", h.values())
+
+ob = json.dumps(h, default=uhi.io.json.default)
+ir = json.loads(ob, object_hook=uhi.io.json.object_hook)
+
+h_loaded = hist.Hist(ir)
+print("\nh_loaded =\n", h_loaded)