feat: add comparison plotters (#580)

* feat: add comparison plotter functions

Co-authored-by: cyrraz <[email protected]>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* feat: added model and data/model comparison plotting functions

Co-authored-by: cyrraz <[email protected]>

* test: add examples of 1d histogram comparisons and test them

    ---------

    Co-authored-by: Tristan Fillinger <[email protected]>

* test: fix path to image examples

Co-authored-by: Tristan Fillinger <[email protected]>

* chore: silence some ruff errors

Co-authored-by: Tristan Fillinger <[email protected]>

* test: add examples of data model comparisons and test them

Co-authored-by: cyrraz <[email protected]>

* refactor: improve code formatting and organization in comparison scripts

* ci: update macOS-14 Python version to 3.9 to resolve conflicts with plothist_utils

* fix: switch print to logging in docs

---------

Co-authored-by: cyrraz <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Andrzej Novak <[email protected]>

Author: 4 people

.github/workflows/ci.yml

@@ -18,12 +18,12 @@ jobs:
       fail-fast: false
       matrix:
         runs-on: [ ubuntu-latest ]
-        python-version: [ "3.8", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"] # "3.8" conflicts with plothist_utils for now
         include:  # testing the last "reasonable supported" version
           - runs-on: macOS-13
             python-version: "3.9"
           - runs-on: macOS-14
-            python-version: "3.8"  # min version available for Apple silicon
+            python-version: "3.9"  # min version available for Apple silicon # changed to 3.9 as conflicts with plothist_utils for now
           - runs-on: windows-latest
             python-version: "3.9"
 

.gitignore

@@ -4,6 +4,7 @@ src/mplhep/_version.py
 result_images/
 test/
 .nox/
+.vscode/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

docs/source/conf.py

@@ -9,6 +9,7 @@
 # -- Path setup --------------------------------------------------------------
 import importlib
 import inspect
+import logging
 import os
 import subprocess
 import sys
@@ -152,7 +153,7 @@ def linkcode_resolve(domain, info):
 
 with Path(here / "_static/bkg_sig_plot.yaml").resolve().open() as f:
     plotdata = yaml.load(f, Loader=yaml.FullLoader)
-print("Creating gallery plots on the fly... (this takes a minute or two)")
+logging.info("Creating gallery plots on the fly... (this takes a minute or two)")
 for style in allstyle:
     plt.style.use("default")  # make sure it's reset
     plt.style.use(getattr(mplhep.style, style))

examples/1d_histograms/1d_comparison_asymmetry.py

@@ -0,0 +1,41 @@
+"""
+Asymmetry
+=========
+
+Compare two 1D histograms using the asymmetry comparison [(h1-h2)/(h1+h2)].
+"""
+
+from plothist_utils import get_dummy_data
+
+df = get_dummy_data()
+
+name = "variable_1"
+
+x1 = df[name][df["category"] == 2]
+x2 = df[name][df["category"] == 3]
+
+x_range = (min(*x1, *x2), max(*x1, *x2))
+
+import hist
+from hist import Hist
+
+h1 = Hist(hist.axis.Regular(50, x_range[0], x_range[1]))
+h2 = Hist(hist.axis.Regular(50, x_range[0], x_range[1]))
+
+h1.fill(x1)
+h2.fill(x2)
+
+###
+from mplhep import plot_two_hist_comparison
+
+fig, ax_main, ax_comparison = plot_two_hist_comparison(
+    h1,
+    h2,
+    xlabel=name,
+    ylabel="Entries",
+    h1_label=r"$\mathbfit{h}_1$",
+    h2_label=r"$\mathbfit{h}_2$",
+    comparison="asymmetry",  # <--
+)
+
+fig.savefig("1d_comparison_asymmetry.svg", bbox_inches="tight")

examples/1d_histograms/1d_comparison_difference.py

@@ -0,0 +1,44 @@
+"""
+Difference
+==========
+
+Compare two 1D histograms using the difference [h1-h2].
+"""
+
+from plothist_utils import get_dummy_data
+
+df = get_dummy_data()
+
+name = "variable_1"
+
+x1 = df[name][df["category"] == 2]
+x2 = df[name][df["category"] == 3]
+
+x_range = (min(*x1, *x2), max(*x1, *x2))
+
+import hist
+from hist import Hist
+
+h1 = Hist(hist.axis.Regular(50, x_range[0], x_range[1]))
+h2 = Hist(hist.axis.Regular(50, x_range[0], x_range[1]))
+
+h1.fill(x1)
+h2.fill(x2)
+
+###
+from mplhep import add_text, plot_two_hist_comparison
+
+fig, ax_main, ax_comparison = plot_two_hist_comparison(
+    h1,
+    h2,
+    xlabel=name,
+    ylabel="Entries",
+    h1_label=r"$\mathcal{H}_{1}$",
+    h2_label=r"$\mathcal{H}_{2}$",
+    comparison="difference",  # <--
+)
+
+add_text("Comparison of two hist with difference plot", ax=ax_main)
+add_text("Difference ax", x="right", ax=ax_comparison)
+
+fig.savefig("1d_comparison_difference.svg", bbox_inches="tight")

examples/1d_histograms/1d_comparison_efficiency.py

@@ -0,0 +1,41 @@
+"""
+Efficiency
+==========
+
+Compare the ratio between two histograms h1 and h2 when the entries of h1 are a subset of the entries of h2.
+"""
+
+from plothist_utils import get_dummy_data
+
+df = get_dummy_data()
+
+name = "variable_1"
+
+x_total = df[name][df["category"] == 2]
+x_sample = x_total[: int(len(x_total) * 0.75)]
+
+x_range = (min(x_total), max(x_total))
+
+import hist
+from hist import Hist
+
+h_sample = Hist(hist.axis.Regular(50, x_range[0], x_range[1]))
+h_total = Hist(hist.axis.Regular(50, x_range[0], x_range[1]))
+
+h_sample.fill(x_sample)
+h_total.fill(x_total)
+
+###
+from mplhep import plot_two_hist_comparison
+
+fig, ax_main, ax_comparison = plot_two_hist_comparison(
+    h_sample,
+    h_total,
+    xlabel=name,
+    ylabel="Entries",
+    h1_label=r"$\mathit{H}_{Sample}$",
+    h2_label=r"$\mathit{H}_{Total}$",
+    comparison="efficiency",  # <--
+)
+
+fig.savefig("1d_comparison_efficiency.svg", bbox_inches="tight")

examples/1d_histograms/1d_comparison_only_efficiency.py

@@ -0,0 +1,37 @@
+"""
+Comparison
+==========
+
+Plot the comparison between two 1D histograms.
+"""
+
+from plothist_utils import get_dummy_data
+
+df = get_dummy_data()
+
+name = "variable_1"
+
+x_total = df[name][df["category"] == 2]
+x_sample = x_total[: int(len(x_total) * 0.75)]
+
+x_range = (min(x_total), max(x_total))
+
+import hist
+from hist import Hist
+
+h_sample = Hist(hist.axis.Regular(50, x_range[0], x_range[1]))
+h_total = Hist(hist.axis.Regular(50, x_range[0], x_range[1]))
+
+h_sample.fill(x_sample)
+h_total.fill(x_total)
+
+###
+import matplotlib.pyplot as plt
+
+from mplhep import plot_comparison
+
+fig, ax = plt.subplots()
+
+plot_comparison(h_sample, h_total, ax=ax, xlabel=name, comparison="efficiency")
+
+fig.savefig("1d_comparison_only_efficiency.svg", bbox_inches="tight")

examples/1d_histograms/1d_comparison_pull.py

@@ -0,0 +1,41 @@
+"""
+Pull
+====
+
+Compare two 1D histograms using the pull method.
+"""
+
+from plothist_utils import get_dummy_data
+
+df = get_dummy_data()
+
+name = "variable_1"
+
+x1 = df[name][df["category"] == 2]
+x2 = df[name][df["category"] == 3]
+
+x_range = (min(*x1, *x2), max(*x1, *x2))
+
+import hist
+from hist import Hist
+
+h1 = Hist(hist.axis.Regular(50, x_range[0], x_range[1]))
+h2 = Hist(hist.axis.Regular(50, x_range[0], x_range[1]))
+
+h1.fill(x1)
+h2.fill(x2)
+
+###
+from mplhep import plot_two_hist_comparison
+
+fig, ax_main, ax_comparison = plot_two_hist_comparison(
+    h1,
+    h2,
+    xlabel=name,
+    ylabel="Entries",
+    h1_label=r"$h_1$",
+    h2_label=r"$h_2$",
+    comparison="pull",  # <---
+)
+
+fig.savefig("1d_comparison_pull.svg", bbox_inches="tight")

examples/1d_histograms/1d_comparison_ratio.py

@@ -0,0 +1,41 @@
+"""
+Ratio
+=====
+
+Compare two 1D histograms using the ratio [h1/h2].
+"""
+
+from plothist_utils import get_dummy_data
+
+df = get_dummy_data()
+
+name = "variable_1"
+
+x1 = df[name][df["category"] == 2]
+x2 = df[name][df["category"] == 3]
+
+x_range = (min(*x1, *x2), max(*x1, *x2))
+
+import hist
+from hist import Hist
+
+h1 = Hist(hist.axis.Regular(50, x_range[0], x_range[1]))
+h2 = Hist(hist.axis.Regular(50, x_range[0], x_range[1]))
+
+h1.fill(x1)
+h2.fill(x2)
+
+###
+from mplhep import plot_two_hist_comparison
+
+# Default comparison is ratio
+fig, ax_main, ax_comparison = plot_two_hist_comparison(
+    h1,
+    h2,
+    xlabel=name,
+    ylabel="Entries",
+    h1_label="h1",
+    h2_label="h2",
+)
+
+fig.savefig("1d_comparison_ratio.svg", bbox_inches="tight")

examples/1d_histograms/1d_comparison_relative_difference.py

@@ -0,0 +1,41 @@
+"""
+Relative difference
+===================
+
+Compare two 1D histograms using the relative difference [(h1-h2)/h2].
+"""
+
+from plothist_utils import get_dummy_data
+
+df = get_dummy_data()
+
+name = "variable_1"
+
+x1 = df[name][df["category"] == 2]
+x2 = df[name][df["category"] == 3]
+
+x_range = (min(*x1, *x2), max(*x1, *x2))
+
+import hist
+from hist import Hist
+
+h1 = Hist(hist.axis.Regular(50, x_range[0], x_range[1]))
+h2 = Hist(hist.axis.Regular(50, x_range[0], x_range[1]))
+
+h1.fill(x1)
+h2.fill(x2)
+
+###
+from mplhep import plot_two_hist_comparison
+
+fig, ax_main, ax_comparison = plot_two_hist_comparison(
+    h1,
+    h2,
+    xlabel=name,
+    ylabel="Entries",
+    h1_label=r"$\mathbf{H\,\,1}$",
+    h2_label=r"$\mathbf{H\,\,2}$",
+    comparison="relative_difference",  # <--
+)
+
+fig.savefig("1d_comparison_relative_difference.svg", bbox_inches="tight")