feat: add ratio plot support through .plot_ratio API (#161)

* feat: Add plot_ratio API

* Add .plot_ratio to BastHist API
   - Adds ratio plot support for other Hists and callables
* Factor out plot_ratio and plot_pull to perform the final subplot plotting
   - Majority of logic is factored out of plot_pull into _plot_ratiolike
   - _plot_ratiolike then calls plot_ratio or plot_pull as needed

* Add test images for plot_ratio

* Add plotting tests for plot_ratio

* Update README and Changelog to reflect addition of plot_ratio

* Add NameTuples for typing

* force return type to be np.ndarray
* type before to deal with control flow

* Fixups thanks to Henry's advice

* Ensure default uncertainty band color visible

* bump location of __all__ to just below imports

* Remove quotes

* Rename _hist vars to either __hist or histogram

* Add test for str alias for plot_ratio and plot_pull

* Add str to types for plot_ratiolike

* use TypeVar to type hist.BaseHist

* Rename plot_x -> plot_x_array for clarity

* Use quoted types over TypeVar

Co-authored-by: Henry Schreiner <[email protected]>

Co-authored-by: Henry Schreiner <[email protected]>

Author: matthewfeickert

README.md

@@ -58,6 +58,7 @@ Hist currently provides everything boost-histogram provides, and the following e
 - Quick plotting routines encourage exploration:
   - `.plot()` provides 1D and 2D plots
   - `.plot2d_full()` shows 1D projects around a 2D plot
+  - `.plot_ratio(...)` make a ratio plot between the histogram and another histogram or callable
   - `.plot_pull(...)` performs a pull plot
   - `.plot_pie()` makes a pie plot
   - `.show()` provides a nice str printout using Histoprint

docs/changelog.rst

@@ -4,6 +4,10 @@ Changelog
 IN PROGRESS
 --------------------
 
+* Add ``plot_ratio`` to the public API, which allows for making ratio plots between the
+  histogram and either another histogram or a callable.
+  `#161 <https://github.com/scikit-hep/hist/pull/161>`_
+
 * Add frequentist coverage interval support in the ``intervals`` module.
   `#176 <https://github.com/scikit-hep/hist/pull/176>`_
 

src/hist/basehist.py

@@ -35,6 +35,8 @@
     import matplotlib.axes
     from mplhep.plot import Hist1DArtists, Hist2DArtists
 
+    from .plot import FitResultArtists, MainAxisArtists, RatiolikeArtists
+
 InnerIndexing = Union[
     SupportsIndex, str, Callable[[bh.axis.Axis], int], slice, "ellipsis"
 ]
@@ -401,20 +403,45 @@ def plot2d_full(
 
         return hist.plot.plot2d_full(self, ax_dict=ax_dict, **kwargs)
 
+    def plot_ratio(
+        self,
+        other: Union["hist.BaseHist", Callable[[np.ndarray], np.ndarray], str],
+        *,
+        ax_dict: "Optional[Dict[str, matplotlib.axes.Axes]]" = None,
+        **kwargs: Any,
+    ) -> "Tuple[MainAxisArtists, RatiolikeArtists]":
+        """
+        ``plot_ratio`` method for ``BaseHist`` object.
+
+        Return a tuple of artists following a structure of
+        ``(main_ax_artists, subplot_ax_artists)``
+        """
+
+        import hist.plot
+
+        return hist.plot._plot_ratiolike(
+            self, other, ax_dict=ax_dict, view="ratio", **kwargs
+        )
+
     def plot_pull(
         self,
-        func: Callable[[np.ndarray], np.ndarray],
+        func: Union[Callable[[np.ndarray], np.ndarray], str],
         *,
         ax_dict: "Optional[Dict[str, matplotlib.axes.Axes]]" = None,
         **kwargs: Any,
-    ) -> "Tuple[matplotlib.axes.Axes, matplotlib.axes.Axes]":
+    ) -> "Tuple[FitResultArtists, RatiolikeArtists]":
         """
-        Plot_pull method for BaseHist object.
+        ``plot_pull`` method for ``BaseHist`` object.
+
+        Return a tuple of artists following a structure of
+        ``(main_ax_artists, subplot_ax_artists)``
         """
 
         import hist.plot
 
-        return hist.plot.plot_pull(self, func, ax_dict=ax_dict, **kwargs)
+        return hist.plot._plot_ratiolike(
+            self, func, ax_dict=ax_dict, view="pull", **kwargs
+        )
 
     def plot_pie(
         self,