Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit dcbf144

Browse files
NelleVNelleV
authored
Merge pull request #11539 from phobson/sticky-margins
DOC: talk about sticky edges in Axes.margins
2 parents a0994d3 + e0b7cc7 commit dcbf144

2 files changed

Lines changed: 106 additions & 33 deletions

File tree

‎examples/subplots_axes_and_figures/axes_margins.py‎

Lines changed: 63 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
11
"""
2-
=====================================
3-
Zooming in and out using Axes.margins
4-
=====================================
2+
=====================================================================
3+
Zooming in and out using Axes.margins and the subject of "stickiness"
4+
=====================================================================
5+
6+
The first figure in this example shows how to zoom in and out of a
7+
plot using `~.Axes.margins` instead of `~.Axes.set_xlim` and
8+
`~.Axes.set_ylim`. The second figure demonstrates the concept of
9+
edge "stickiness" introduced by certain methods and artists and how
10+
to effectively work around that.
511
6-
This example shows how to zoom in and out of a plot using `~.Axes.margins`
7-
instead of `~.Axes.set_xlim` and `~.Axes.set_ylim`.
812
"""
913

1014
import numpy as np
@@ -32,3 +36,57 @@ def f(t):
3236
ax3.set_title('Zoomed in')
3337

3438
plt.show()
39+
40+
41+
#############################################################################
42+
#
43+
# On the "stickiness" of certain plotting methods
44+
# """""""""""""""""""""""""""""""""""""""""""""""
45+
#
46+
# Some plotting functions make the axis limits "sticky" or immune to the will
47+
# of the `~.Axes.margins` methods. For instance, `~.Axes.imshow` and
48+
# `~.Axes.pcolor` expect the user to want the limits to be tight around the
49+
# pixels shown in the plot. If this behavior is not desired, you need to set
50+
# `~.Axes.use_sticky_edges` to `False`. Consider the following example:
51+
52+
y, x = np.mgrid[:5, 1:6]
53+
poly_coords = [
54+
(0.25, 2.75), (3.25, 2.75),
55+
(2.25, 0.75), (0.25, 0.75)
56+
]
57+
fig, (ax1, ax2) = plt.subplots(ncols=2)
58+
59+
# Here we set the stickiness of the axes object...
60+
# ax1 we'll leave as the default, which uses sticky edges
61+
# and we'll turn off stickiness for ax2
62+
ax2.use_sticky_edges = False
63+
64+
for ax, status in zip((ax1, ax2), ('Is', 'Is Not')):
65+
cells = ax.pcolor(x, y, x+y, cmap='inferno') # sticky
66+
ax.add_patch(
67+
plt.Polygon(poly_coords, color='forestgreen', alpha=0.5)
68+
) # not sticky
69+
ax.margins(x=0.1, y=0.05)
70+
ax.set_aspect('equal')
71+
ax.set_title('{} Sticky'.format(status))
72+
73+
plt.show()
74+
75+
76+
#############################################################################
77+
#
78+
# ------------
79+
#
80+
# References
81+
# """"""""""
82+
#
83+
# The use of the following functions, methods is shown
84+
# in this example:
85+
86+
import matplotlib
87+
matplotlib.axes.Axes.margins
88+
matplotlib.pyplot.margins
89+
matplotlib.axes.Axes.use_sticky_edges
90+
matplotlib.axes.Axes.pcolor
91+
matplotlib.pyplot.pcolor
92+
matplotlib.pyplot.Polygon

‎lib/matplotlib/axes/_base.py‎

Lines changed: 43 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2227,41 +2227,56 @@ def margins(self, *margins, x=None, y=None, tight=True):
22272227
"""
22282228
Set or retrieve autoscaling margins.
22292229
2230-
signatures::
2231-
2232-
margins()
2233-
2234-
returns xmargin, ymargin
2235-
2236-
::
2237-
2238-
margins(margin)
2239-
2240-
margins(xmargin, ymargin)
2241-
2242-
margins(x=xmargin, y=ymargin)
2243-
2244-
margins(..., tight=False)
2245-
2246-
All three forms above set the xmargin and ymargin parameters.
2247-
All keyword parameters are optional. A single positional argument
2248-
specifies both xmargin and ymargin. The padding added to the end of
2249-
each interval is *margin* times the data interval. The *margin* must
2250-
be a float in the range [0, 1]. Passing both positional and keyword
2251-
arguments for xmargin and/or ymargin is invalid.
2252-
2253-
The *tight* parameter is passed to :meth:`autoscale_view`
2254-
, which is executed after a margin is changed; the default here is
2255-
*True*, on the assumption that when margins are specified, no
2256-
additional padding to match tick marks is usually desired. Setting
2257-
*tight* to *None* will preserve the previous setting.
2230+
The padding added to each limit of the axes is the *margin*
2231+
times the data interval. All input parameters must be floats
2232+
within the range [0, 1]. Passing both positional and keyword
2233+
arguments is invalid and will raise a TypeError. If no
2234+
arguments (positional or otherwise) are provided, the current
2235+
margins will remain in place and simply be returned.
22582236
22592237
Specifying any margin changes only the autoscaling; for example,
22602238
if *xmargin* is not None, then *xmargin* times the X data
22612239
interval will be added to each end of that interval before
22622240
it is used in autoscaling.
22632241
2242+
Parameters
2243+
----------
2244+
args : float, optional
2245+
If a single positional argument is provided, it specifies
2246+
both margins of the x-axis and y-axis limits. If two
2247+
positional arguments are provided, they will be interpreted
2248+
as *xmargin*, *ymargin*. If setting the margin on a single
2249+
axis is desired, use the keyword arguments described below.
2250+
2251+
x, y : float, optional
2252+
Specific margin values for the x-axis and y-axis,
2253+
respectively. These cannot be used with positional
2254+
arguments, but can be used individually to alter on e.g.,
2255+
only the y-axis.
2256+
2257+
tight : bool, default is True
2258+
The *tight* parameter is passed to :meth:`autoscale_view`,
2259+
which is executed after a margin is changed; the default
2260+
here is *True*, on the assumption that when margins are
2261+
specified, no additional padding to match tick marks is
2262+
usually desired. Set *tight* to *None* will preserve
2263+
the previous setting.
2264+
2265+
2266+
Returns
2267+
-------
2268+
xmargin, ymargin : float
2269+
2270+
Notes
2271+
-----
2272+
If a previously used Axes method such as :meth:`pcolor` has set
2273+
:attr:`use_sticky_edges` to `True`, only the limits not set by
2274+
the "sticky artists" will be modified. To force all of the
2275+
margins to be set, set :attr:`use_sticky_edges` to `False`
2276+
before calling :meth:`margins`.
2277+
22642278
"""
2279+
22652280
if margins and x is not None and y is not None:
22662281
raise TypeError('Cannot pass both positional and keyword '
22672282
'arguments for x and/or y.')

0 commit comments

Comments
 (0)