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

plothist/examples/utility/color_palette_hists.py

@@ -0,0 +1,94 @@
+"""
+Color palettes in stacked histograms
+====================================
+
+Examples of color palettes in stacked histograms.
+"""
+
+from plothist_utils import get_dummy_data
+
+df = get_dummy_data()
+
+import matplotlib.pyplot as plt
+
+from plothist import add_text, get_color_palette, make_hist, plot_error_hist, plot_model
+
+# Define the histograms
+key = "variable_1"
+xrange = (-8, 10)
+category = "category"
+
+# Define masks
+signal_mask = df[category] == 7
+data_mask = df[category] == 8
+
+background_categories = [0, 1, 2, 3, 4, 5]
+background_categories_labels = [f"c{i}" for i in background_categories]
+background_masks = [df[category] == p for p in background_categories]
+
+# Make histograms
+data_hist = make_hist(df[key][data_mask], bins=50, range=xrange, weights=1)
+background_hists = [
+    make_hist(df[key][mask], bins=50, range=xrange, weights=1)
+    for mask in background_masks
+]
+signal_hist = make_hist(df[key][signal_mask], bins=50, range=xrange, weights=1)
+
+# Optional: scale to data
+background_scaling_factor = data_hist.sum().value / sum(background_hists).sum().value
+background_hists = [background_scaling_factor * h for h in background_hists]
+
+signal_scaling_factor = data_hist.sum().value / signal_hist.sum().value
+signal_hist *= signal_scaling_factor
+
+
+# Plotting section
+nrows, ncols = 2, 2
+
+fig, axes = plt.subplots(
+    nrows=nrows,
+    ncols=ncols,
+    figsize=(12, 10),
+)
+fig.subplots_adjust(hspace=0.25)
+
+cmap_list = ["viridis", "ggplot", "coolwarm", "YlGnBu_r"]
+ax_coords = [(x, y) for x in range(nrows) for y in range(ncols)]
+
+for k, cmap_name in enumerate(cmap_list):
+    background_categories_colors = get_color_palette(
+        cmap_name, len(background_categories)
+    )
+
+    ax = axes[ax_coords[k]]
+
+    plot_model(
+        stacked_components=background_hists,
+        stacked_labels=background_categories_labels,
+        stacked_colors=background_categories_colors,
+        xlabel=key,
+        ylabel="Entries",
+        model_uncertainty=False,
+        fig=fig,
+        ax=ax,
+    )
+
+    plot_error_hist(
+        data_hist,
+        color="black",
+        label="Data",
+        ax=ax,
+    )
+
+    ax.set_xlim(xrange)
+    ax.legend()
+
+    cmap_name = cmap_name.replace("_", r"\_")
+    add_text(
+        rf"$\mathrm{{\mathbf{{cmap = {cmap_name}}}}}$", x="right", fontsize=12, ax=ax
+    )
+
+fig.savefig(
+    "color_palette_hists.svg",
+    bbox_inches="tight",
+)

plothist/examples/utility/color_palette_squares.py

@@ -0,0 +1,100 @@
+"""
+Color palettes
+==============
+
+Examples of color palettes.
+"""
+
+import matplotlib.colors as mcolors
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib import patches
+
+from plothist import get_color_palette
+
+
+def create_palette_plot(colors, fig_name, add_text=False, add_black_border=False):
+    ncolors = len(colors)
+
+    # Create a figure and axis
+    fig, ax = plt.subplots(figsize=(ncolors, 1))
+
+    # Plot the colored squares with small spacing
+    square_size = 1
+    spacing = 0.1
+    x = 0
+
+    for color in colors:
+        rect = patches.Rectangle((x, 0), square_size, square_size, color=color)
+        ax.add_patch(rect)
+        x += square_size + spacing
+
+        if add_text:
+            # Add text displaying the color value
+            ax.text(
+                x - (square_size + spacing) / 1.81,
+                -0.18,
+                mcolors.rgb2hex(color).upper(),
+                ha="center",
+                fontsize=10,
+            )
+
+    # Set the x-axis limits and show the ticks
+    ax.set_xlim(-0.5, x - spacing)
+    ax.set_xticks(np.arange(0, x, square_size + spacing))
+    ax.set_xticklabels(np.arange(1, ncolors + 1), fontsize=8)
+    ax.set_xticklabels([])  # Remove the x-tick labels
+
+    # Set the y-axis ticks and labels
+    ax.set_yticks([])
+    ax.set_yticklabels([])
+
+    # Remove the borders around the plot
+    ax.spines["top"].set_visible(False)
+    ax.spines["bottom"].set_visible(False)
+    ax.spines["left"].set_visible(False)
+    ax.spines["right"].set_visible(False)
+
+    # Remove the x-label and y-label
+    ax.set_xlabel("")
+    ax.set_ylabel("")
+
+    if add_black_border:
+        # Add a black border rectangle
+        border_rect = patches.Rectangle(
+            (0, 0),
+            x - spacing,
+            square_size,
+            edgecolor="black",
+            facecolor="none",
+            linewidth=1,
+        )
+        ax.add_patch(border_rect)
+
+    # Adjust the padding and remove extra whitespace
+    plt.margins(0)
+    plt.gca().set_axis_off()
+    plt.subplots_adjust(left=0.05, right=0.95)
+
+    plt.savefig(fig_name, bbox_inches="tight")
+
+    return fig
+
+
+figs = []
+
+ncolors = 7
+
+ncolors_ggplot = 7 if ncolors > 7 else ncolors
+colors = get_color_palette("ggplot", ncolors_ggplot)
+figs.append(
+    create_palette_plot(colors, fig_name="usage_style_cycle.svg", add_text=True)
+)
+
+colors = get_color_palette("cubehelix", ncolors)
+figs.append(create_palette_plot(colors, fig_name="usage_cubehelix.svg"))
+
+cmap_list = ["viridis", "coolwarm", "YlGnBu_r"]
+for cmap_name in cmap_list:
+    colors = get_color_palette(cmap_name, ncolors)
+    figs.append(create_palette_plot(colors, fig_name=f"usage_{cmap_name}_palette.svg"))

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,11 @@
+from __future__ import annotations
+
+import warnings
+from collections.abc import Sequence
+from typing import Callable
+
 import boost_histogram as bh
 import numpy as np
-import warnings
 
 
 # Define a custom warning for range issues
@@ -12,18 +17,24 @@ class RangeWarning(Warning):
 warnings.filterwarnings("always", category=RangeWarning)
 
 
-def create_axis(bins, range=None, data=np.array([]), 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
-        The input data for determining the axis range. Default is an empty array.
+    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.
     underflow : bool, optional
@@ -46,20 +57,19 @@ def create_axis(bins, range=None, data=np.array([]), overflow=False, underflow=F
     ValueError
         If the range parameter contains "min" or "max" but the data is empty.
     """
+    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
@@ -69,8 +79,8 @@ def create_axis(bins, range=None, data=np.array([]), overflow=False, underflow=F
                 "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."
@@ -79,10 +89,10 @@ def create_axis(bins, range=None, data=np.array([]), overflow=False, underflow=F
             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.")
 
@@ -94,30 +104,35 @@ def create_axis(bins, range=None, data=np.array([]), overflow=False, underflow=F
     return bh.axis.Regular(bins, x_min, x_max, underflow=underflow, overflow=overflow)
 
 
-def make_hist(data=np.array([]), 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
-        1D array-like data used to fill the histogram (default is an empty array).
-        If an empty array, an empty histogram is returned.
-    bins : int or tuple, 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 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
@@ -125,6 +140,8 @@ def make_hist(data=np.array([]), bins=50, range=None, weights=1):
     RangeWarning
         If more than 1% of the data is outside of the binning range.
     """
+    if data is None:
+        data = np.array([])
 
     axis = create_axis(bins, range, data)
 
@@ -145,7 +162,7 @@ def make_hist(data=np.array([]), bins=50, range=None, weights=1):
         # Issue a warning if more than 1% of the data is outside of the binning range
         if range_coverage < 0.99:
             warnings.warn(
-                f"Only {100*range_coverage:.2f}% of data contained in the binning range [{axis.edges[0]}, {axis.edges[-1]}].",
+                f"Only {100 * range_coverage:.2f}% of data contained in the binning range [{axis.edges[0]}, {axis.edges[-1]}].",
                 category=RangeWarning,
                 stacklevel=2,
             )
@@ -153,31 +170,38 @@ def make_hist(data=np.array([]), bins=50, range=None, weights=1):
     return h
 
 
-def make_2d_hist(data=np.array([[], []]), 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
-        2D array-like data used to fill the histogram (default is an empty array).
-        If an empty array, an empty histogram is returned.
-    bins : tuple, optional
-        Binning specification for each dimension of the histogram (default is (10, 10)).
+    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 : 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
@@ -190,10 +214,14 @@ def make_2d_hist(data=np.array([[], []]), bins=(10, 10), range=(None, None), wei
     RangeWarning
         If more than 1% of the data is outside of the binning range.
     """
+    if data is None:
+        data = np.array([[], []])
     if len(data) != 2:
         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])
@@ -219,7 +247,7 @@ def make_2d_hist(data=np.array([[], []]), bins=(10, 10), range=(None, None), wei
         # Issue a warning if more than 1% of the data is outside of the binning range
         if range_coverage < 0.99:
             warnings.warn(
-                f"Only {100*range_coverage:.2f}% of data contained in the binning range ([{x_axis.edges[0]}, {x_axis.edges[-1]}], [{y_axis.edges[0]}, {y_axis.edges[-1]}]).",
+                f"Only {100 * range_coverage:.2f}% of data contained in the binning range ([{x_axis.edges[0]}, {x_axis.edges[-1]}], [{y_axis.edges[0]}, {y_axis.edges[-1]}]).",
                 category=RangeWarning,
                 stacklevel=2,
             )
@@ -227,13 +255,13 @@ def make_2d_hist(data=np.array([[], []]), bins=(10, 10), range=(None, None), wei
     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
@@ -246,10 +274,11 @@ def _check_counting_histogram(hist):
         raise ValueError(
             f"The histogram must be a counting histogram, but the input histogram has kind {hist.kind}."
         )
-    return
 
 
-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
@@ -257,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
@@ -282,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