fix: stairs/steppatch cleanup

andrzejnovak · andrzejnovak · commit e5af734dbef8 · 2020-09-09T17:50:58.000+02:00
diff --git a/doc/api/axes_api.rst b/doc/api/axes_api.rst
@@ -137,6 +137,7 @@ Binned
    Axes.hexbin
    Axes.hist
    Axes.hist2d
+   Axes.stairs
 
 Contours
 --------
diff --git a/doc/users/next_whats_new/steppatch_and_stairs.rst b/doc/users/next_whats_new/steppatch_and_stairs.rst
@@ -1,7 +1,7 @@
 New `~.matplotlib.patches.StepPatch` artist and a `.pyplot.stairs` method
 -------------------------------------------------------------------------
-These take inputs of asymmetric lengths with y-like values and 
-x-like edges, between which the values lie.
+For both the artist and the function, the x-like edges input is one 
+longer than the y-like values input
 
   .. plot::
 
diff --git a/examples/lines_bars_and_markers/stairs_demo.py b/examples/lines_bars_and_markers/stairs_demo.py
@@ -1,12 +1,15 @@
 """
-=============
-Histline Demo
-=============
+===========
+Stairs Demo
+===========
 
 This example demonstrates the use of `~.matplotlib.pyplot.stairs`
 for histogram and histogram-like data visualization and an associated
-underlying `.StepPatch` artist, which is
-a contrained version of `.PathPatch` specified by its bins and edges.
+underlying `.StepPatch` artist, which is a specialized version of
+`.PathPatch` specified by its bins and edges.
+
+The primary difference to `~.matplotlib.pyplot.step` is that ``stairs``
+x-like edges input is one longer than its y-like values input.
 """
 
 import numpy as np
@@ -19,12 +22,12 @@
 
 fig, axs = plt.subplots(3, 1, figsize=(7, 15))
 axs[0].stairs(h, bins, label='Simple histogram')
-axs[0].stairs(h, bins+5, baseline=50, label='--//-- w/ modified baseline')
-axs[0].stairs(h, bins+10, baseline=None, label='--//-- w/ no edges')
+axs[0].stairs(h, bins+5, baseline=50, label='Modified baseline')
+axs[0].stairs(h, bins+10, baseline=None, label='No edges')
 axs[0].set_title("Step Histograms")
 
 axs[1].stairs(np.arange(1, 6, 1), fill=True,
-              label='Filled histogram\nw/ automatatic edges')
+              label='Filled histogram\nw/ automatic edges')
 axs[1].stairs(np.arange(1, 6, 1)*0.3, np.arange(2, 8, 1),
               orientation='horizontal', hatch='//',
               label='Hatched histogram\nw/ horizontal orientation')
@@ -43,6 +46,24 @@
     ax.legend()
 plt.show()
 
+#############################################################################
+# Comparison of `.pyplot.step` and `.pyplot.stairs`.
+
+bins = np.arange(14)
+centers = bins[:-1] + np.diff(bins)/2
+y = np.sin(centers / 2)
+
+plt.step(bins[:-1], y, where='post', label='Step(where="post")')
+plt.plot(bins[:-1], y, 'o--', color='grey', alpha=0.3)
+
+plt.stairs(y - 1, bins, baseline=None, label='Stairs')
+plt.plot(centers, y - 1, 'o--', color='grey', alpha=0.3)
+plt.plot(np.repeat(bins, 2), np.hstack([y[0], np.repeat(y, 2), y[-1]]) - 1,
+         'o', color='red', alpha=0.2)
+
+plt.legend()
+plt.title('plt.step vs plt.stairs')
+plt.show()
 
 #############################################################################
 #
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -6918,6 +6918,10 @@ def stairs(self, values, edges=None, *,
         if edges is None:
             edges = np.arange(len(values) + 1)
 
+        self._process_unit_info(xdata=edges, ydata=values, kwargs=kwargs)
+        edges = self.convert_xunits(edges)
+        values = self.convert_yunits(values)
+
         patch = mpatches.StepPatch(values,
                                    edges,
                                    baseline=baseline,
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -1019,11 +1019,10 @@ def __init__(self, values, edges, *,
         self.orientation = orientation
         self._edges = np.asarray(edges)
         self._values = np.asarray(values)
-        verts, codes = self._update_data()
-        path = Path(verts, codes)
-        super().__init__(path, **kwargs)
+        self._update_path()
+        super().__init__(self._path, **kwargs)
 
-    def _update_data(self):
+    def _update_path(self):
         if np.isnan(np.sum(self._edges)):
             raise ValueError('Nan values in "edges" are disallowed')
         if self._edges.size - 1 != self._values.size:
@@ -1046,18 +1045,24 @@ def _update_data(self):
                 xy = np.column_stack([y, x])
             verts.append(xy)
             codes.append(np.array([Path.MOVETO] + [Path.LINETO]*(len(xy)-1)))
-        return np.vstack(verts), np.hstack(codes)
+            self._path = Path(np.vstack(verts), np.hstack(codes))
 
-    def set_edges(self, edges):
-        self._edges = np.asarray(edges)
-        verts, codes = self._update_data()
-        self.set_path(Path(verts, codes))
-        self.stale = True
+    def set_data(self, values, edges=None):
+        """
+        Set the values and optionally edges of the
+        StepPatch artist.
 
-    def set_values(self, values):
-        self._values = np.asarray(values)
-        verts, codes = self._update_data()
-        self.set_path(Path(verts, codes))
+        Parameters
+        ----------
+        values : 1D array-like or None
+            Will not update values, if passing None
+        edges : 1D array-like, optional
+        """
+        if values is not None:
+            self._values = np.asarray(values)
+        if edges is not None:
+            self._edges = np.asarray(edges)
+        self._update_path()
         self.stale = True
 
 
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -1819,13 +1819,14 @@ def test_stairs_fill(fig_test, fig_ref):
 def test_stairs_update(fig_test, fig_ref):
     # Test
     fig_test, test_ax = plt.subplots()
-    h = test_ax.stairs([1, 2])
-    h.set_values([2, 1])
-    h.set_edges([0, 1, 1.5])
-
+    h = test_ax.stairs([1, 2, 3])
+    h.set_values([3, 2, 1])
+    h.set_data([1, 2, 1], np.arange(4)/2)
+    h.set_data([1, 2, 3])
+    h.set_data(None, np.arange(4))
     # # Ref
     fig_ref, ref_ax = plt.subplots()
-    h = ref_ax.stairs([2, 1], [0, 1, 1.5])
+    h = ref_ax.stairs([1, 2, 3])
 
 
 @pytest.mark.xfail
