DOC: talk about sticky edges in Axes.margins

phobson · phobson · commit 56875796786b · 2018-06-29T14:11:21.000-07:00
starts to address the confusion mentioned in #11534
diff --git a/examples/subplots_axes_and_figures/axes_margins.py b/examples/subplots_axes_and_figures/axes_margins.py
@@ -1,10 +1,14 @@
 """
-=====================================
-Zooming in and out using Axes.margins
-=====================================
+=====================================================================
+Zooming in and out using Axes.margins and the subject of "stickiness"
+=====================================================================
+
+The first figure in this example shows how to zoom in and out of a
+plot using `~.Axes.margins` instead of `~.Axes.set_xlim` and
+`~.Axes.set_ylim`. The second figure demonstrates the concept of
+edge "stickiness" introduced by certain methods and artists and how
+to effectively work around that.
 
-This example shows how to zoom in and out of a plot using `~.Axes.margins`
-instead of `~.Axes.set_xlim` and `~.Axes.set_ylim`.
 """
 
 import numpy as np
@@ -32,3 +36,57 @@ def f(t):
 ax3.set_title('Zoomed in')
 
 plt.show()
+
+
+#############################################################################
+#
+# On the "stickiness" of certain plotting methods
+# """""""""""""""""""""""""""""""""""""""""""""""
+#
+# Some plotting functions make the axis limits "sticky" or immune to the will
+# of the `~.Axes.margins` methods. For instance, `~.Axes.imshow` and
+# `~.Axes.pcolor` expect the user to want the limits to be tight around the
+# pixels shown in the plot. If this behavior is not desired, you need to set
+# `~.Axes.use_sticky_edges` to `False`. Consider the following example:
+
+y, x = np.mgrid[:5, 1:6]
+poly_coords = [
+    (0.25, 2.75), (3.25, 2.75),
+    (2.25, 0.75), (0.25, 0.75)
+]
+fig, (ax1, ax2) =  plt.subplots(ncols=2)
+
+# Here we set the stickiness of the axes object...
+# ax1 we'll leave as the default, which uses sticky edges
+# and we'll turn off stickiness for ax2
+ax2.use_sticky_edges = False
+
+for ax, status in zip((ax1, ax2), ('Is', 'Is Not')):
+    cells = ax.pcolor(x, y, x+y, cmap='inferno')  # sticky
+    ax.add_patch(
+        plt.Polygon(poly_coords, color='forestgreen', alpha=0.5)
+    )  # not sticky
+    ax.margins(x=0.1, y=0.05)
+    ax.set_aspect('equal')
+    ax.set_title('{} Sticky'.format(status))
+
+plt.show()
+
+
+#############################################################################
+#
+# ------------
+#
+# References
+# """"""""""
+#
+# The use of the following functions, methods is shown
+# in this example:
+
+import matplotlib
+matplotlib.axes.Axes.margins
+matplotlib.pyplot.margins
+matplotlib.axes.Axes.use_sticky_edges
+matplotlib.axes.Axes.pcolor
+matplotlib.pyplot.pcolor
+matplotlib.pyplot.Polygon
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -2227,41 +2227,58 @@ def margins(self, *margins, x=None, y=None, tight=True):
         """
         Set or retrieve autoscaling margins.
 
-        signatures::
+        The padding added to each limit of the axes is the *margin*
+        times the data interval. All input parameters must be floats
+        within the range [0, 1]. Passing both positional and keyword
+        arguments is invalid and will raise a TypeError. If no
+        arguments (positional or otherwise) are provided, the current
+        margins will remain in place and simply be returned.
 
-            margins()
-
-        returns xmargin, ymargin
-
-        ::
-
-            margins(margin)
-
-            margins(xmargin, ymargin)
+        Specifying any margin changes only the autoscaling; for example,
+        if *xmargin* is not None, then *xmargin* times the X data
+        interval will be added to each end of that interval before
+        it is used in autoscaling.
 
-            margins(x=xmargin, y=ymargin)
+        Parameters
+        ----------
+        args : float, optional
+            If a single positional argument is provided, it specifies
+            both margins of the x-axis and y-axis limits. If two
+            positional arguments are provided, they will be interpreted
+            as *xmargin*, *ymargin*. If setting the margin on a single
+            axis is desired, use the keyword arguments described below.
+
+        x, y : float, optional
+            Specific margin values for the x-axis and y-axis,
+            respectively. These cannot be used with positional
+            arguments, but can be used individually to alter on e.g.,
+            only the y-axis.
+
+        tight : bool, default is True
+            The *tight* parameter is passed to :meth:`autoscale_view`,
+            which is executed after a margin is changed; the default
+            here is *True*, on the assumption that when margins are
+            specified, no additional padding to match tick marks is
+            usually desired.  Set *tight* to *None* will preserve
+            the previous setting.
 
-            margins(..., tight=False)
 
-        All three forms above set the xmargin and ymargin parameters.
-        All keyword parameters are optional.  A single positional argument
-        specifies both xmargin and ymargin. The padding added to the end of
-        each interval is *margin* times the data interval. The *margin* must
-        be a float in the range [0, 1].  Passing both positional and keyword
-        arguments for xmargin and/or ymargin is invalid.
+        Returns
+        -------
+        xmargin, ymargin : float
 
-        The *tight* parameter is passed to :meth:`autoscale_view`
-        , which is executed after a margin is changed; the default here is
-        *True*, on the assumption that when margins are specified, no
-        additional padding to match tick marks is usually desired.  Setting
-        *tight* to *None* will preserve the previous setting.
+        Notes
+        -----
+        If a previously used Axes method such as :meth:`pcolor` has set
+        :attr:`use_sticky_edges` to `True`, only the limits not set by
+        the "sticky artists" will be modified. To force all of the
+        margins to be set, set :attr:`use_sticky_edges` to `False`
+        before calling :meth:`margins`.
 
-        Specifying any margin changes only the autoscaling; for example,
-        if *xmargin* is not None, then *xmargin* times the X data
-        interval will be added to each end of that interval before
-        it is used in autoscaling.
+        .. plot:: gallery/subplots_axes_and_figures/axes_margins.py
 
         """
+
         if margins and x is not None and y is not None:
             raise TypeError('Cannot pass both positional and keyword '
                             'arguments for x and/or y.')
