feat: rename levels to stairs

andrzejnovak · andrzejnovak · commit aa905acd787e · 2020-09-09T17:50:57.000+02:00
diff --git a/doc/api/artist_api.rst b/doc/api/artist_api.rst
@@ -4,7 +4,7 @@
 ``matplotlib.artist``
 *********************
 
-.. inheritance-diagram:: matplotlib.axes._axes.Axes matplotlib.axes._base._AxesBase matplotlib.axis.Axis matplotlib.axis.Tick matplotlib.axis.XAxis matplotlib.axis.XTick matplotlib.axis.YAxis matplotlib.axis.YTick matplotlib.collections.AsteriskPolygonCollection matplotlib.collections.BrokenBarHCollection matplotlib.collections.CircleCollection matplotlib.collections.Collection matplotlib.collections.EllipseCollection matplotlib.collections.EventCollection matplotlib.collections.LineCollection matplotlib.collections.PatchCollection matplotlib.collections.PathCollection matplotlib.collections.PolyCollection matplotlib.collections.QuadMesh matplotlib.collections.RegularPolyCollection matplotlib.collections.StarPolygonCollection matplotlib.collections.TriMesh matplotlib.collections._CollectionWithSizes matplotlib.contour.ClabelText matplotlib.figure.Figure matplotlib.image.AxesImage matplotlib.image.BboxImage matplotlib.image.FigureImage matplotlib.image.NonUniformImage matplotlib.image.PcolorImage matplotlib.image._ImageBase matplotlib.legend.Legend matplotlib.lines.Line2D matplotlib.offsetbox.AnchoredOffsetbox matplotlib.offsetbox.AnchoredText matplotlib.offsetbox.AnnotationBbox matplotlib.offsetbox.AuxTransformBox matplotlib.offsetbox.DrawingArea matplotlib.offsetbox.HPacker matplotlib.offsetbox.OffsetBox matplotlib.offsetbox.OffsetImage matplotlib.offsetbox.PackerBase matplotlib.offsetbox.PaddedBox matplotlib.offsetbox.TextArea matplotlib.offsetbox.VPacker matplotlib.patches.Arc matplotlib.patches.Arrow matplotlib.patches.Circle matplotlib.patches.CirclePolygon matplotlib.patches.ConnectionPatch matplotlib.patches.Ellipse matplotlib.patches.FancyArrow matplotlib.patches.FancyArrowPatch matplotlib.patches.FancyBboxPatch matplotlib.patches.Patch matplotlib.patches.PathPatch matplotlib.patches.LevelsPatch matplotlib.patches.Polygon matplotlib.patches.Rectangle matplotlib.patches.RegularPolygon matplotlib.patches.Shadow matplotlib.patches.Wedge matplotlib.projections.geo.AitoffAxes matplotlib.projections.geo.GeoAxes matplotlib.projections.geo.HammerAxes matplotlib.projections.geo.LambertAxes matplotlib.projections.geo.MollweideAxes matplotlib.projections.polar.PolarAxes matplotlib.quiver.Barbs matplotlib.quiver.Quiver matplotlib.quiver.QuiverKey matplotlib.spines.Spine matplotlib.table.Cell matplotlib.table.CustomCell matplotlib.table.Table matplotlib.text.Annotation matplotlib.text.Text
+.. inheritance-diagram:: matplotlib.axes._axes.Axes matplotlib.axes._base._AxesBase matplotlib.axis.Axis matplotlib.axis.Tick matplotlib.axis.XAxis matplotlib.axis.XTick matplotlib.axis.YAxis matplotlib.axis.YTick matplotlib.collections.AsteriskPolygonCollection matplotlib.collections.BrokenBarHCollection matplotlib.collections.CircleCollection matplotlib.collections.Collection matplotlib.collections.EllipseCollection matplotlib.collections.EventCollection matplotlib.collections.LineCollection matplotlib.collections.PatchCollection matplotlib.collections.PathCollection matplotlib.collections.PolyCollection matplotlib.collections.QuadMesh matplotlib.collections.RegularPolyCollection matplotlib.collections.StarPolygonCollection matplotlib.collections.TriMesh matplotlib.collections._CollectionWithSizes matplotlib.contour.ClabelText matplotlib.figure.Figure matplotlib.image.AxesImage matplotlib.image.BboxImage matplotlib.image.FigureImage matplotlib.image.NonUniformImage matplotlib.image.PcolorImage matplotlib.image._ImageBase matplotlib.legend.Legend matplotlib.lines.Line2D matplotlib.offsetbox.AnchoredOffsetbox matplotlib.offsetbox.AnchoredText matplotlib.offsetbox.AnnotationBbox matplotlib.offsetbox.AuxTransformBox matplotlib.offsetbox.DrawingArea matplotlib.offsetbox.HPacker matplotlib.offsetbox.OffsetBox matplotlib.offsetbox.OffsetImage matplotlib.offsetbox.PackerBase matplotlib.offsetbox.PaddedBox matplotlib.offsetbox.TextArea matplotlib.offsetbox.VPacker matplotlib.patches.Arc matplotlib.patches.Arrow matplotlib.patches.Circle matplotlib.patches.CirclePolygon matplotlib.patches.ConnectionPatch matplotlib.patches.Ellipse matplotlib.patches.FancyArrow matplotlib.patches.FancyArrowPatch matplotlib.patches.FancyBboxPatch matplotlib.patches.Patch matplotlib.patches.PathPatch matplotlib.patches.StepPatch matplotlib.patches.Polygon matplotlib.patches.Rectangle matplotlib.patches.RegularPolygon matplotlib.patches.Shadow matplotlib.patches.Wedge matplotlib.projections.geo.AitoffAxes matplotlib.projections.geo.GeoAxes matplotlib.projections.geo.HammerAxes matplotlib.projections.geo.LambertAxes matplotlib.projections.geo.MollweideAxes matplotlib.projections.polar.PolarAxes matplotlib.quiver.Barbs matplotlib.quiver.Quiver matplotlib.quiver.QuiverKey matplotlib.spines.Spine matplotlib.table.Cell matplotlib.table.CustomCell matplotlib.table.Table matplotlib.text.Annotation matplotlib.text.Text
    :parts: 1
    :private-bases:
 
diff --git a/doc/api/patches_api.rst b/doc/api/patches_api.rst
@@ -29,7 +29,7 @@ Classes
    FancyBboxPatch
    Patch
    PathPatch
-   LevelsPatch
+   StepPatch
    Polygon
    Rectangle
    RegularPolygon
diff --git a/doc/users/next_whats_new/steppatch_and_stairs.rst b/doc/users/next_whats_new/steppatch_and_stairs.rst
@@ -1,5 +1,5 @@
-New `~.matplotlib.patches.LevelsPatch` artist and a `.pyplot.levels` method
----------------------------------------------------------------------------
+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.
 
@@ -14,9 +14,9 @@ x-like edges, between which the values lie.
 
     fig, ax = plt.subplots(constrained_layout=True)
 
-    ax.levels(h, bins)
+    ax.stairs(h, bins)
 
     plt.show()
 
-See :doc:`/gallery/lines_bars_and_markers/levels_demo`
+See :doc:`/gallery/lines_bars_and_markers/stairs_demo`
 for examples.
diff --git a/examples/lines_bars_and_markers/stairs_demo.py b/examples/lines_bars_and_markers/stairs_demo.py
@@ -3,41 +3,41 @@
 Histline Demo
 =============
 
-This example demonstrates the use of `~.matplotlib.pyplot.levels`
+This example demonstrates the use of `~.matplotlib.pyplot.stairs`
 for histogram and histogram-like data visualization and an associated
-underlying `.LevelsPatch` artist, which is
+underlying `.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 LevelsPatch
+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].levels(h, bins, label='Simple histogram')
-axs[0].levels(h, bins+5, baseline=50, label='--//-- w/ modified baseline')
-axs[0].levels(h, bins+10, baseline=None, label='--//-- w/ no edges')
+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].set_title("Step Histograms")
 
-axs[1].levels(np.arange(1, 6, 1), fill=True,
+axs[1].stairs(np.arange(1, 6, 1), fill=True,
               label='Filled histogram\nw/ automatatic edges')
-axs[1].levels(np.arange(1, 6, 1)*0.3, np.arange(2, 8, 1),
+axs[1].stairs(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 = LevelsPatch(values=[1, 2, 3, 2, 1],
-                    edges=range(1, 7),
-                    label=('Patch derived underlying object\n'
-                           'with default edge/facecolor behaviour'))
+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("LevelsPatch artist")
+axs[2].set_title("StepPatch artist")
 
 for ax in axs:
     ax.legend()
@@ -55,6 +55,6 @@
 # in this example:
 
 import matplotlib
-matplotlib.axes.Axes.levels
-matplotlib.pyplot.levels
-matplotlib.patches.LevelsPatch
+matplotlib.axes.Axes.stairs
+matplotlib.pyplot.stairs
+matplotlib.patches.StepPatch
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -6872,7 +6872,7 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
             return tops, bins, cbook.silent_list(patch_type, patches)
 
     @_preprocess_data()
-    def levels(self, values, edges=None, *,
+    def stairs(self, values, edges=None, *,
                orientation='vertical', baseline=0, fill=False, **kwargs):
         """
         A histogram-like line or filled plot.
@@ -6896,12 +6896,12 @@ def levels(self, values, edges=None, *,
 
         Returns
         -------
-        LevelsPatch : `matplotlib.patches.LevelsPatch`
+        StepPatch : `matplotlib.patches.StepPatch`
 
         Other Parameters
         ----------------
         **kwargs
-            `~matplotlib.patches.LevelsPatch` properties
+            `~matplotlib.patches.StepPatch` properties
 
         """
 
@@ -6918,12 +6918,12 @@ def levels(self, values, edges=None, *,
         if edges is None:
             edges = np.arange(len(values) + 1)
 
-        patch = mpatches.LevelsPatch(values,
-                                     edges,
-                                     baseline=baseline,
-                                     orientation=orientation,
-                                     fill=fill,
-                                     **kwargs)
+        patch = mpatches.StepPatch(values,
+                                   edges,
+                                   baseline=baseline,
+                                   orientation=orientation,
+                                   fill=fill,
+                                   **kwargs)
         self.add_patch(patch)
         if baseline is None:
             baseline = 0
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -34,7 +34,7 @@
 from matplotlib.font_manager import FontProperties
 from matplotlib.lines import Line2D
 from matplotlib.patches import (Patch, Rectangle, Shadow, FancyBboxPatch,
-                                LevelsPatch)
+                                StepPatch)
 from matplotlib.collections import (LineCollection, RegularPolyCollection,
                                     CircleCollection, PathCollection,
                                     PolyCollection)
@@ -624,7 +624,7 @@ def draw(self, renderer):
         ErrorbarContainer: legend_handler.HandlerErrorbar(),
         Line2D: legend_handler.HandlerLine2D(),
         Patch: legend_handler.HandlerPatch(),
-        LevelsPatch: legend_handler.HandlerLevelsPatch(),
+        StepPatch: legend_handler.HandlerStepPatch(),
         LineCollection: legend_handler.HandlerLineCollection(),
         RegularPolyCollection: legend_handler.HandlerRegularPolyCollection(),
         CircleCollection: legend_handler.HandlerCircleCollection(),
diff --git a/lib/matplotlib/legend_handler.py b/lib/matplotlib/legend_handler.py
@@ -302,9 +302,9 @@ def create_artists(self, legend, orig_handle,
         return [p]
 
 
-class HandlerLevelsPatch(HandlerBase):
+class HandlerStepPatch(HandlerBase):
     """
-    Handler for `~.matplotlib.patches.LevelsPatch` instances.
+    Handler for `~.matplotlib.patches.StepPatch` instances.
     """
     def __init__(self, **kw):
         """
@@ -319,7 +319,7 @@ def _create_patch(self, legend, orig_handle,
                       width=width, height=height)
         return p
 
-    # Unfilled LevelsPatch should show as a line
+    # Unfilled StepPatch should show as a line
     def _create_line(self, legend, orig_handle,
                      xdescent, ydescent, width, height, fontsize):
 
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -989,8 +989,8 @@ def set_path(self, path):
         self._path = path
 
 
-class LevelsPatch(PathPatch):
-    """An unclosed levels path patch."""
+class StepPatch(PathPatch):
+    """An unclosed step path patch."""
 
     @docstring.dedent_interpd
     def __init__(self, values, edges, *,
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2778,11 +2778,11 @@ def hist(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_copy_docstring_and_deprecators(Axes.levels)
-def levels(
+@_copy_docstring_and_deprecators(Axes.stairs)
+def stairs(
         values, edges=None, *, orientation='vertical', baseline=0,
         fill=False, data=None, **kwargs):
-    return gca().levels(
+    return gca().stairs(
         values, edges=edges, 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_stairs_options.png b/lib/matplotlib/tests/baseline_images/test_axes/test_stairs_options.png
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -1745,20 +1745,20 @@ def test_hist_zorder(histtype, zorder):
 
 
 @check_figures_equal()
-def test_levels(fig_test, fig_ref):
+def test_stairs(fig_test, fig_ref):
     import matplotlib.lines as mlines
     y = np.array([6, 14, 32, 37, 48, 32, 21,  4])  # hist
     x = np.array([1., 2., 3., 4., 5., 6., 7., 8., 9.])  # bins
 
     fig_test, test_axes = plt.subplots(3, 2)
     test_axes = test_axes.flatten()
-    test_axes[0].levels(y, x, baseline=None)
-    test_axes[1].levels(y, x, baseline=None, orientation='horizontal')
-    test_axes[2].levels(y, x)
-    test_axes[3].levels(y, x, orientation='horizontal')
-    test_axes[4].levels(y, x)
+    test_axes[0].stairs(y, x, baseline=None)
+    test_axes[1].stairs(y, x, baseline=None, orientation='horizontal')
+    test_axes[2].stairs(y, x)
+    test_axes[3].stairs(y, x, orientation='horizontal')
+    test_axes[4].stairs(y, x)
     test_axes[4].semilogy()
-    test_axes[5].levels(y, x, orientation='horizontal')
+    test_axes[5].stairs(y, x, orientation='horizontal')
     test_axes[5].semilogy()
 
     fig_ref, ref_axes = plt.subplots(3, 2)
@@ -1788,16 +1788,16 @@ def test_levels(fig_test, fig_ref):
 
 
 @check_figures_equal()
-def test_levels_fill(fig_test, fig_ref):
+def test_stairs_fill(fig_test, fig_ref):
     h, bins = [1, 2, 3, 4, 2], [0, 1, 2, 3, 4, 5]
     bs = -2
     # Test
     fig_test, test_axes = plt.subplots(2, 2)
     test_axes = test_axes.flatten()
-    test_axes[0].levels(h, bins, fill=True)
-    test_axes[1].levels(h, bins, orientation='horizontal', fill=True)
-    test_axes[2].levels(h, bins, baseline=bs, fill=True)
-    test_axes[3].levels(h, bins, baseline=bs, orientation='horizontal',
+    test_axes[0].stairs(h, bins, fill=True)
+    test_axes[1].stairs(h, bins, orientation='horizontal', fill=True)
+    test_axes[2].stairs(h, bins, baseline=bs, fill=True)
+    test_axes[3].stairs(h, bins, baseline=bs, orientation='horizontal',
                           fill=True)
 
     # # Ref
@@ -1815,22 +1815,22 @@ def test_levels_fill(fig_test, fig_ref):
     ref_axes[3].set_xlim(bs, None)
 
 
-@image_comparison(['test_levels_options.png'], remove_text=True)
-def test_levels_options():
+@image_comparison(['test_stairs_options.png'], remove_text=True)
+def test_stairs_options():
     x, y = np.array([1, 2, 3, 4, 5]), np.array([1, 2, 3, 4]).astype(float)
     yn = y.copy()
     yn[1] = np.nan
 
     fig, ax = plt.subplots()
-    ax.levels(y*3, x, color='green', fill=True, label="A")
-    ax.levels(y, x*3-3, color='red', fill=True,
+    ax.stairs(y*3, x, color='green', fill=True, label="A")
+    ax.stairs(y, x*3-3, color='red', fill=True,
                 orientation='horizontal', label="B")
-    ax.levels(yn, x, color='orange', ls='--', lw=2, label="C")
-    ax.levels(yn/3, x*3-2, color='purple', ls='--', lw=2, baseline=0.5,
+    ax.stairs(yn, x, color='orange', ls='--', lw=2, label="C")
+    ax.stairs(yn/3, x*3-2, color='purple', ls='--', lw=2, baseline=0.5,
                 orientation='horizontal', label="D")
-    ax.levels(y[::-1]*3+12, x, color='red', ls='--', lw=2, baseline=None,
+    ax.stairs(y[::-1]*3+12, x, color='red', ls='--', lw=2, baseline=None,
                 label="E")
-    ax.levels(y[:-1][::-1]*2+11, x[:-1]+0.5, color='blue', ls='--', lw=2,
+    ax.stairs(y[:-1][::-1]*2+11, x[:-1]+0.5, color='blue', ls='--', lw=2,
                 baseline=12, hatch='//', label="F")
     ax.legend(loc=0)
 
diff --git a/tools/boilerplate.py b/tools/boilerplate.py
@@ -215,7 +215,7 @@ def boilerplate_gen():
         'grid',
         'hexbin',
         'hist',
-        'levels',
+        'stairs',
         'hist2d',
         'hlines',
         'imshow',
