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

plothist/__init__.py

@@ -1,115 +1,107 @@
+from __future__ import annotations
+
+from ._version import version as __version__
+from .comparison import (
+    get_asymmetrical_uncertainties,
+    get_comparison,
+    get_difference,
+    get_pull,
+    get_ratio,
+    get_ratio_variances,
+)
+from .histogramming import (
+    create_axis,
+    flatten_2d_hist,
+    make_2d_hist,
+    make_hist,
+)
+from .plothist_style import (
+    add_luminosity,
+    add_text,
+    cubehelix_palette,
+    get_color_palette,
+    plot_reordered_legend,
+    set_fitting_ylabel_fontsize,
+    set_style,
+)
 from .plotters import (
     create_comparison_figure,
-    plot_hist,
     plot_2d_hist,
     plot_2d_hist_with_projections,
+    plot_comparison,
+    plot_data_model_comparison,
     plot_error_hist,
+    plot_function,
+    plot_hist,
     plot_hist_uncertainties,
+    plot_model,
     plot_two_hist_comparison,
-    plot_comparison,
     savefig,
-    plot_data_model_comparison,
-    plot_model,
-    plot_function,
 )
-
-from .histogramming import (
-    create_axis,
-    make_hist,
-    make_2d_hist,
-    flatten_2d_hist,
-)
-
 from .variable_registry import (
     create_variable_registry,
     get_variable_from_registry,
-    update_variable_registry,
     remove_variable_registry_parameters,
+    update_variable_registry,
     update_variable_registry_ranges,
 )
 
-from .comparison import (
-    get_asymmetrical_uncertainties,
-    get_comparison,
-    get_pull,
-    get_difference,
-    get_ratio,
-    get_ratio_variances,
-)
-
-from .plothist_style import (
-    set_style,
-    cubehelix_palette,
-    get_color_palette,
-    set_fitting_ylabel_fontsize,
-    add_text,
-    add_luminosity,
-    plot_reordered_legend,
-)
-
-from .get_dummy_data import get_dummy_data
-
 __all__ = [
     "__version__",
+    "add_luminosity",
+    "add_text",
+    "create_axis",
+    "create_comparison_figure",
     "create_variable_registry",
+    "cubehelix_palette",
+    "flatten_2d_hist",
+    "get_asymmetrical_uncertainties",
+    "get_color_palette",
+    "get_comparison",
+    "get_difference",
+    "get_pull",
+    "get_ratio",
+    "get_ratio_variances",
     "get_variable_from_registry",
-    "update_variable_registry",
-    "remove_variable_registry_parameters",
-    "update_variable_registry_ranges",
-    "create_comparison_figure",
-    "create_axis",
-    "make_hist",
     "make_2d_hist",
-    "plot_hist",
+    "make_hist",
     "plot_2d_hist",
     "plot_2d_hist_with_projections",
+    "plot_comparison",
+    "plot_data_model_comparison",
     "plot_error_hist",
+    "plot_function",
+    "plot_hist",
     "plot_hist_uncertainties",
+    "plot_model",
+    "plot_reordered_legend",
     "plot_two_hist_comparison",
-    "plot_comparison",
+    "remove_variable_registry_parameters",
     "savefig",
-    "plot_data_model_comparison",
-    "plot_model",
-    "plot_function",
-    "add_luminosity",
-    "get_asymmetrical_uncertainties",
-    "set_style",
-    "cubehelix_palette",
-    "get_color_palette",
     "set_fitting_ylabel_fontsize",
-    "add_text",
-    "get_asymmetrical_uncertainties",
-    "get_comparison",
-    "get_pull",
-    "get_difference",
-    "get_ratio",
-    "get_ratio_variances",
-    "flatten_2d_hist",
-    "plot_reordered_legend",
-    "get_dummy_data",
+    "set_style",
+    "update_variable_registry",
+    "update_variable_registry_ranges",
 ]
 
 
 # Get style file and use it
-import matplotlib.pyplot as plt
 from importlib.resources import files
 
+import matplotlib.pyplot as plt
+
 style_file = files("plothist").joinpath("default_style.mplstyle")
 plt.style.use(style_file)
 
-# Check the fonts
-from matplotlib.font_manager import findfont
-import warnings
+# Install fonts
+from importlib import resources
+
+import matplotlib.font_manager as fm
 
-for font_type in ["Math", "Sans", "Roman"]:
-    try:
-        findfont(f"Latin Modern {font_type}", fallback_to_default=False)
-    except:
-        warnings.warn(
-            "The recommended fonts to use plothist were not found. You can install them by typing 'install_latin_modern_fonts' in your terminal. If it still does not work, please check the documentation at https://plothist.readthedocs.io/en/latest/usage/font_installation.html",
-            stacklevel=3,
-        )
-        break
+with resources.as_file(resources.files("plothist_utils") / "fonts") as font_path:
+    font_files = fm.findSystemFonts(fontpaths=[str(font_path)])
+    for font in font_files:
+        fm.fontManager.addfont(font)
 
 # Check version of boost_histogram
 import boost_histogram as bh

plothist/_version.py

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '1.5.0'
+__version_tuple__ = version_tuple = (1, 5, 0)

plothist/_version.pyi

@@ -0,0 +1,2 @@
+version: str
+version_tuple: tuple[int, int, int] | tuple[int, int, int, str, str]

plothist/comparison.py

@@ -1,9 +1,13 @@
+from __future__ import annotations
+
+import boost_histogram as bh
 import numpy as np
-import scipy.stats as stats
+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.
 
@@ -24,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
@@ -41,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.
@@ -49,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
@@ -80,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
@@ -103,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
@@ -128,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)
@@ -192,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)
@@ -237,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`.
@@ -250,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
@@ -300,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])
@@ -336,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".
@@ -360,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
@@ -416,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").
@@ -440,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
@@ -459,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")