8000 DOC: Add a plot to margins() to visualize the effect · timhoffm/matplotlib@8ea86fe · GitHub
[go: up one dir, main page]
Skip to content

Commit 8ea86fe

Browse files
timhoffmtimhoffm
committed
DOC: Add a plot to margins() to visualize the effect
1 parent 36af98e commit 8ea86fe

File tree

2 files changed

+60
-39
lines changed

2 files changed

+60
-39
lines changed

‎doc/_embedded_plots/axes_margins.py

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import numpy as np
2+
import matplotlib.pyplot as plt
3+
4+
fig, ax = plt.subplots(figsize=(6.5, 4))
5+
x = np.linspace(0, 1, 33)
6+
y = -np.sin(x * 2*np.pi)
7+
ax.plot(x, y, 'o')
8+
ax.margins(0.5, 0.2)
9+
ax.set_title("margins(x=0.5, y=0.2)")
10+
11+
# fix the Axes limits so that the following helper drawings
12+
# cannot change them further.
13+
ax.set(xlim=ax.get_xlim(), ylim=ax.get_ylim())
14+
15+
16+
def arrow(p1, p2, **props):
17+
ax.annotate("", p1, p2,
18+
arrowprops=dict(arrowstyle="<->", shrinkA=0, shrinkB=0, **props))
19+
20+
21+
axmin, axmax = ax.get_xlim()
22+
aymin, aymax = ax.get_ylim()
23+
xmin, xmax = x.min(), x.max()
24+
ymin, ymax = y.min(), y.max()
25+
26+
y0 = -0.8
27+
ax.axvspan(axmin, xmin, color=("orange", 0.1))
28+
ax.axvspan(xmax, axmax, color=("orange", 0.1))
29+
arrow((xmin, y0), (xmax, y0), color="sienna")
30+
arrow((xmax, y0), (axmax, y0), color="orange")
31+
ax.text((xmax + axmax)/2, y0+0.05, "x margin\n* x data range",
32+
ha="center", va="bottom", color="orange")
33+
ax.text(0.55, y0+0.1, "x data range", va="bottom", color="sienna")
34+
35+
x0 = 0.1
36+
ax.axhspan(aymin, ymin, color=("tab:green", 0.1))
37+
ax.axhspan(ymax, aymax, color=("tab:green", 0.1))
38+
arrow((x0, ymin), (x0, ymax), color="darkgreen")
39+
arrow((x0, ymax), (x0, aymax), color="tab:green")
40+
ax.text(x0, (ymax + aymax) / 2, " y margin * y data range",
41+
va="center", color="tab:green")
42+
ax.text(x0, 0.5, " y data range", color="darkgreen")

‎lib/matplotlib/axes/_base.py

Lines changed: 18 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -2736,47 +2736,22 @@ def set_ymargin(self, m):
27362736

27372737
def margins(self, *margins, x=None, y=None, tight=True):
27382738
"""
2739-
Set or retrieve autoscaling margins.
2739+
Set or retrieve margins around the data for autoscaling axis limits.
27402740
2741-
The padding added to each limit of the Axes is the *margin*
2742-
times the data interval. All input parameters must be floats
2743-
greater than -0.5. Passing both positional and keyword
2744-
arguments is invalid and will raise a TypeError. If no
2745-
arguments (positional or otherwise) are provided, the current
2746-
margins will remain unchanged and simply be returned.
2747-
2748-
.. plot::
2749-
2750-
import numpy as np
2751-
import matplotlib.pyplot as plt
2752-
2753-
x, y = np.meshgrid(np.linspace(0, 1, 10), np.linspace(0, 1, 10))
2754-
fig, ax = plt.subplots()
2755-
ax.plot(x, y, 'o', color='lightblue')
2756-
ax.margins(1.5, 0.5)
2757-
ax.set_title("margins(x=1.5, y=0.5)")
2741+
This allows to configure the padding around the data without having to
2742+
set explicit limits using `~.Axes.set_xlim` / `~.Axes.set_ylim`.
27582743
2759-
def arrow(p1, p2, **props):
2760-
ax.annotate("", p1, p2,
2761-
arrowprops=dict(arrowstyle="<->", shrinkA=0, shrinkB=0, **props))
2744+
Autoscaling determines the axis limits by adding *margin* times the
2745+
data interval as padding around the data. See the following illustration:
27622746
2763-
arrow((-1.5, 0), (0, 0), color="orange")
2764-
arrow((0, 0), (1, 0), color="sienna")
2765-
8000 arrow((1, 0), (2.5, 0), color="orange")
2766-
ax.text(-0.75, -0.1, "x margin * x data range", ha="center",
2767-
color="orange")
2768-
ax.text(0.5, -0.1, "x data range", ha="center", color="sienna")
2747+
.. plot:: _embedded_plots/axes_margins.py
27692748
2770-
arrow((1, -0.5), (1, 0), color="tab:green")
2771-
arrow((1, 0), (1, 1), color="darkgreen")
2772-
arrow((1, 1), (1, 1.5), color="tab:green")
2773-
ax.text(1.1, 1.25, "y margin * y data range", color="tab:green")
2774-
ax.text(1.1, 0.5, "y data range", color="darkgreen")
2749+
All input parameters must be floats greater than -0.5. Passing both
2750+
positional and keyword arguments is invalid and will raise a TypeError.
2751+
If no arguments (positional or otherwise) are provided, the current
2752+
margins will remain unchanged and simply be returned.
27752753
2776-
Specifying any margin changes only the autoscaling; for example,
2777-
if *xmargin* is not None, then *xmargin* times the X data
2778-
interval will be added to each end of that interval before
2779-
it is used in autoscaling.
2754+
The default margins are :rc:`axes.xmargin` and :rc:`axes.ymargin`.
27802755
27812756
Parameters
27822757
----------
@@ -2808,10 +2783,14 @@ def arrow(p1, p2, **props):
28082783
Notes
28092784
-----
28102785
If a previously used Axes method such as :meth:`pcolor` has set
2811-
:attr:`use_sticky_edges` to `True`, only the limits not set by
2812-
the "sticky artists" will be modified. To force all of the
2813-
margins to be set, set :attr:`use_sticky_edges` to `False`
2786+
`~.Axes.use_sticky_edges` to `True`, only the limits not set by
2787+
the "sticky artists" will be modified. To force all
2788+
margins to be set, set `~.Axes.use_sticky_edges` to `False`
28142789
before calling :meth:`margins`.
2790+
2791+
See Also
2792+
--------
2793+
.Axes.set_xmargin, .Axes.set_ymargin
28152794
"""
28162795

28172796
if margins and (x is not None or y is not None):

0 commit comments

Comments
 (0)
0