limit StepPatch to get/set_data()

Author: andrzejnovak

examples/lines_bars_and_markers/stairs_demo.py

@@ -45,11 +45,12 @@
 
 #############################################################################
 # *baseline* can take an array to allow for stacked histogram plots
+A = [[0, 0, 0],
+     [1, 2, 3],
+     [2, 4, 6],
+     [3, 6, 9]]
 
-A = np.tile([1, 2, 3], (3, 1)) * np.arange(1, 4).reshape(-1, 1)
-A = np.vstack([np.zeros(3), A])
-
-for i in range(3):
+for i in range(len(A) - 1):
     plt.stairs(A[i+1], baseline=A[i], fill=True)
 
 #############################################################################

lib/matplotlib/axes/_axes.py

@@ -6729,7 +6729,8 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
     def stairs(self, values, edges=None, *,
                orientation='vertical', baseline=0, fill=False, **kwargs):
         """
-        A stepwise constant line or filled plot.
+        A stepwise constant function as a line with bounding edges
+        or a filled plot.
 
         Parameters
         ----------
@@ -6745,8 +6746,10 @@ def stairs(self, values, edges=None, *,
             the y-axis, and edges are along the x-axis.
 
         baseline : float, array-like or None, default: 0
-            Determines bottom value of the bounding edges or when
-            ``fill=True``, position of lower edge.
+            The bottom value of the bounding edges or when
+            ``fill=True``, position of lower edge. If *fill* is
+            True or an array is passed to *baseline*, a closed
+            path is drawn.
 
         fill : bool, default: False
             Whether the area under the step curve should be filled.

lib/matplotlib/patches.py

@@ -4,6 +4,7 @@
 import math
 from numbers import Number
 import textwrap
+from collections import namedtuple
 
 import numpy as np
 
@@ -920,7 +921,8 @@ class StepPatch(PathPatch):
     """
     A path patch describing a stepwise constant function.
 
-    The path is unclosed. It starts and stops at baseline.
+    By default the path is not closed and starts and stops at
+    baseline value.
     """
 
     _edge_default = False
@@ -939,12 +941,14 @@ def __init__(self, values, edges, *,
             between which the curve takes on vals values.
 
         orientation : {'vertical', 'horizontal'}, default: 'vertical'
-            The direction of the steps. Vertical means that *values* are along
-            the y-axis, and edges are along the x-axis.
+            The direction of the steps. Vertical means that *values* are
+            along the y-axis, and edges are along the x-axis.
 
-        baseline : float, 1D array-like or None, default: 0
-            Determines bottom value of the bounding edges or when
-            ``fill=True``, position of lower edge.
+        baseline : float, array-like or None, default: 0
+            The bottom value of the bounding edges or when
+            ``fill=True``, position of lower edge. If *fill* is
+            True or an array is passed to *baseline*, a closed
+            path is drawn.
 
         Other valid keyword arguments are:
 
@@ -993,12 +997,13 @@ def _update_path(self):
             self._path = Path(np.vstack(verts), np.hstack(codes))
 
     def get_data(self):
-        """Get `.StepPatch` values, edges and baseline."""
-        return self._values, self._edges, self._baseline
+        """Get `.StepPatch` values, edges and baseline as namedtuple."""
+        StairData = namedtuple('StairData', 'values edges baseline')
+        return StairData(self._values, self._edges, self._baseline)
 
-    def set_data(self, values, edges=None, baseline=None):
+    def set_data(self, values=None, edges=None, baseline=None):
         """
-        Set `.StepPatch` values and optionally edges and baseline.
+        Set `.StepPatch` values, edges and baseline.
 
         Parameters
         ----------
@@ -1007,6 +1012,8 @@ def set_data(self, values, edges=None, baseline=None):
         edges : 1D array-like, optional
         baseline : float, 1D array-like or None
         """
+        if values is None and edges is None and baseline is None:
+            raise ValueError("Must set *values*, *edges* or *baseline*.")
         if values is not None:
             self._values = np.asarray(values)
         if edges is not None:
@@ -1016,40 +1023,6 @@ def set_data(self, values, edges=None, baseline=None):
         self._update_path()
         self.stale = True
 
-    def set_values(self, values):
-        """
-        Set `.StepPatch` values.
-
-        Parameters
-        ----------
-        values : 1D array-like
-        """
-        self.set_data(values, edges=None, baseline=None)
-
-    def set_edges(self, edges):
-        """
-        Set `.StepPatch` edges.
-
-        Parameters
-        ----------
-        edges : 1D array-like
-        """
-        self.set_data(None, edges=edges, baseline=None)
-
-    def get_baseline(self):
-        """Get `.StepPatch` baseline."""
-        return self._baseline
-
-    def set_baseline(self, baseline):
-        """
-        Set `.StepPatch` baseline.
-
-        Parameters
-        ----------
-        baseline : float, array-like or None, default: 0
-        """
-        self.set_data(None, edges=None, baseline=baseline)
-
 
 class Polygon(Patch):
     """A general polygon patch."""

lib/matplotlib/tests/test_axes.py

@@ -1884,15 +1884,15 @@ def test_stairs_update(fig_test, fig_ref):
     test_ax = fig_test.add_subplot()
     h = test_ax.stairs([1, 2, 3])
     test_ax.set_ylim(ylim)
-    h.set_values([3, 2, 1])
-    h.set_edges(np.arange(4)+2)
+    h.set_data([3, 2, 1])
+    h.set_data(edges=np.arange(4)+2)
     h.set_data([1, 2, 1], np.arange(4)/2)
     h.set_data([1, 2, 3])
     h.set_data(None, np.arange(4))
     assert np.allclose(h.get_data()[0], np.arange(1, 4))
     assert np.allclose(h.get_data()[1], np.arange(4))
-    h.set_baseline(-2)
-    assert h.get_baseline() == -2
+    h.set_data(baseline=-2)
+    assert h.get_data().baseline == -2
 
     # Ref
     ref_ax = fig_ref.add_subplot()
@@ -1913,13 +1913,13 @@ def test_stairs_invalid_mismatch():
 def test_stairs_invalid_update():
     h = plt.stairs([1, 2], [0, 1, 2])
     with pytest.raises(ValueError, match='Nan values in "edges"'):
-        h.set_edges([1, np.nan, 2])
+        h.set_data(edges=[1, np.nan, 2])
 
 
 def test_stairs_invalid_update2():
     h = plt.stairs([1, 2], [0, 1, 2])
     with pytest.raises(ValueError, match='Size mismatch'):
-        h.set_edges(np.arange(5))
+        h.set_data(edges=np.arange(5))
 
 
 @image_comparison(['test_stairs_options.png'], remove_text=True)