plothist 1.4.0__py3-none-any.whl → 1.6.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/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/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