plothist 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

plothist/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.4.0'
-__version_tuple__ = version_tuple = (1, 4, 0)
+__version__ = version = '1.5.0'
+__version_tuple__ = version_tuple = (1, 5, 0)

plothist/comparison.py

@@ -1,12 +1,13 @@
 from __future__ import annotations
 
+import boost_histogram as bh
 import numpy as np
 from scipy import stats
 
 from plothist.histogramming import _check_counting_histogram
 
 
-def _check_uncertainty_type(uncertainty_type):
+def _check_uncertainty_type(uncertainty_type: str) -> None:
     """
     Check that the uncertainty type is valid.
 
@@ -27,13 +28,13 @@ def _check_uncertainty_type(uncertainty_type):
         )
 
 
-def _is_unweighted(hist):
+def _is_unweighted(hist: bh.Histogram) -> bool:
     """
     Check whether a histogram is unweighted.
 
     Parameters
     ----------
-    hist : boost_histogram.Histogram
+    hist : bh.Histogram
         The histogram to check.
 
     Returns
@@ -44,7 +45,9 @@ def _is_unweighted(hist):
     return np.allclose(hist.variances(), hist.values())
 
 
-def get_asymmetrical_uncertainties(hist):
+def get_asymmetrical_uncertainties(
+    hist: bh.Histogram,
+) -> tuple[np.ndarray, np.ndarray]:
     """
     Get Poisson asymmetrical uncertainties for a histogram via a frequentist approach based on a confidence-interval computation.
     Asymmetrical uncertainties can only be computed for an unweighted histogram, because the bin contents of a weighted histogram do not follow a Poisson distribution.
@@ -52,14 +55,14 @@ def get_asymmetrical_uncertainties(hist):
 
     Parameters
     ----------
-    hist : boost_histogram.Histogram
+    hist : bh.Histogram
         The histogram.
 
     Returns
     -------
-    uncertainties_low : numpy.ndarray
+    uncertainties_low : np.ndarray
         The lower uncertainties.
-    uncertainties_high : numpy.ndarray
+    uncertainties_high : np.ndarray
         The upper uncertainties.
 
     Raise
@@ -83,13 +86,13 @@ def get_asymmetrical_uncertainties(hist):
     return uncertainties_low, uncertainties_high
 
 
-def _check_binning_consistency(hist_list):
+def _check_binning_consistency(hist_list: list[bh.Histogram]) -> None:
     """
     Check that all the histograms in the provided list share the same definition of their bins.
 
     Parameters
     ----------
-    hist_list : list of boost_histogram.Histogram
+    hist_list : list[bh.Histogram]
         The list of histograms to check.
 
     Raise
@@ -106,15 +109,15 @@ def _check_binning_consistency(hist_list):
                 raise ValueError("The bins of the histograms must be equal.")
 
 
-def get_ratio_variances(h1, h2):
+def get_ratio_variances(h1: bh.Histogram, h2: bh.Histogram) -> np.ndarray:
     """
     Calculate the variances of the ratio of two uncorrelated histograms (h1/h2).
 
     Parameters
     ----------
-    h1 : boost_histogram.Histogram
+    h1 : bh.Histogram
         The first histogram.
-    h2 : boost_histogram.Histogram
+    h2 : bh.Histogram
         The second histogram.
 
     Returns
@@ -131,38 +134,39 @@ def get_ratio_variances(h1, h2):
     _check_counting_histogram(h1)
     _check_counting_histogram(h2)
 
-    np.seterr(divide="ignore", invalid="ignore")
-    ratio_variances = np.where(
-        h2.values() != 0,
-        h1.variances() / h2.values() ** 2
-        + h2.variances() * h1.values() ** 2 / h2.values() ** 4,
-        np.nan,
-    )
-    np.seterr(divide="warn", invalid="warn")
-
-    return ratio_variances
+    with np.errstate(divide="ignore", invalid="ignore"):
+        return np.where(
+            h2.values() != 0,
+            h1.variances() / h2.values() ** 2
+            + h2.variances() * h1.values() ** 2 / h2.values() ** 4,
+            np.nan,
+        )
 
 
-def get_pull(h1, h2, h1_uncertainty_type="symmetrical"):
+def get_pull(
+    h1: bh.Histogram,
+    h2: bh.Histogram,
+    h1_uncertainty_type: str = "symmetrical",
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
     """
     Compute the pull between two histograms.
 
     Parameters
     ----------
-    h1 : boost_histogram.Histogram
+    h1 : bh.Histogram
         The first histogram.
-    h2 : boost_histogram.Histogram
+    h2 : bh.Histogram
         The second histogram.
     h1_uncertainty_type : str, optional
         What kind of bin uncertainty to use for h1: "symmetrical" for the Poisson standard deviation derived from the variance stored in the histogram object, "asymmetrical" for asymmetrical uncertainties based on a Poisson confidence interval. Default is "symmetrical".
 
     Returns
     -------
-    pull_values : numpy.ndarray
+    pull_values : np.ndarray
         The pull values.
-    pull_uncertainties_low : numpy.ndarray
+    pull_uncertainties_low : np.ndarray
         The lower uncertainties on the pull. Always ones.
-    pull_uncertainties_high : numpy.ndarray
+    pull_uncertainties_high : np.ndarray
         The upper uncertainties on the pull. Always ones.
     """
     _check_uncertainty_type(h1_uncertainty_type)
@@ -195,26 +199,30 @@ def get_pull(h1, h2, h1_uncertainty_type="symmetrical"):
     )
 
 
-def get_difference(h1, h2, h1_uncertainty_type="symmetrical"):
+def get_difference(
+    h1: bh.Histogram,
+    h2: bh.Histogram,
+    h1_uncertainty_type: str = "symmetrical",
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
     """
     Compute the difference between two histograms.
 
     Parameters
     ----------
-    h1 : boost_histogram.Histogram
+    h1 : bh.Histogram
         The first histogram.
-    h2 : boost_histogram.Histogram
+    h2 : bh.Histogram
         The second histogram.
     h1_uncertainty_type : str, optional
         What kind of bin uncertainty to use for h1: "symmetrical" for the Poisson standard deviation derived from the variance stored in the histogram object, "asymmetrical" for asymmetrical uncertainties based on a Poisson confidence interval. Default is "symmetrical".
 
     Returns
     -------
-    difference_values : numpy.ndarray
+    difference_values : np.ndarray
         The difference values.
-    difference_uncertainties_low : numpy.ndarray
+    difference_uncertainties_low : np.ndarray
         The lower uncertainties on the difference.
-    difference_uncertainties_high : numpy.ndarray
+    difference_uncertainties_high : np.ndarray
         The upper uncertainties on the difference.
     """
     _check_uncertainty_type(h1_uncertainty_type)
@@ -240,7 +248,7 @@ def get_difference(h1, h2, h1_uncertainty_type="symmetrical"):
     )
 
 
-def get_efficency(h1, h2):
+def get_efficiency(h1: bh.Histogram, h2: bh.Histogram) -> tuple[np.ndarray, np.ndarray]:
     """
     Calculate the ratio of two correlated histograms (h1/h2), in which the entries of h1 are a subsample of the entries of h2.
     The variances are calculated according to the formula given in :ref:`documentation-statistics-label`.
@@ -253,16 +261,16 @@ def get_efficency(h1, h2):
 
     Parameters
     ----------
-    h1 : boost_histogram.Histogram
+    h1 : bh.Histogram
         The first histogram.
-    h2 : boost_histogram.Histogram
+    h2 : bh.Histogram
         The second histogram.
 
     Returns
     -------
-    efficiency_values : numpy.ndarray
+    efficiency_values : np.ndarray
         The efficiency values.
-    efficiency_uncertainties : numpy.ndarray
+    efficiency_uncertainties : np.ndarray
         The uncertainties on the efficiency values.
 
     Raises
@@ -303,23 +311,23 @@ def get_efficency(h1, h2):
     return efficiency_values, np.sqrt(efficiency_variances)
 
 
-def get_asymmetry(h1, h2):
+def get_asymmetry(h1: bh.Histogram, h2: bh.Histogram) -> tuple[np.ndarray, np.ndarray]:
     """
     Get the asymmetry between two histograms h1 and h2, defined as (h1 - h2) / (h1 + h2).
     Only symmetrical uncertainties are supported.
 
     Parameters
     ----------
-    h1 : boost_histogram.Histogram
+    h1 : bh.Histogram
         The first histogram.
-    h2 : boost_histogram.Histogram
+    h2 : bh.Histogram
         The second histogram.
 
     Returns
     -------
-    asymmetry_values : numpy.ndarray
+    asymmetry_values : np.ndarray
         The asymmetry values.
-    asymmetry_uncertainties : numpy.ndarray
+    asymmetry_uncertainties : np.ndarray
         The uncertainties on the asymmetry.
     """
     _check_binning_consistency([h1, h2])
@@ -339,19 +347,19 @@ def get_asymmetry(h1, h2):
 
 
 def get_ratio(
-    h1,
-    h2,
-    h1_uncertainty_type="symmetrical",
-    ratio_uncertainty_type="uncorrelated",
-):
+    h1: bh.Histogram,
+    h2: bh.Histogram,
+    h1_uncertainty_type: str = "symmetrical",
+    ratio_uncertainty_type: str = "uncorrelated",
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
     """
     Compute the ratio h1/h2 between two uncorrelated histograms h1 and h2.
 
     Parameters
     ----------
-    h1 : boost_histogram.Histogram
+    h1 : bh.Histogram
         The numerator histogram.
-    h2 : boost_histogram.Histogram
+    h2 : bh.Histogram
         The denominator histogram.
     h1_uncertainty_type : str, optional
         What kind of bin uncertainty to use for h1: "symmetrical" for the Poisson standard deviation derived from the variance stored in the histogram object, "asymmetrical" for asymmetrical uncertainties based on a Poisson confidence interval. Default is "symmetrical".
@@ -363,11 +371,11 @@ def get_ratio(
 
     Returns
     -------
-    ratio_values : numpy.ndarray
+    ratio_values : np.ndarray
         The ratio values.
-    ratio_uncertainties_low : numpy.ndarray
+    ratio_uncertainties_low : np.ndarray
         The lower uncertainties on the ratio.
-    ratio_uncertainties_high : numpy.ndarray
+    ratio_uncertainties_high : np.ndarray
         The upper uncertainties on the ratio.
 
     Raises
@@ -419,19 +427,19 @@ def get_ratio(
 
 
 def get_comparison(
-    h1,
-    h2,
-    comparison,
-    h1_uncertainty_type="symmetrical",
-):
+    h1: bh.Histogram,
+    h2: bh.Histogram,
+    comparison: str,
+    h1_uncertainty_type: str = "symmetrical",
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
     """
     Compute the comparison between two histograms.
 
     Parameters
     ----------
-    h1 : boost_histogram.Histogram
+    h1 : bh.Histogram
         The first histogram for comparison.
-    h2 : boost_histogram.Histogram
+    h2 : bh.Histogram
         The second histogram for comparison.
     comparison : str
         The type of comparison ("ratio", "split_ratio", "pull", "difference", "relative_difference", "efficiency", or "asymmetry").
@@ -443,11 +451,11 @@ def get_comparison(
 
     Returns
     -------
-    values : numpy.ndarray
+    values : np.ndarray
         The comparison values.
-    lower_uncertainties : numpy.ndarray
+    lower_uncertainties : np.ndarray
         The lower uncertainties on the comparison values.
-    upper_uncertainties : numpy.ndarray
+    upper_uncertainties : np.ndarray
         The upper uncertainties on the comparison values.
 
     Raises
@@ -462,49 +470,47 @@ def get_comparison(
     _check_counting_histogram(h1)
     _check_counting_histogram(h2)
 
-    np.seterr(divide="ignore", invalid="ignore")
-
-    if comparison == "ratio":
-        values, lower_uncertainties, upper_uncertainties = get_ratio(
-            h1, h2, h1_uncertainty_type, "uncorrelated"
-        )
-    elif comparison == "split_ratio":
-        values, lower_uncertainties, upper_uncertainties = get_ratio(
-            h1, h2, h1_uncertainty_type, "split"
-        )
-    elif comparison == "relative_difference":
-        values, lower_uncertainties, upper_uncertainties = get_ratio(
-            h1, h2, h1_uncertainty_type, "uncorrelated"
-        )
-        values -= 1  # relative difference is ratio-1
-    elif comparison == "pull":
-        values, lower_uncertainties, upper_uncertainties = get_pull(
-            h1, h2, h1_uncertainty_type
-        )
-    elif comparison == "difference":
-        values, lower_uncertainties, upper_uncertainties = get_difference(
-            h1, h2, h1_uncertainty_type
-        )
-    elif comparison == "asymmetry":
-        if h1_uncertainty_type == "asymmetrical":
-            raise ValueError(
-                "Asymmetrical uncertainties are not supported for the asymmetry comparison."
+    with np.errstate(divide="ignore", invalid="ignore"):
+        if comparison == "ratio":
+            values, lower_uncertainties, upper_uncertainties = get_ratio(
+                h1, h2, h1_uncertainty_type, "uncorrelated"
             )
-        values, uncertainties = get_asymmetry(h1, h2)
-        lower_uncertainties = uncertainties
-        upper_uncertainties = uncertainties
-    elif comparison == "efficiency":
-        if h1_uncertainty_type == "asymmetrical":
+        elif comparison == "split_ratio":
+            values, lower_uncertainties, upper_uncertainties = get_ratio(
+                h1, h2, h1_uncertainty_type, "split"
+            )
+        elif comparison == "relative_difference":
+            values, lower_uncertainties, upper_uncertainties = get_ratio(
+                h1, h2, h1_uncertainty_type, "uncorrelated"
+            )
+            values -= 1  # relative difference is ratio-1
+        elif comparison == "pull":
+            values, lower_uncertainties, upper_uncertainties = get_pull(
+                h1, h2, h1_uncertainty_type
+            )
+        elif comparison == "difference":
+            values, lower_uncertainties, upper_uncertainties = get_difference(
+                h1, h2, h1_uncertainty_type
+            )
+        elif comparison == "asymmetry":
+            if h1_uncertainty_type == "asymmetrical":
+                raise ValueError(
+                    "Asymmetrical uncertainties are not supported for the asymmetry comparison."
+                )
+            values, uncertainties = get_asymmetry(h1, h2)
+            lower_uncertainties = uncertainties
+            upper_uncertainties = uncertainties
+        elif comparison == "efficiency":
+            if h1_uncertainty_type == "asymmetrical":
+                raise ValueError(
+                    "Asymmetrical uncertainties are not supported in an efficiency computation."
+                )
+            values, uncertainties = get_efficiency(h1, h2)
+            lower_uncertainties = uncertainties
+            upper_uncertainties = uncertainties
+        else:
             raise ValueError(
-                "Asymmetrical uncertainties are not supported in an efficiency computation."
+                f"{comparison} not available as a comparison ('ratio', 'split_ratio', 'pull', 'difference', 'relative_difference', 'asymmetry' or 'efficiency')."
             )
-        values, uncertainties = get_efficency(h1, h2)
-        lower_uncertainties = uncertainties
-        upper_uncertainties = uncertainties
-    else:
-        raise ValueError(
-            f"{comparison} not available as a comparison ('ratio', 'split_ratio', 'pull', 'difference', 'relative_difference', 'asymmetry' or 'efficiency')."
-        )
-    np.seterr(divide="warn", invalid="warn")
 
     return values, lower_uncertainties, upper_uncertainties

plothist/examples/1d_hist/1d_comparison_asymmetry.py

@@ -0,0 +1,37 @@
+"""
+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))
+
+from plothist import make_hist
+
+h1 = make_hist(x1, bins=50, range=x_range)
+h2 = make_hist(x2, bins=50, range=x_range)
+
+###
+from plothist 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")

plothist/examples/1d_hist/1d_comparison_difference.py

@@ -0,0 +1,40 @@
+"""
+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))
+
+from plothist import make_hist
+
+h1 = make_hist(x1, bins=50, range=x_range)
+h2 = make_hist(x2, bins=50, range=x_range)
+
+###
+from plothist 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")

plothist/examples/1d_hist/1d_comparison_efficiency.py

@@ -0,0 +1,37 @@
+"""
+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))
+
+from plothist import make_hist
+
+h_sample = make_hist(x_sample, bins=50, range=x_range)
+h_total = make_hist(x_total, bins=50, range=x_range)
+
+###
+from plothist 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")

plothist/examples/1d_hist/1d_comparison_only_efficiency.py

@@ -0,0 +1,33 @@
+"""
+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))
+
+from plothist import make_hist
+
+h_sample = make_hist(x_sample, bins=50, range=x_range)
+h_total = make_hist(x_total, bins=50, range=x_range)
+
+###
+import matplotlib.pyplot as plt
+
+from plothist 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")

plothist/examples/1d_hist/1d_comparison_pull.py

@@ -0,0 +1,37 @@
+"""
+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))
+
+from plothist import make_hist
+
+h1 = make_hist(x1, bins=50, range=x_range)
+h2 = make_hist(x2, bins=50, range=x_range)
+
+###
+from plothist 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")

plothist/examples/1d_hist/1d_comparison_ratio.py

@@ -0,0 +1,37 @@
+"""
+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))
+
+from plothist import make_hist
+
+h1 = make_hist(x1, bins=50, range=x_range)
+h2 = make_hist(x2, bins=50, range=x_range)
+
+###
+from plothist 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")

plothist/examples/1d_hist/1d_comparison_relative_difference.py

@@ -0,0 +1,37 @@
+"""
+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))
+
+from plothist import make_hist
+
+h1 = make_hist(x1, bins=50, range=x_range)
+h2 = make_hist(x2, bins=50, range=x_range)
+
+###
+from plothist 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")