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

plothist/examples/utility/matplotlib_vs_plothist_style.py

@@ -0,0 +1,63 @@
+"""
+Default style: matplotlib vs plothist
+=====================================
+
+Illustration of the difference between matplotlib and plothist default styles.
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+from plothist_utils import get_dummy_data
+
+df = get_dummy_data()
+
+figs = []
+
+for style in ["matplotlib", "plothist"]:
+    if style == "matplotlib":
+        plt.style.use("default")
+        plt.rcParams["font.family"] = "DejaVu Sans"
+    else:
+        # No need to set the style if we use plothist, just importing it is enough
+        # Here we set the style because the matplotlib style was set before
+        from plothist import set_style
+
+        set_style("default")
+
+    # Create a figure with subplots
+    fig, (ax1, ax2) = plt.subplots(
+        2, 1, figsize=(6, 5.4), sharex=True, gridspec_kw={"height_ratios": [4, 1]}
+    )
+
+    # Plot histograms in the first subplot (ax1)
+    hist_0, bins, _ = ax1.hist(
+        df["variable_0"], bins=20, histtype="step", linewidth=1.2, label="h1"
+    )
+    h1 = ax1.hist(
+        df["variable_1"], bins=bins, histtype="step", linewidth=1.2, label="h2"
+    )
+    ax1.set_ylabel("Entries")
+    ax1.legend()
+
+    # Calculate the ratio of histogram values and plot in the second subplot (ax2)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        ratio = hist_0 / h1[0]  # Divide bin values of variable_0 by variable_1
+    bin_centers = 0.5 * (bins[:-1] + bins[1:])  # Calculate bin centers
+
+    # Create fake error bars for the ratio
+    ax2.plot(bin_centers, ratio, marker="|", linestyle="", markersize=15, color="black")
+    ax2.plot(bin_centers, ratio, marker="o", linestyle="", markersize=4, color="black")
+
+    ax2.axhline(y=1, color="black", linestyle="--", linewidth=0.8)
+    ax2.set_xlabel("Variable")
+    ax2.set_ylabel("Ratio")
+
+    ax1.set_xlim(-10, 10)
+    ax2.set_xlim(-10, 10)
+    ax2.set_ylim(0, 2)
+
+    fig.subplots_adjust(hspace=0.15)
+
+    fig.savefig(f"{style}_example.svg", bbox_inches="tight")
+
+    figs.append(fig)

plothist/histogramming.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import warnings
+from collections.abc import Sequence
+from typing import Callable
 
 import boost_histogram as bh
 import numpy as np
@@ -15,17 +17,23 @@ class RangeWarning(Warning):
 warnings.filterwarnings("always", category=RangeWarning)
 
 
-def create_axis(bins, range=None, data=None, overflow=False, underflow=False):
+def create_axis(
+    bins: int | list[float] | np.ndarray,
+    range: tuple[float | str, float | str] | None = None,
+    data: list[float] | np.ndarray | None = None,
+    overflow: bool = False,
+    underflow: bool = False,
+) -> bh.axis.Regular | bh.axis.Variable:
     """
     Create an axis object for histogram binning based on the input data and parameters.
 
     Parameters
     ----------
-    bins : int or array-like
+    bins : int or list[float]
         The number of bins or bin edges for the axis.
-    range : None or tuple, optional
-        The range of the axis. If None, it will be determined based on the data.
-    data : array-like, optional
+    range : None or tuple[float | str, float | str], optional
+        The range of the axis. If None, it will be determined based on the data. Default is None.
+    data : list[float] or np.ndarray, optional
         The input data for determining the axis range. Default is None.
     overflow : bool, optional
         Whether to include an overflow bin. If False, the upper edge of the last bin is inclusive. Default is False.
@@ -52,19 +60,16 @@ def create_axis(bins, range=None, data=None, overflow=False, underflow=False):
     if data is None:
         data = np.array([])
 
-    try:
-        N = len(bins)
-    except TypeError:
-        N = 1
+    is_variable_bins = isinstance(bins, (list, np.ndarray))
 
-    if N > 1:
+    if is_variable_bins:
         if range is not None:
             warnings.warn(
                 f"Custom binning -> ignore supplied range ({range}).", stacklevel=2
             )
         return bh.axis.Variable(bins, underflow=underflow, overflow=overflow)
 
-    if bins <= 0:
+    if isinstance(bins, int) and bins <= 0:
         raise ValueError(f"Number of bins must be positive, but got {bins}.")
 
     # Inspired from np.histograms
@@ -74,8 +79,8 @@ def create_axis(bins, range=None, data=None, overflow=False, underflow=False):
                 "Cannot use 'min'/'max' range values with empty data. "
                 "Please supply a range or provide data."
             )
-        x_min = min(data) if range[0] == "min" else range[0]
-        x_max = max(data) if range[1] == "max" else range[1]
+        x_min = min(data) if range[0] == "min" else float(range[0])
+        x_max = max(data) if range[1] == "max" else float(range[1])
         if x_min > x_max:
             raise ValueError(
                 f"Range of [{x_min}, {x_max}] is not valid. Max must be larger than min."
@@ -84,10 +89,10 @@ def create_axis(bins, range=None, data=None, overflow=False, underflow=False):
             raise ValueError(f"Range of [{x_min}, {x_max}] is not finite.")
     elif len(data) == 0:
         # handle empty arrays. Can't determine range, so use 0-1.
-        x_min, x_max = 0, 1
+        x_min, x_max = 0.0, 1.0
     else:
-        x_min = min(data)
-        x_max = max(data)
+        x_min = float(min(data))
+        x_max = float(max(data))
         if not (np.isfinite(x_min) and np.isfinite(x_max)):
             raise ValueError(f"Autodetected range of [{x_min}, {x_max}] is not finite.")
 
@@ -99,30 +104,35 @@ def create_axis(bins, range=None, data=None, overflow=False, underflow=False):
     return bh.axis.Regular(bins, x_min, x_max, underflow=underflow, overflow=overflow)
 
 
-def make_hist(data=None, bins=50, range=None, weights=1):
+def make_hist(
+    data: list[float] | np.ndarray | None = None,
+    bins: int | list[float] | np.ndarray = 50,
+    range: tuple[float | str, float | str] | None = None,
+    weights: float | list[float] | np.ndarray = 1,
+) -> bh.Histogram:
     """
     Create a histogram object and fill it with the provided data.
 
     Parameters
     ----------
-    data : array-like, optional
+    data : list[float] or np.ndarray, optional
         1D array-like data used to fill the histogram (default is None).
         If None is provided, an empty histogram is returned.
-    bins : int or tuple, optional
+    bins : int or list[float], optional
         Binning specification for the histogram (default is 50).
         If an integer, it represents the number of bins.
-        If a tuple, it should be the explicit list of all bin edges.
-    range : tuple, optional
+        If a list, it should be the explicit list of all bin edges.
+    range : tuple[float | str, float | str], optional
         The range of values to consider for the histogram bins (default is None).
         If None, the range is determined from the data.
-    weights : float or array-like, optional
+    weights : float or list[float] or np.ndarray, optional
         Weight(s) to apply to the data points (default is 1).
         If a float, a single weight is applied to all data points.
         If an array-like, weights are applied element-wise.
 
     Returns
     -------
-    histogram : boost_histogram.Histogram
+    histogram : bh.Histogram
         The filled histogram object.
 
     Warns
@@ -160,31 +170,38 @@ def make_hist(data=None, bins=50, range=None, weights=1):
     return h
 
 
-def make_2d_hist(data=None, bins=(10, 10), range=(None, None), weights=1):
+def make_2d_hist(
+    data: list[np.ndarray] | np.ndarray | None = None,
+    bins: Sequence[int | Sequence[float]] | None = None,
+    range: tuple[
+        tuple[float | str, float | str] | None, tuple[float | str, float | str] | None
+    ] = (None, None),
+    weights: float | list[float] | np.ndarray = 1,
+) -> bh.Histogram:
     """
     Create a 2D histogram object and fill it with the provided data.
 
     Parameters
     ----------
-    data : array-like, optional
+    data : list[np.ndarray] or np.ndarray, optional
         2D array-like data used to fill the histogram (default is None).
         If None is provided, an empty histogram is returned.
-    bins : tuple, optional
-        Binning specification for each dimension of the histogram (default is (10, 10)).
+    bins : Sequence[int | Sequence[float]], optional
+        Binning specification for each dimension of the histogram (if None, it will be set to [50, 50]).
         Each element of the tuple represents the number of bins for the corresponding dimension.
         Also support explicit bin edges specification (for non-constant bin size).
-    range : tuple, optional
+    range : tuple[tuple[float | str, float | str] | None, tuple[float | str, float | str] | None], optional
         The range of values to consider for each dimension of the histogram (default is (None, None)).
         If None, the range is determined from the data for that dimension.
         The tuple should have the same length as the data.
-    weights : float or array-like, optional
+    weights : float or list[float] or np.ndarray, optional
         Weight(s) to apply to the data points (default is 1).
         If a float, a single weight is applied to all data points.
         If an array-like, weights are applied element-wise.
 
     Returns
     -------
-    histogram : boost_histogram.Histogram
+    histogram : bh.Histogram
         The filled 2D histogram object.
 
     Raises
@@ -203,6 +220,8 @@ def make_2d_hist(data=None, bins=(10, 10), range=(None, None), weights=1):
         raise ValueError("data should have two components, x and y")
     if len(data[0]) != len(data[1]):
         raise ValueError("x and y must have the same length.")
+    if bins is None:
+        bins = [50, 50]
 
     x_axis = create_axis(bins[0], range[0], data[0])
     y_axis = create_axis(bins[1], range[1], data[1])
@@ -236,13 +255,13 @@ def make_2d_hist(data=None, bins=(10, 10), range=(None, None), weights=1):
     return h
 
 
-def _check_counting_histogram(hist):
+def _check_counting_histogram(hist: bh.Histogram) -> None:
     """
     Check that the histogram is a counting histogram.
 
     Parameters
     ----------
-    hist : boost_histogram.Histogram
+    hist : bh.Histogram
         The histogram to check.
 
     Raise
@@ -257,7 +276,9 @@ def _check_counting_histogram(hist):
         )
 
 
-def _make_hist_from_function(func, ref_hist):
+def _make_hist_from_function(
+    func: Callable[[np.ndarray], np.ndarray], ref_hist: bh.Histogram
+) -> bh.Histogram:
     """
     Create a histogram from a function and a reference histogram.
     The returned histogram has the same binning as the reference histogram and
@@ -265,14 +286,14 @@ def _make_hist_from_function(func, ref_hist):
 
     Parameters
     ----------
-    func : function
+    func : Callable[[np.ndarray], np.ndarray]
         1D function. The function should support vectorization (i.e. accept a numpy array as input).
-    ref_hist : boost_histogram.Histogram
+    ref_hist : bh.Histogram
         The reference 1D histogram to use for the binning.
 
     Returns
     -------
-    hist : boost_histogram.Histogram
+    hist : bh.Histogram
         The histogram filled with the function.
 
     Raises
@@ -290,18 +311,18 @@ def _make_hist_from_function(func, ref_hist):
     return hist
 
 
-def flatten_2d_hist(hist):
+def flatten_2d_hist(hist: bh.Histogram) -> bh.Histogram:
     """
     Flatten a 2D histogram into a 1D histogram.
 
     Parameters
     ----------
-    hist : Histogram object
+    hist : bh.Histogram
         The 2D histogram to be flattened.
 
     Returns
     -------
-    Histogram object
+    bh.Histogram
         The flattened 1D histogram.
 
     Raises

plothist/plothist_style.py

@@ -1,13 +1,11 @@
 from __future__ import annotations
 
-from importlib.resources import files
-
 import matplotlib as mpl
 import matplotlib.pyplot as plt
 import numpy as np
 
 
-def set_style(style="default"):
+def set_style(style: str = "default") -> None:
     """
     Set the plothist style.
 
@@ -32,22 +30,21 @@ def set_style(style="default"):
     available_styles = ["default"]
 
     if style in available_styles:
-        style_file = files("plothist").joinpath(f"{style}_style.mplstyle")
-        plt.style.use(style_file)
+        plt.style.use(f"plothist.{style}_style")
     else:
         raise ValueError(f"{style} not in the available styles: {available_styles}")
 
 
 def cubehelix_palette(
-    ncolors=7,
-    start=1.5,
-    rotation=1.5,
-    gamma=1.0,
-    hue=0.8,
-    lightest=0.8,
-    darkest=0.3,
-    reverse=True,
-):
+    ncolors: int = 7,
+    start: float = 1.5,
+    rotation: float = 1.5,
+    gamma: float = 1.0,
+    hue: float = 0.8,
+    lightest: float = 0.8,
+    darkest: float = 0.3,
+    reverse: bool = True,
+) -> list[tuple[float, float, float]]:
     """
     Make a sequential palette from the cubehelix system, in which the perceived brightness is linearly increasing.
     This code is adapted from seaborn, which implements equation (2) of reference [1] below.
@@ -75,10 +72,9 @@ def cubehelix_palette(
 
     Returns
     -------
-    list of RGB tuples
+    list[tuple[float, float, float]]
         The generated palette of colors represented as a list of RGB tuples.
 
-
     References
     ----------
     [1] Green, D. A. (2011). "A colour scheme for the display of astronomical
@@ -119,7 +115,9 @@ def cubehelix_palette(
     return pal
 
 
-def get_color_palette(cmap, N):
+def get_color_palette(
+    cmap: str, N: int
+) -> list[str] | list[tuple[float, float, float]]:
     """
     Get N different colors from a chosen colormap.
 
@@ -132,8 +130,9 @@ def get_color_palette(cmap, N):
 
     Returns
     -------
-    list
-        A list of RGB color tuples sampled from the colormap.
+    list[str] or list[tuple[float, float, float]]
+        A list of colors. If "ggplot" is selected, returns a list of hex color strings.
+        Otherwise, returns a list of RGB color tuples.
 
     References
     ----------
@@ -174,7 +173,7 @@ def get_color_palette(cmap, N):
     return plt_cmap(np.linspace(0, 1, N))
 
 
-def set_fitting_ylabel_fontsize(ax):
+def set_fitting_ylabel_fontsize(ax: plt.Axes) -> float:
     """
     Get the suitable font size for a ylabel text that fits within the plot's y-axis limits.
 
@@ -190,9 +189,8 @@ def set_fitting_ylabel_fontsize(ax):
     """
     ylabel_fontsize = ax.yaxis.get_label().get_fontsize()
 
-    # Check if renderer is available
-    if ax.figure.canvas.get_renderer() is None:
-        ax.figure.canvas.draw()
+    # Force renderer to be initialized
+    ax.figure.canvas.draw()
 
     while (
         ax.yaxis.get_label()
@@ -214,14 +212,14 @@ def set_fitting_ylabel_fontsize(ax):
 
 
 def add_text(
-    text,
-    x="left",
-    y="top",
-    fontsize=12,
-    white_background=False,
-    ax=None,
+    text: str,
+    x: float | str = "left",
+    y: float | str = "top",
+    fontsize: int = 12,
+    white_background: bool = False,
+    ax: plt.Axes | None = None,
     **kwargs,
-):
+) -> None:
     """
     Add text to an axis.
 
@@ -229,9 +227,9 @@ def add_text(
     ----------
     text : str
         The text to add.
-    x : float, optional
+    x : float | str, optional
         Horizontal position of the text in unit of the normalized x-axis length. The default is value "left", which is an alias for 0.0. Other aliases are "right", "left_in", "right_in", "right_out".
-    y : float, optional
+    y : float | str, optional
         Vertical position of the text in unit of the normalized y-axis length. The default is value "top", which is an alias for 1.01. Other aliases are "top_in", "bottom_in", "top_out"="top", "bottom_out"="bottom".
     fontsize : int, optional
         Font size, by default 12.
@@ -279,14 +277,14 @@ def add_text(
     }
 
     if isinstance(x, str):
-        x = x_values.get(x)
-        if x is None:
-            raise ValueError(f"{x} not a float or a valid position")
+        if x not in x_values:
+            raise ValueError(f"{x!r} is not a valid x position.")
+        x = x_values[x]
 
     if isinstance(y, str):
-        y = y_values.get(y)
-        if y is None:
-            raise ValueError(f"{y} not a float or a valid position")
+        if y not in y_values:
+            raise ValueError(f"{y!r} is not a valid y position.")
+        y = y_values[y]
 
     t = ax.text(
         x,
@@ -303,19 +301,19 @@ def add_text(
 
 
 def add_luminosity(
-    collaboration,
-    x="right",
-    y="top",
-    fontsize=12,
-    is_data=True,
-    lumi="",
-    lumi_unit="fb",
-    preliminary=False,
-    two_lines=False,
-    white_background=False,
-    ax=None,
+    collaboration: str,
+    x: float | str = "right",
+    y: float | str = "top",
+    fontsize: int = 12,
+    is_data: bool = True,
+    lumi: int | str = "",
+    lumi_unit: str = "fb",
+    preliminary: bool = False,
+    two_lines: bool = False,
+    white_background: bool = False,
+    ax: plt.Axes | None = None,
     **kwargs,
-):
+) -> None:
     """
     Add the collaboration name and the integrated luminosity (or "Simulation").
 
@@ -323,17 +321,17 @@ def add_luminosity(
     ----------
     collaboration : str
         Collaboration name.
-    x : float, optional
+    x : float | str, optional
         Horizontal position of the text in unit of the normalized x-axis length. The default is value "right", which is an alias for 1.0. Can take other aliases such as "left", "left_in", "right_in", "right_out".
-    y : float, optional
+    y : float | str, optional
         Vertical position of the text in unit of the normalized y-axis length. The default is value "top", which is an alias for 1.01. Can take other aliases such as "top_in", "bottom_in", "top_out"="top", "bottom_out"="bottom".
     fontsize : int, optional
         Font size, by default 12.
     is_data : bool, optional
         If True, plot integrated luminosity. If False, plot "Simulation", by default True.
-    lumi : int/string, optional
+    lumi : int | str, optional
         Integrated luminosity. If empty, do not plot luminosity. Default value is empty.
-    lumi_unit : string, optional
+    lumi_unit : str, optional
         Integrated luminosity unit. Default value is fb. The exponent is automatically -1.
     preliminary : bool, optional
         If True, print "preliminary", by default False.
@@ -383,7 +381,7 @@ def add_luminosity(
     )
 
 
-def plot_reordered_legend(ax, order, **kwargs):
+def plot_reordered_legend(ax: plt.Axes, order: list[int], **kwargs) -> None:
     """
     Reorder the legend handlers and labels on the given Matplotlib axis based
     on the specified order and plot the reordered legend.
@@ -392,7 +390,7 @@ def plot_reordered_legend(ax, order, **kwargs):
     ----------
     ax : matplotlib.axes.Axes
         The Matplotlib Axes object on which the legend is to be reordered.
-    order : list of int
+    order : list[int]
         A list of integers specifying the new order of the legend items.
         The integers refer to the indices of the current legend items.
     kwargs : dict, optional
@@ -418,7 +416,6 @@ def plot_reordered_legend(ax, order, **kwargs):
     To reorder the legend so that 'Line 2' comes first, use:
 
     >>> plot_reordered_legend(ax, [1, 0])
-
     """
 
     # Extract the original handlers and labels