plothist 1.5.0__tar.gz → 1.6.0__tar.gz

{plothist-1.5.0 → plothist-1.6.0}/.gitignore

@@ -15,6 +15,7 @@ temp_img/
 html/
 sg_execution_times.rst
 docs/examples/*/*.svg
+src/plothist/examples/*/*.svg
 example_gallery/
 .svg_metadata.yaml
 tests/*.yaml

{plothist-1.5.0 → plothist-1.6.0}/.pre-commit-config.yaml

@@ -30,7 +30,7 @@ repos:
         args: ["--pytest-test-first"]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.2
+    rev: v0.12.7
     hooks:
       - id: ruff
         args: ["--fix", "--show-fixes"]
@@ -50,7 +50,7 @@ repos:
         args: ["--verbose"]
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.16.1
+    rev: v1.17.1
     hooks:
       - id: mypy
         files: src
@@ -73,6 +73,6 @@ repos:
       - id: check-github-workflows
 
   - repo: https://github.com/henryiii/validate-pyproject-schema-store
-    rev: 2025.06.23
+    rev: 2025.07.28
     hooks:
       - id: validate-pyproject

{plothist-1.5.0 → plothist-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plothist
-Version: 1.5.0
+Version: 1.6.0
 Summary: Plot histograms in a scalable way and a beautiful style.
 Project-URL: Homepage, https://github.com/cyrraz/plothist
 Project-URL: Documentation, https://plothist.readthedocs.io/

{plothist-1.5.0 → plothist-1.6.0}/codecov.yml

@@ -1,6 +1,3 @@
 comment: false
 
 github_checks: false
-
-ignore:
-  - "src/plothist/scripts"

{plothist-1.5.0 → plothist-1.6.0}/docs/conf.py

@@ -1,5 +1,8 @@
 import sys
 
+from sphinx_gallery.scrapers import matplotlib_scraper
+from sphinx_gallery.sorting import ExplicitOrder
+
 import plothist
 
 #
@@ -175,9 +178,6 @@ def reset_mpl(gallery_conf, fname):
     set_style("default")
 
 
-from sphinx_gallery.scrapers import matplotlib_scraper
-
-
 class matplotlib_svg_scraper:
     def __repr__(self):
         return self.__class__.__name__
@@ -186,8 +186,6 @@ class matplotlib_svg_scraper:
         return matplotlib_scraper(*args, format="svg", bbox_inches="tight", **kwargs)
 
 
-from sphinx_gallery.sorting import ExplicitOrder
-
 sphinx_gallery_conf = {
     # path to your example scripts
     "examples_dirs": ["../src/plothist/examples"],

plothist-1.6.0/docs/documentation/statistics.rst

@@ -0,0 +1,21 @@
+.. _documentation-statistics-label:
+
+===================
+Notes on statistics
+===================
+
+In the :func:`plot_error_hist() <plothist.plotters.plot_error_hist>` function, the represented uncertainties can be:
+
+- ``symmetrical``: use the square root of the variance of the histogram
+- ``asymmetrical``: frequentist approach based on a Poisson confidence interval (see `page 16 on this presentation <https://www.nikhef.nl/~ivov/Statistics/PoissonError/2017_05_15_PoissonError_LHCb_IvovanVulpen.pdf>`_)
+
+    - the upper limit on bins with no entries can be interpreted differently. By default, a one-sided 68% confidence bound is used. The behavior can be changed using the ``uncertainty_type = asymmetrical_double_sided_zeros``, which will use a two-sided 68% confidence bound.
+    - this method doesn't support weighted histograms. For more details, see the `note about uncertainties when the histogram entries are weighted <https://www.pp.rhul.ac.uk/~cowan/stat/notes/errors_with_weights.pdf>`_.
+
+.. image:: ../img/uncertainty_types.png
+   :alt: Simple error hist
+   :width: 500
+
+The uncertainty on the efficiency (ratio of two histograms h1 and h2 when the entries of h1 are a subset of the entries of h2) in :func:`get_efficiency() <plothist.comparison.get_efficiency>` is calculated following equation (19) of:
+
+- `T. Ullrich, Z. Xu, Treatment of Errors in Efficiency Calculations, arxiv: 0701199v1. <https://arxiv.org/pdf/physics/0701199v1.pdf>`_

{plothist-1.5.0 → plothist-1.6.0}/pyproject.toml

@@ -83,7 +83,10 @@ extend-select = [
     "PD",          # pandas-vet
 ]
 ignore = [
-    "E402",  # module level import not at top of file
     "NPY002",  # Replace legacy `np.random` call with `np.random.Generator`
+]
+[tool.ruff.lint.per-file-ignores]
+"src/plothist/examples/**/*.py" = [
+    "E402",  # module level import not at top of file
     "PD901",  # Avoid using the generic variable name `df` for DataFrames
 ]

{plothist-1.5.0 → plothist-1.6.0}/src/plothist/_version.py

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

{plothist-1.5.0 → plothist-1.6.0}/src/plothist/comparison.py

@@ -22,9 +22,16 @@ def _check_uncertainty_type(uncertainty_type: str) -> None:
         If the uncertainty type is not valid.
 
     """
-    if uncertainty_type not in ["symmetrical", "asymmetrical"]:
+    _valid_uncertainty_types = [
+        "symmetrical",
+        "asymmetrical",
+        "asymmetrical_double_sided_zeros",
+        "asymmetrical_one_sided_zeros",
+    ]
+
+    if uncertainty_type not in _valid_uncertainty_types:
         raise ValueError(
-            f"Uncertainty type {uncertainty_type} not valid. Must be 'symmetrical' or 'asymmetrical'."
+            f"Uncertainty type {uncertainty_type} not valid. Must be in {_valid_uncertainty_types}."
         )
 
 
@@ -42,11 +49,12 @@ def _is_unweighted(hist: bh.Histogram) -> bool:
     bool
         True if the histogram is unweighted, False otherwise.
     """
-    return np.allclose(hist.variances(), hist.values())
+    return np.allclose(hist.variances(), hist.values(), equal_nan=True)
 
 
 def get_asymmetrical_uncertainties(
     hist: bh.Histogram,
+    uncertainty_type: str = "asymmetrical",
 ) -> tuple[np.ndarray, np.ndarray]:
     """
     Get Poisson asymmetrical uncertainties for a histogram via a frequentist approach based on a confidence-interval computation.
@@ -57,6 +65,8 @@ def get_asymmetrical_uncertainties(
     ----------
     hist : bh.Histogram
         The histogram.
+    uncertainty_type : str, optional
+        The type of uncertainty to compute for bins with 0 entry. Default is "asymmetrical" (= "asymmetrical_one_sided_zeros"). Use "asymmetrical_double_sided_zeros" to have the double-sided definition. More information in :ref:`documentation-statistics-label`.
 
     Returns
     -------
@@ -72,16 +82,44 @@ def get_asymmetrical_uncertainties(
 
     """
     _check_counting_histogram(hist)
+    _check_uncertainty_type(uncertainty_type)
 
     if not _is_unweighted(hist):
         raise ValueError(
             "Asymmetrical uncertainties can only be computed for an unweighted histogram."
         )
-    conf_level = 0.682689492
-    alpha = 1.0 - conf_level
+
+    alpha = 1.0 - 0.682689492
+    tail_probability = alpha / 2
+
     n = hist.values()
-    uncertainties_low = n - stats.gamma.ppf(alpha / 2, n, scale=1)
-    uncertainties_high = stats.gamma.ppf(1 - alpha / 2, n + 1, scale=1) - n
+
+    lower_bound = np.zeros_like(n, dtype=float)
+    upper_bound = np.zeros_like(n, dtype=float)
+
+    # Two-sided Garwood intervals for n > 0
+    lower_bound[n > 0] = stats.gamma.ppf(q=tail_probability, a=n[n > 0], scale=1)
+    upper_bound[n > 0] = stats.gamma.ppf(
+        q=1 - tail_probability, a=n[n > 0] + 1, scale=1
+    )
+
+    if uncertainty_type == "asymmetrical_double_sided_zeros":
+        # Two-sided Garwood intervals for n == 0
+        upper_bound[n == 0] = stats.gamma.ppf(q=1 - tail_probability, a=1, scale=1)
+    elif uncertainty_type in ["asymmetrical_one_sided_zeros", "asymmetrical"]:
+        # One-sided upper limit for n == 0
+        upper_bound[n == 0] = stats.gamma.ppf(q=1 - 2 * tail_probability, a=1, scale=1)
+    else:
+        raise ValueError(
+            f"Invalid uncertainty type '{uncertainty_type}' for asymmetrical uncertainties."
+        )
+
+    # Compute asymmetric uncertainties
+    uncertainties_low = n - lower_bound
+    uncertainties_high = upper_bound - n
+
+    uncertainties_low = np.nan_to_num(uncertainties_low, nan=0.0)
+    uncertainties_high = np.nan_to_num(uncertainties_high, nan=0.0)
 
     return uncertainties_low, uncertainties_high
 
@@ -174,8 +212,10 @@ def get_pull(
     _check_counting_histogram(h1)
     _check_counting_histogram(h2)
 
-    if h1_uncertainty_type == "asymmetrical":
-        uncertainties_low, uncertainties_high = get_asymmetrical_uncertainties(h1)
+    if "asymmetrical" in h1_uncertainty_type:
+        uncertainties_low, uncertainties_high = get_asymmetrical_uncertainties(
+            h1, h1_uncertainty_type
+        )
         h1_variances = np.where(
             h1.values() >= h2.values(),
             uncertainties_low**2,
@@ -232,8 +272,10 @@ def get_difference(
 
     difference_values = h1.values() - h2.values()
 
-    if h1_uncertainty_type == "asymmetrical":
-        uncertainties_low, uncertainties_high = get_asymmetrical_uncertainties(h1)
+    if "asymmetrical" in h1_uncertainty_type:
+        uncertainties_low, uncertainties_high = get_asymmetrical_uncertainties(
+            h1, h1_uncertainty_type
+        )
 
         difference_uncertainties_low = np.sqrt(uncertainties_low**2 + h2.variances())
         difference_uncertainties_high = np.sqrt(uncertainties_high**2 + h2.variances())
@@ -390,11 +432,13 @@ def get_ratio(
 
     ratio_values = np.where(h2.values() != 0, h1.values() / h2.values(), np.nan)
 
-    if h1_uncertainty_type == "asymmetrical":
-        uncertainties_low, uncertainties_high = get_asymmetrical_uncertainties(h1)
+    if "asymmetrical" in h1_uncertainty_type:
+        uncertainties_low, uncertainties_high = get_asymmetrical_uncertainties(
+            h1, h1_uncertainty_type
+        )
 
     if ratio_uncertainty_type == "uncorrelated":
-        if h1_uncertainty_type == "asymmetrical":
+        if "asymmetrical" in h1_uncertainty_type:
             h1_high = h1.copy()
             h1_high[:] = np.c_[h1_high.values(), uncertainties_high**2]
             h1_low = h1.copy()
@@ -405,7 +449,7 @@ def get_ratio(
             ratio_uncertainties_low = np.sqrt(get_ratio_variances(h1, h2))
             ratio_uncertainties_high = ratio_uncertainties_low
     elif ratio_uncertainty_type == "split":
-        if h1_uncertainty_type == "asymmetrical":
+        if "asymmetrical" in h1_uncertainty_type:
             ratio_uncertainties_low = uncertainties_low / h2.values()
             ratio_uncertainties_high = uncertainties_high / h2.values()
         else:
@@ -493,7 +537,7 @@ def get_comparison(
                 h1, h2, h1_uncertainty_type
             )
         elif comparison == "asymmetry":
-            if h1_uncertainty_type == "asymmetrical":
+            if "asymmetrical" in h1_uncertainty_type:
                 raise ValueError(
                     "Asymmetrical uncertainties are not supported for the asymmetry comparison."
                 )
@@ -501,7 +545,7 @@ def get_comparison(
             lower_uncertainties = uncertainties
             upper_uncertainties = uncertainties
         elif comparison == "efficiency":
-            if h1_uncertainty_type == "asymmetrical":
+            if "asymmetrical" in h1_uncertainty_type:
                 raise ValueError(
                     "Asymmetrical uncertainties are not supported in an efficiency computation."
                 )

plothist-1.6.0/src/plothist/examples/utility/uncertainty_types.py

@@ -0,0 +1,120 @@
+"""
+Representation of different uncertainty types.
+==============================================
+
+This example demonstrates how to use the `plot_error_hist` function with different uncertainty types
+"""
+
+import boost_histogram as bh
+import matplotlib.pyplot as plt
+import numpy as np
+
+from plothist import add_text, plot_error_hist
+
+
+def shifted_array(values, offset: int, size: int = 15) -> np.ndarray:
+    """
+    Create an array of a given size with NaNs and fill it with values at specified offsets.
+    The values are inserted at every offset starting from the given offset.
+    """
+
+    arr = np.full(size, np.nan)
+    indices = range(offset, size, len(values))
+
+    for i, idx in enumerate(indices):
+        if i >= len(values):
+            break
+        arr[idx] = values[i]
+
+    return arr
+
+
+def make_grouped_edges(
+    n_groups, group_size=4, inner_spacing=0.1, inter_spacing=0.2
+) -> np.ndarray:
+    """
+    Create a set of edges for a histogram with grouped categories.
+    """
+
+    edges = [
+        group_start + i * inner_spacing
+        for group in range(n_groups)
+        for i in range(group_size)
+        for group_start in [
+            group * (group_size * inner_spacing + inter_spacing - inner_spacing)
+        ]
+    ]
+    return np.array(edges)
+
+
+# Create a category axis with explicit locations
+edges = make_grouped_edges(4)
+axis = bh.axis.Variable(edges)
+
+hists = []
+entries = [0, 0.5, 3, 500]
+
+for k in range(3):
+    hist = bh.Histogram(axis, storage=bh.storage.Weight())
+    values = shifted_array(entries, k)
+    hist[:] = np.c_[values, values]
+    hists.append(hist)
+
+
+fig, (ax_top, ax_bot) = plt.subplots(
+    2, 1, gridspec_kw={"height_ratios": [1, 3], "hspace": 0.05}
+)
+
+for ax in (ax_top, ax_bot):
+    plot_error_hist(
+        hists[0], ax=ax, label="symmetrical", uncertainty_type="symmetrical"
+    )
+    plot_error_hist(
+        hists[1], ax=ax, label="asymmetrical", uncertainty_type="asymmetrical"
+    )
+    plot_error_hist(
+        hists[2],
+        ax=ax,
+        label="asymmetrical_double_sided_zeros",
+        uncertainty_type="asymmetrical_double_sided_zeros",
+    )
+
+add_text("plot_error_hist() with different uncertainty type", ax=ax_top, x="right")
+
+# Set axis limits
+ax_top.set_ylim(465, 530)
+ax_bot.set_ylim(-0.5, 6.9)
+ax_bot.set_xlim(xmin=-0.05)
+
+# Format bottom ticks and labels
+ax_bot.set_xticks(edges[1::4] + 0.05)
+ax_bot.set_xlabel("Entry category")
+ax_bot.set_xticklabels(entries)
+ax_bot.set_ylabel("Entries")
+ax_bot.yaxis.label.set_horizontalalignment("left")
+ax_bot.spines.top.set_visible(False)
+ax_bot.xaxis.set_minor_locator(plt.NullLocator())  # Hide x-axis minor ticks
+
+# Format top ticks and labels
+ax_top.xaxis.tick_top()
+ax_top.spines.bottom.set_visible(False)
+ax_top.set_xticklabels([])
+ax_top.set_xticks([])
+
+# Draw break marks
+d = 0.5  # proportion of vertical to horizontal extent of the slanted line
+kwargs = {
+    "marker": [(-1, -d), (1, d)],
+    "markersize": 12,
+    "linestyle": "none",
+    "color": "k",
+    "mec": "k",
+    "mew": 1,
+    "clip_on": False,
+}
+ax_top.plot([0, 1], [0, 0], transform=ax_top.transAxes, **kwargs)
+ax_bot.plot([0, 1], [1, 1], transform=ax_bot.transAxes, **kwargs)
+
+ax_top.legend(loc="upper left")
+
+fig.savefig("uncertainty_types.svg", bbox_inches="tight")

{plothist-1.5.0 → plothist-1.6.0}/src/plothist/plothist_style.py

@@ -112,7 +112,7 @@ def cubehelix_palette(
     pal = cmap(x)[:, :3].tolist()
     if reverse:
         pal = pal[::-1]
-    return pal
+    return [tuple(c) for c in pal]
 
 
 def get_color_palette(
@@ -170,7 +170,7 @@ def get_color_palette(
         )
 
     plt_cmap = plt.get_cmap(cmap)
-    return plt_cmap(np.linspace(0, 1, N))
+    return [tuple(k) for k in plt_cmap(np.linspace(0, 1, N))]
 
 
 def set_fitting_ylabel_fontsize(ax: plt.Axes) -> float:

{plothist-1.5.0 → plothist-1.6.0}/src/plothist/plotters.py

@@ -406,7 +406,9 @@ def plot_error_hist(
     if uncertainty_type == "symmetrical":
         kwargs.setdefault("yerr", np.sqrt(hist.variances()))
     else:
-        uncertainties_low, uncertainties_high = get_asymmetrical_uncertainties(hist)
+        uncertainties_low, uncertainties_high = get_asymmetrical_uncertainties(
+            hist, uncertainty_type
+        )
         kwargs.setdefault("yerr", [uncertainties_low, uncertainties_high])
 
     kwargs.setdefault("fmt", ".")

{plothist-1.5.0 → plothist-1.6.0}/tests/test_comparison.py

@@ -4,6 +4,7 @@ import pytest
 from plothist.comparison import (
     _check_binning_consistency,
     _check_uncertainty_type,
+    get_asymmetrical_uncertainties,
     get_comparison,
 )
 
@@ -11,11 +12,20 @@ from plothist.comparison import (
 def test_check_uncertainty_type_invalid():
     with pytest.raises(
         ValueError,
-        match="Uncertainty type invalid_type not valid. Must be 'symmetrical' or 'asymmetrical'.",
+        match="Uncertainty type invalid_type not valid. Must be in",
     ):
         _check_uncertainty_type("invalid_type")
 
 
+def test_get_asymmetrical_uncertainties_invalid():
+    h1 = bh.Histogram(bh.axis.Regular(10, 0, 1))
+    with pytest.raises(
+        ValueError,
+        match="Invalid uncertainty type 'symmetrical' for asymmetrical uncertainties.",
+    ):
+        get_asymmetrical_uncertainties(h1, uncertainty_type="symmetrical")
+
+
 def test_check_binning_consistency_dimensionality():
     h1 = bh.Histogram(bh.axis.Regular(10, 0, 1))
     h2 = bh.Histogram(bh.axis.Regular(10, 0, 1), bh.axis.Regular(5, 0, 5))

{plothist-1.5.0 → plothist-1.6.0}/tests/test_variable_registry.py

@@ -99,7 +99,7 @@ def test_update_variable_registry_ranges() -> None:
     """
     Test variable registry range update.
     """
-    df = get_dummy_data()
+    dummy_data = get_dummy_data()
 
     registry_path = "./_test_variable_registry_ranges.yaml"
 
@@ -109,7 +109,7 @@ def test_update_variable_registry_ranges() -> None:
     )
 
     with pytest.raises(RuntimeError) as err:
-        update_variable_registry_ranges(df, variable_keys, path=registry_path)
+        update_variable_registry_ranges(dummy_data, variable_keys, path=registry_path)
     assert (
         str(err.value)
         == f"Variable {variable_keys[0]} does not have a name, bins or range property in the registry {registry_path}."
@@ -123,7 +123,7 @@ def test_update_variable_registry_ranges() -> None:
     )
 
     with pytest.raises(RuntimeError) as err:
-        update_variable_registry_ranges(df, variable_keys, path=registry_path)
+        update_variable_registry_ranges(dummy_data, variable_keys, path=registry_path)
     assert (
         str(err.value)
         == f"Variable {variable_keys[0]} does not have a name, bins or range property in the registry {registry_path}."
@@ -137,7 +137,7 @@ def test_update_variable_registry_ranges() -> None:
     )
 
     with pytest.raises(RuntimeError) as err:
-        update_variable_registry_ranges(df, variable_keys, path=registry_path)
+        update_variable_registry_ranges(dummy_data, variable_keys, path=registry_path)
     assert (
         str(err.value)
         == f"Variable {variable_keys[0]} does not have a name, bins or range property in the registry {registry_path}."
@@ -151,7 +151,7 @@ def test_update_variable_registry_ranges() -> None:
     )
 
     with pytest.raises(RuntimeError) as err:
-        update_variable_registry_ranges(df, variable_keys, path=registry_path)
+        update_variable_registry_ranges(dummy_data, variable_keys, path=registry_path)
     assert (
         str(err.value)
         == f"Variable {variable_keys[0]} does not have a name, bins or range property in the registry {registry_path}."
@@ -160,7 +160,7 @@ def test_update_variable_registry_ranges() -> None:
     # Standard registry creation
     create_variable_registry(variable_keys, path=registry_path, reset=True)
 
-    update_variable_registry_ranges(df, variable_keys, path=registry_path)
+    update_variable_registry_ranges(dummy_data, variable_keys, path=registry_path)
 
     for key in variable_keys:
         registry = get_variable_from_registry(key, path=registry_path)
@@ -183,14 +183,14 @@ def test_update_variable_registry_ranges() -> None:
     assert registry["range"] == (-1, 1)
 
     # Range values shouldn't be updated as overwrite=False
-    update_variable_registry_ranges(df, ["variable_0"], path=registry_path)
+    update_variable_registry_ranges(dummy_data, ["variable_0"], path=registry_path)
 
     registry = get_variable_from_registry("variable_0", path=registry_path)
     assert registry["range"] == (-1, 1)
 
     # Range values should be updated as overwrite=True
     update_variable_registry_ranges(
-        df, ["variable_0"], path=registry_path, overwrite=True
+        dummy_data, ["variable_0"], path=registry_path, overwrite=True
     )
 
     registry = get_variable_from_registry("variable_0", path=registry_path)
@@ -316,16 +316,16 @@ def test_update_variable_registry_ranges_all_keys() -> None:
     """
     Test update of variable registry with variable_keys=None
     """
-    df = get_dummy_data()
+    dummy_data = get_dummy_data()
 
     registry_path = "./_test_variable_registry_update_all_keys.yaml"
 
     create_variable_registry(variable_keys, path=registry_path)
-    update_variable_registry_ranges(df, variable_keys=None, path=registry_path)
+    update_variable_registry_ranges(dummy_data, variable_keys=None, path=registry_path)
 
     for key in variable_keys:
         variable = get_variable_from_registry(key, path=registry_path)
-        assert pytest.approx(variable["range"][0]) == df[key].min()
-        assert pytest.approx(variable["range"][1]) == df[key].max()
+        assert pytest.approx(variable["range"][0]) == dummy_data[key].min()
+        assert pytest.approx(variable["range"][1]) == dummy_data[key].max()
 
     os.remove(registry_path)

plothist-1.5.0/docs/documentation/statistics.rst

@@ -1,14 +0,0 @@
-.. _documentation-statistics-label:
-
-===================
-Notes on statistics
-===================
-
-The following urls are helpful to understand the statistical treatment of the uncertainties on the content of each bin of a histogram:
-
-- `Note about uncertainties when the histogram entries are weighted. <https://www.pp.rhul.ac.uk/~cowan/stat/notes/errors_with_weights.pdf>`_
-- `Presentation about asymmetrical uncertainties. <https://www.nikhef.nl/~ivov/Statistics/PoissonError/2017_05_15_PoissonError_LHCb_IvovanVulpen.pdf>`_
-
-The uncertainty on the efficiency (ratio of two histograms h1 and h2 when the entries of h1 are a subset of the entries of h2) is calculated following equation (19) of:
-
-- `T. Ullrich, Z. Xu, Treatment of Errors in Efficiency Calculations, arxiv: 0701199v1. <https://arxiv.org/pdf/physics/0701199v1.pdf>`_