matplotlib · choldgraf · Oct 19, 2017 · Oct 17, 2017 · Oct 19, 2017 · Oct 19, 2017
diff --git a/examples/api_examples/axes_margins.py b/examples/api_examples/axes_margins.py
@@ -0,0 +1,33 @@
+"""
+=====================================
+Zooming in and out using Axes.margins
+=====================================
+
+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
+import matplotlib.pyplot as plt
+
+
+def f(t):
+    return np.exp(-t) * np.cos(2*np.pi*t)
+
+
+t1 = np.arange(0.0, 3.0, 0.01)
+
+ax1 = plt.subplot(212)
+ax1.margins(0.05)           # Default margin is 0.05, value 0 means fit
+ax1.plot(t1, f(t1), 'k')
+
+ax2 = plt.subplot(221)
+ax2.margins(2, 2)           # Values >0.0 zoom out
+ax2.plot(t1, f(t1), 'r')
+ax2.set_title('Zoomed out')
+
+ax3 = plt.subplot(222)
+ax3.margins(x=0, y=-0.25)   # Values in (-0.5, 0.0) zooms in to center
+ax3.plot(t1, f(t1), 'g')
+ax3.set_title('Zoomed in')
+
+plt.show()
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -2075,10 +2075,10 @@ def set_xmargin(self, m):
         *m* times the data interval will be added to each
         end of that interval before it is used in autoscaling.
 
-        accepts: float in range 0 to 1
+        accepts: float greater than -0.5
         """
-        if m < 0 or m > 1:
-            raise ValueError("margin must be in range 0 to 1")
+        if m <= -0.5:
+            raise ValueError("margin must be greater than -0.5")
         self._xmargin = m
         self.stale = True
 
@@ -2089,10 +2089,10 @@ def set_ymargin(self, m):
         *m* times the data interval will be added to each
         end of that interval before it is used in autoscaling.
 
-        accepts: float in range 0 to 1
+        accepts: float greater than -0.5
         """
-        if m < 0 or m > 1:
-            raise ValueError("margin must be in range 0 to 1")
+        if m <= -0.5:
+            raise ValueError("margin must be greater than -0.5")
         self._ymargin = m
         self.stale = True
 

diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -4585,21 +4585,37 @@ def test_o_marker_path_snap():
 def test_margins():
     # test all ways margins can be called
     data = [1, 10]
+    xmin = 0.0
+    xmax = len(data) - 1.0
+    ymin = min(data)
+    ymax = max(data)
 
     fig1, ax1 = plt.subplots(1, 1)
     ax1.plot(data)
     ax1.margins(1)
     assert ax1.margins() == (1, 1)
+    assert ax1.get_xlim() == (xmin - (xmax - xmin) * 1,
+                              xmax + (xmax - xmin) * 1)
+    assert ax1.get_ylim() == (ymin - (ymax - ymin) * 1,
+                              ymax + (ymax - ymin) * 1)
 
     fig2, ax2 = plt.subplots(1, 1)
     ax2.plot(data)
-    ax2.margins(1, 0.5)
-    assert ax2.margins() == (1, 0.5)
+    ax2.margins(0.5, 2)
+    assert ax2.margins() == (0.5, 2)
+    assert ax2.get_xlim() == (xmin - (xmax - xmin) * 0.5,
+                              xmax + (xmax - xmin) * 0.5)
+    assert ax2.get_ylim() == (ymin - (ymax - ymin) * 2,
+                              ymax + (ymax - ymin) * 2)
 
     fig3, ax3 = plt.subplots(1, 1)
     ax3.plot(data)
-    ax3.margins(x=1, y=0.5)
-    assert ax3.margins() == (1, 0.5)
+    ax3.margins(x=-0.2, y=0.5)
+    assert ax3.margins() == (-0.2, 0.5)
+    assert ax3.get_xlim() == (xmin - (xmax - xmin) * -0.2,
+                              xmax + (xmax - xmin) * -0.2)
+    assert ax3.get_ylim() == (ymin - (ymax - ymin) * 0.5,
+                              ymax + (ymax - ymin) * 0.5)
 
 
 def test_length_one_hist():