feat: Add histline/StepPatch demo and what's new

andrzejnovak · andrzejnovak · commit e24ec9376e00 · 2020-09-09T17:50:57.000+02:00
diff --git a/.flake8 b/.flake8
@@ -162,6 +162,7 @@ per-file-ignores =
     examples/lines_bars_and_markers/fill.py: E402
     examples/lines_bars_and_markers/fill_between_demo.py: E402
     examples/lines_bars_and_markers/filled_step.py: E402
+    examples/lines_bars_and_markers/histline_demo.py: E402
     examples/lines_bars_and_markers/horizontal_barchart_distribution.py: E402
     examples/lines_bars_and_markers/joinstyle.py: E402
     examples/lines_bars_and_markers/scatter_hist.py: E402
diff --git a/doc/users/next_whats_new/steppatch_and_histline.rst b/doc/users/next_whats_new/steppatch_and_histline.rst
@@ -0,0 +1,22 @@
+New `~.matplotlib.patches.StepPatch` artist and a `.pyplot.histline` method
+---------------------------------------------------------------------------
+These take inputs of asymmetric lengths with y-like values and 
+x-like edges, between which the values lie.
+
+  .. plot::
+
+    import numpy as np
+    import matplotlib.pyplot as plt
+
+    np.random.seed(0)
+    h, bins = np.histogram(np.random.normal(5, 2, 5000),
+                           bins=np.linspace(0,10,20))
+
+    fig, ax = plt.subplots(constrained_layout=True)
+
+    ax.histline(h, bins)
+
+    plt.show()
+
+See :doc:`/gallery/lines_bars_and_markers/histline_demo`
+for examples.
diff --git a/examples/lines_bars_and_markers/histline_demo.py b/examples/lines_bars_and_markers/histline_demo.py
@@ -0,0 +1,60 @@
+"""
+=============
+Histline Demo
+=============
+
+This example demonstrates the use of `~.matplotlib.pyplot.histline`
+for histogram and histogram-like data visualization and an associated
+underlying `~.matplotlib.patches.StepPatch` artist, which is
+a contrained version of `.PathPatch` specified by its bins and edges.
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+from matplotlib.patches import StepPatch
+
+np.random.seed(0)
+h, bins = np.histogram(np.random.normal(5, 3, 5000),
+                       bins=np.linspace(0, 10, 20))
+
+fig, axs = plt.subplots(3, 1, figsize=(7, 15))
+axs[0].histline(h, bins, label='Simple histogram')
+axs[0].histline(h, bins+5, baseline=50, label='--//-- w/ modified baseline')
+axs[0].histline(h, bins+10, baseline=None, label='--//-- w/ no edges')
+axs[0].set_title("Step Histograms")
+
+axs[1].histline(np.arange(1, 6, 1), fill=True,
+                label='Filled histogram\nw/ automatatic edges')
+axs[1].histline(np.arange(1, 6, 1)*0.3, np.arange(2, 8, 1),
+                orientation='horizontal', hatch='//',
+                label='Hatched histogram\nw/ horizontal orientation')
+axs[1].set_title("Filled histogram")
+
+patch = StepPatch(values=[1, 2, 3, 2, 1],
+                  edges=range(1, 7),
+                  label=('Patch derived underlying object\n'
+                         'with default edge/facecolor behaviour'))
+axs[2].add_patch(patch)
+axs[2].set_xlim(0, 7)
+axs[2].set_ylim(-1, 5)
+axs[2].set_title("StepPatch artist")
+
+for ax in axs:
+    ax.legend()
+plt.show()
+
+
+#############################################################################
+#
+# ------------
+#
+# References
+# """"""""""
+#
+# The use of the following functions, methods, classes and modules is shown
+# in this example:
+
+import matplotlib
+matplotlib.axes.Axes.histline
+matplotlib.pyplot.histline
+matplotlib.patches.StepPatch
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -6872,36 +6872,36 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
             return tops, bins, cbook.silent_list(patch_type, patches)
 
     @_preprocess_data()
-    def histline(self, vals, bins=None, *,
+    def histline(self, values, bins=None, *,
                  orientation='vertical', baseline=0, fill=False, **kwargs):
         """
         A histogram-like line or filled plot.
 
         Parameters
         ----------
-        vals : array
+        values : array-like
             An array of y-values.
 
-        bins : array, default: ``range(len(vals)+1)``
+        bins : array-like, default: ``range(len(vals)+1)``
             A array of x-values, with ``len(bins) == len(vals) + 1``,
             between which the curve takes on vals values.
 
         orientation : {'vertical', 'horizontal'}, default: 'vertical'
 
         baseline : float or None, default: 0
             Determines starting value of the bounding edges or when
-            "fill" == True, position of lower edge.
+            ``fill=True``, position of lower edge.
 
         fill : bool, default: False
 
         Returns
         -------
-        patch : `.StepPatch`
+        StepPatch : `.patches.StepPatch`
 
         Other Parameters
         ----------------
         **kwargs
-            `~matplotlib.patches.Patch` properties
+            `~.matplotlib.patches.StepPatch` properties
 
         """
 
@@ -6916,9 +6916,9 @@ def histline(self, vals, bins=None, *,
             kwargs.setdefault('edgecolor', _color)
 
         if bins is None:
-            bins = np.arange(len(vals) + 1)
+            bins = np.arange(len(values) + 1)
 
-        patch = mpatches.StepPatch(vals,
+        patch = mpatches.StepPatch(values,
                                    bins,
                                    baseline=baseline,
                                    orientation=orientation,
diff --git a/lib/matplotlib/legend_handler.py b/lib/matplotlib/legend_handler.py
@@ -304,7 +304,7 @@ def create_artists(self, legend, orig_handle,
 
 class HandlerStepPatch(HandlerBase):
     """
-    Handler for `.StepPatch` instances.
+    Handler for `~.matplotlib.patches.StepPatch` instances.
     """
     def __init__(self, **kw):
         """
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -993,23 +993,23 @@ class StepPatch(PathPatch):
     """An unclosed stepline path patch."""
 
     @docstring.dedent_interpd
-    def __init__(self, vals, edges, *,
-                 orientation='horizontal', baseline=0, **kwargs):
+    def __init__(self, values, edges, *,
+                 orientation='vertical', baseline=0, **kwargs):
         """
         Parameters
         ----------
-        vals : array
+        values : array-like
             An array of y-values.
 
-        edges : array
+        edges : array-like
             A array of x-value edges, with ``len(edges) == len(vals) + 1``,
             between which the curve takes on vals values.
 
         orientation : {'vertical', 'horizontal'}, default: 'vertical'
 
         baseline : float or None, default: 0
             Determines starting value of the bounding edges or when
-            "fill" == True, position of lower edge.
+            ``fill=True``, position of lower edge.
 
         Other valid keyword arguments are:
 
@@ -1018,20 +1018,24 @@ def __init__(self, vals, edges, *,
         self.baseline = baseline
         self.orientation = orientation
         self._edges = np.asarray(edges)
-        self._vals = np.asarray(vals)
+        self._values = np.asarray(values)
         verts, codes = self._update_data()
         path = Path(verts, codes)
         super().__init__(path, **kwargs)
 
     def _update_data(self):
-        if self._edges.size - 1 != self._vals.size:
-            raise ValueError('Size mismatch between "vals" and "edges"')
+        if self._edges.size - 1 != self._values.size:
+            raise ValueError('Size mismatch between "values" and "edges". '
+                             "Expected `len(values) + 1 == len(edges)`, but "
+                             "they are or lengths {} and {}".format(
+                                 self._edges.size, self._values.size)
+                             )
         verts, codes = [], []
-        for idx0, idx1 in cbook.contiguous_regions(~np.isnan(self._vals)):
+        for idx0, idx1 in cbook.contiguous_regions(~np.isnan(self._values)):
             x = np.vstack((self._edges[idx0:idx1+1],
                            self._edges[idx0:idx1+1])).T.flatten()
-            y = np.vstack((self._vals[idx0:idx1],
-                           self._vals[idx0:idx1])).T.flatten()
+            y = np.vstack((self._values[idx0:idx1],
+                           self._values[idx0:idx1])).T.flatten()
             if self.baseline is not None:
                 y = np.hstack((self.baseline, y, self.baseline))
             else:
@@ -1048,13 +1052,8 @@ def set_edges(self, edges):
         self._edges = np.asarray(edges)
         self._update_data()
 
-    def set_vals(self, vals):
-        self._vals = np.asarray(vals)
-        self._update_data()
-
-    def set_vals_edges(self, vals, edges):
-        self._vals = np.asarray(vals)
-        self._edegs = np.asarray(edges)
+    def set_values(self, values):
+        self._values = np.asarray(values)
         self._update_data()
 
 
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2780,10 +2780,10 @@ def hist(
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
 @_copy_docstring_and_deprecators(Axes.histline)
 def histline(
-        vals, bins=None, *, orientation='vertical', baseline=0,
+        values, bins=None, *, orientation='vertical', baseline=0,
         fill=False, data=None, **kwargs):
     return gca().histline(
-        vals, bins=bins, orientation=orientation, baseline=baseline,
+        values, bins=bins, orientation=orientation, baseline=baseline,
         fill=fill, **({"data": data} if data is not None else {}),
         **kwargs)
 
diff --git a/lib/matplotlib/tests/baseline_images/test_axes/test_histline_options.png b/lib/matplotlib/tests/baseline_images/test_axes/test_histline_options.png
diff --git a/lib/matplotlib/tests/baseline_images/test_axes/test_histline_options.svg b/lib/matplotlib/tests/baseline_images/test_axes/test_histline_options.svg
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
