feat: add xoffsets option (#559)

Author: andrzejnovak

src/mplhep/plot.py

@@ -85,6 +85,7 @@ def histplot(
     sort=None,
     edges=True,
     binticks=False,
+    xoffsets=None,
     ax: mpl.axes.Axes | None = None,
     flow="hint",
     **kwargs,
@@ -147,6 +148,8 @@ def histplot(
             Specifies whether to draw first and last edges of the histogram
         binticks : bool, default: False, optional
             Attempts to draw x-axis ticks coinciding with bin boundaries if feasible.
+        xoffsets: bool, default: False,
+            If True, the bin "centers" of plotted histograms will be offset within their bin.
         ax : matplotlib.axes.Axes, optional
             Axes object (if None, last one is fetched or one is created)
         flow :  str, optional { "show", "sum", "hint", "none"}
@@ -273,6 +276,7 @@ def iterable_not_string(arg):
         density=density,
         binwnorm=binwnorm,
         flow=flow,
+        xoffsets=xoffsets,
     )
     flow_bins, underflow, overflow = flow_info
 
@@ -342,6 +346,7 @@ def iterable_not_string(arg):
                     _ls = _kwargs.pop("linestyle", "-")
                     _kwargs["linestyle"] = "none"
                     _plot_info = plottables[i].to_errorbar()
+                    del _plot_info["xerr"]
                     _e = ax.errorbar(
                         **_plot_info,
                         **_kwargs,
@@ -477,7 +482,12 @@ def iterable_not_string(arg):
             _plot_info = plottables[i].to_errorbar()
             if yerr is False:
                 _plot_info["yerr"] = None
-            _plot_info["xerr"] = _xerr
+            if not xerr:
+                del _plot_info["xerr"]
+            if isinstance(xerr, (int, float)) and not isinstance(xerr, bool):
+                _plot_info["xerr"] = xerr
+            elif isinstance(xerr, (np.ndarray, list)):
+                _plot_info["xerr"] = xerr[i]
             _e = ax.errorbar(
                 **_plot_info,
                 label=_labels[i],

src/mplhep/utils.py

@@ -145,6 +145,7 @@ def get_plottables(
     stack=False,
     density=False,
     binwnorm=None,
+    xoffsets=False,
 ):
     """
     Generate plottable histograms from various histogram data sources.
@@ -189,6 +190,8 @@ def get_plottables(
     binwnorm : float, optional
         If true, convert sum weights to bin-width-normalized, with unit equal to
             supplied value (usually you want to specify 1.)
+    xoffsets : bool | float | iterable, optional
+        Offset for x-axis values.
 
     Returns
     -------
@@ -203,7 +206,16 @@ def get_plottables(
     hists = list(process_histogram_parts(H, bins))
     final_bins, _ = get_plottable_protocol_bins(hists[0].axes[0])
 
-    for h in hists:
+    if xoffsets is True:
+        parsed_offsets = []
+        widths = np.diff(final_bins)
+        sub_bin_width = widths / (len(hists) + 1)
+        for i in range(len(hists)):
+            parsed_offsets.append(sub_bin_width * (i + 1))
+        xoffsets = parsed_offsets
+    else:
+        xoffsets = [None] * len(hists)
+    for h, xoffset in zip(hists, xoffsets):
         value, variance = np.copy(h.values()), h.variances()
         if has_variances := variance is not None:
             variance = np.copy(variance)
@@ -241,7 +253,9 @@ def get_plottables(
 
         # Set plottables
         if flow in ("none", "hint"):
-            plottables.append(Plottable(value, edges=final_bins, variances=variance))
+            plottables.append(
+                Plottable(value, edges=final_bins, variances=variance, xoffsets=xoffset)
+            )
         elif flow == "show":
             _flow_bin_size: float = np.max(
                 [0.05 * (final_bins[-1] - final_bins[0]), np.mean(np.diff(final_bins))]
@@ -257,7 +271,9 @@ def get_plottables(
                 value = np.r_[value, overflow]
                 if has_variances:
                     variance = np.r_[variance, overflowv]
-            plottables.append(Plottable(value, edges=flow_bins, variances=variance))
+            plottables.append(
+                Plottable(value, edges=flow_bins, variances=variance, xoffsets=xoffset)
+            )
         elif flow == "sum":
             if underflow > 0:
                 value[0] += underflow
@@ -267,9 +283,13 @@ def get_plottables(
                 value[-1] += overflow
                 if has_variances:
                     variance[-1] += overflowv
-            plottables.append(Plottable(value, edges=final_bins, variances=variance))
+            plottables.append(
+                Plottable(value, edges=final_bins, variances=variance, xoffsets=xoffset)
+            )
         else:
-            plottables.append(Plottable(value, edges=final_bins, variances=variance))
+            plottables.append(
+                Plottable(value, edges=final_bins, variances=variance, xoffsets=xoffset)
+            )
 
     if w2 is not None:
         for _w2, _plottable in zip(
@@ -422,7 +442,14 @@ def norm_stack_plottables(plottables, bins, stack=False, density=False, binwnorm
 
 class Plottable:
     def __init__(
-        self, values, *, edges=None, variances=None, yerr=None, w2method="poisson"
+        self,
+        values,
+        *,
+        edges=None,
+        xoffsets=None,
+        variances=None,
+        yerr=None,
+        w2method="poisson",
     ):
         self._values = np.array(values).astype(float)
         self.variances = None
@@ -440,8 +467,14 @@ def __init__(
         if self.edges is None:
             self.edges = np.arange(len(values) + 1)
         self.centers = self.edges[:-1] + np.diff(self.edges) / 2
-        self.method = w2method
+        if xoffsets is not None:
+            self.centers = self.edges[:-1] + xoffsets
+        self.xerr_lo, self.xerr_hi = (
+            self.centers - self.edges[:-1],
+            self.edges[1:] - self.centers,
+        )
 
+        self.method = w2method
         self.yerr = yerr
         assert self.variances is None or self.yerr is None
         if self.yerr is not None:
@@ -579,6 +612,7 @@ def to_errorbar(self):
             "x": self.centers,
             "y": self.values,
             "yerr": [self.yerr_lo, self.yerr_hi],
+            "xerr": [self.xerr_lo, self.xerr_hi],
         }
 
 

tests/baseline/test_histplot_w2_methods.png

@@ -770,3 +770,53 @@ def test_histplot_sort(sort):
     )
     ax.legend()
     return fig
+
+
+@pytest.mark.mpl_image_compare(style="default", remove_text=True)
+def test_histplot_xoffsets():
+    np.random.seed(0)
+    evts = np.random.normal(2, 2, 100)
+    htype1 = hist.new.Var([0, 1, 2, 3, 5, 10]).Weight().fill(evts)
+
+    fig, axs = plt.subplots(2, 2)
+    axs = axs.flatten()
+    hep.histplot(
+        [htype1, htype1, htype1],
+        ax=axs[0],
+        xoffsets=True,
+        xerr=False,
+        histtype="errorbar",
+        alpha=1,
+    )
+    hep.histplot(htype1, yerr=False, alpha=0.2, ax=axs[0])
+
+    hep.histplot(
+        [htype1, htype1, htype1],
+        ax=axs[1],
+        xoffsets=True,
+        xerr=True,
+        histtype="errorbar",
+        alpha=1,
+    )
+    hep.histplot(htype1, yerr=False, alpha=0.2, ax=axs[1])
+
+    hep.histplot(
+        [htype1, htype1, htype1],
+        ax=axs[2],
+        xoffsets=True,
+        xerr=0.5,
+        histtype="errorbar",
+        alpha=1,
+    )
+    hep.histplot(htype1, yerr=False, alpha=0.2, ax=axs[2])
+
+    hep.histplot(
+        [htype1, htype1, htype1],
+        ax=axs[3],
+        xoffsets=True,
+        xerr=[0.2, 0.5, 1],
+        histtype="errorbar",
+        alpha=1,
+    )
+    hep.histplot(htype1, yerr=False, alpha=0.2, ax=axs[3])
+    return fig