matplotlib · pelson · Nov 23, 2015 · Nov 17, 2015 · Nov 17, 2015 · Nov 17, 2015
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -11,6 +11,15 @@ sources of the changes you are experiencing.
 For new features that were added to matplotlib, please see
 :ref:`whats-new`.
 
+Changes in 2.0.0
+================
+
+Color of Axes
+-------------
+
+The ``axisbg`` and ``axis_bgcolor`` properties on ``Axes`` have been
+deprecated in favor of ``facecolor``.
+
 Changes in 1.5.0
 ================
 

diff --git a/doc/users/plotting/colormaps/Lfunction.py b/doc/users/plotting/colormaps/Lfunction.py
@@ -49,10 +49,10 @@
 for i in range(red.shape[1]):
 
     # LHS: additive
-    ax1 = fig.add_subplot(nrows,2,i*2+1, axisbg=tuple(rgb_add[0,i,:]))
+    ax1 = fig.add_subplot(nrows,2,i*2+1, facecolor=tuple(rgb_add[0,i,:]))
 
     # RHS: multiplicative
-    ax2 = fig.add_subplot(nrows,2,i*2+2, axisbg=tuple(rgb_geometric[0,i,:]))
+    ax2 = fig.add_subplot(nrows,2,i*2+2, facecolor=tuple(rgb_geometric[0,i,:]))
 
     # ylabels
     if i!=0:
@@ -122,10 +122,10 @@
 for i in range(nrows):
 
     # LHS: additive
-    ax1 = fig.add_subplot(nrows,ncols,i*2+1, axisbg=tuple(rgb_add[0,i,:]))
+    ax1 = fig.add_subplot(nrows,ncols,i*2+1, facecolor=tuple(rgb_add[0,i,:]))
 
     # middle: multiplicative
-    ax2 = fig.add_subplot(nrows,ncols,i*2+2, axisbg=tuple(rgb_geometric[0,i,:]))
+    ax2 = fig.add_subplot(nrows,ncols,i*2+2, facecolor=tuple(rgb_geometric[0,i,:]))
 
     # ylabels
     if i!=0:

diff --git a/examples/pylab_examples/axes_demo.py b/examples/pylab_examples/axes_demo.py
@@ -16,14 +16,14 @@
 plt.title('Gaussian colored noise')
 
 # this is an inset axes over the main axes
-a = plt.axes([.65, .6, .2, .2], axisbg='y')
+a = plt.axes([.65, .6, .2, .2], facecolor='y')
 n, bins, patches = plt.hist(s, 400, normed=1)
 plt.title('Probability')
 plt.xticks([])
 plt.yticks([])
 
 # this is another inset axes over the main axes
-a = plt.axes([0.2, 0.6, .2, .2], axisbg='y')
+a = plt.axes([0.2, 0.6, .2, .2], facecolor='y')
 plt.plot(t[:len(r)], r)
 plt.title('Impulse response')
 plt.xlim(0, 0.2)

diff --git a/examples/pylab_examples/color_demo.py b/examples/pylab_examples/color_demo.py
@@ -16,8 +16,8 @@
 import matplotlib.pyplot as plt
 import numpy as np
 
-plt.subplot(111, axisbg='darkslategray')
-#subplot(111, axisbg='#ababab')
+plt.subplot(111, facecolor='darkslategray')
+#subplot(111, facecolor='#ababab')
 t = np.arange(0.0, 2.0, 0.01)
 s = np.sin(2*np.pi*t)
 plt.plot(t, s, 'y')

diff --git a/examples/pylab_examples/finance_work2.py b/examples/pylab_examples/finance_work2.py
@@ -99,10 +99,10 @@ def moving_average_convergence(x, nslow=26, nfast=12):
 fig = plt.figure(facecolor='white')
 axescolor = '#f6f6f6'  # the axes background color
 
-ax1 = fig.add_axes(rect1, axisbg=axescolor)  # left, bottom, width, height
-ax2 = fig.add_axes(rect2, axisbg=axescolor, sharex=ax1)
+ax1 = fig.add_axes(rect1, facecolor=axescolor)  # left, bottom, width, height
+ax2 = fig.add_axes(rect2, facecolor=axescolor, sharex=ax1)
 ax2t = ax2.twinx()
-ax3 = fig.add_axes(rect3, axisbg=axescolor, sharex=ax1)
+ax3 = fig.add_axes(rect3, facecolor=axescolor, sharex=ax1)
 
 
 # plot the relative strength indicator

diff --git a/examples/pylab_examples/fonts_demo.py b/examples/pylab_examples/fonts_demo.py
@@ -7,7 +7,7 @@
 from matplotlib.font_manager import FontProperties
 import matplotlib.pyplot as plt
 
-plt.subplot(111, axisbg='w')
+plt.subplot(111, facecolor='w')
 
 font0 = FontProperties()
 alignment = {'horizontalalignment': 'center', 'verticalalignment': 'baseline'}

diff --git a/examples/pylab_examples/fonts_demo_kw.py b/examples/pylab_examples/fonts_demo_kw.py
@@ -7,7 +7,7 @@
 import matplotlib.pyplot as plt
 import numpy as np
 
-plt.subplot(111, axisbg='w')
+plt.subplot(111, facecolor='w')
 alignment = {'horizontalalignment': 'center', 'verticalalignment': 'baseline'}
 
 # Show family options

diff --git a/examples/pylab_examples/image_origin.py b/examples/pylab_examples/image_origin.py
@@ -13,12 +13,12 @@
 interp = 'bilinear'
 #interp = 'nearest'
 lim = -2, 11, -2, 6
-plt.subplot(211, axisbg='g')
+plt.subplot(211, facecolor='g')
 plt.title('blue should be up')
 plt.imshow(x, origin='upper', interpolation=interp, cmap='jet')
 #plt.axis(lim)
 
-plt.subplot(212, axisbg='y')
+plt.subplot(212, facecolor='y')
 plt.title('blue should be down')
 plt.imshow(x, origin='lower', interpolation=interp, cmap='jet')
 #plt.axis(lim)

diff --git a/examples/pylab_examples/logo.py b/examples/pylab_examples/logo.py
@@ -15,7 +15,7 @@
 # 0.0005 is the sample interval
 t = 0.0005 * np.arange(len(x))
 plt.figure(1, figsize=(7, 1), dpi=100)
-ax = plt.subplot(111, axisbg='y')
+ax = plt.subplot(111, facecolor='y')
 plt.plot(t, x)
 plt.text(0.5, 0.5, 'matplotlib', color='r',
          fontsize=40, fontname=['Courier', 'DejaVu Sans Mono'],

diff --git a/examples/pylab_examples/mathtext_demo.py b/examples/pylab_examples/mathtext_demo.py
@@ -9,7 +9,7 @@
 fig = figure()
 fig.subplots_adjust(bottom=0.2)
 
-ax = fig.add_subplot(111, axisbg='y')
+ax = fig.add_subplot(111, facecolor='y')
 ax.plot([1, 2, 3], 'r')
 x = np.arange(0.0, 3.0, 0.1)
 

diff --git a/examples/pylab_examples/mathtext_examples.py b/examples/pylab_examples/mathtext_examples.py
@@ -61,7 +61,7 @@ def doall():
 
     # Creating figure and axis.
     plt.figure(figsize=(6, 7))
-    plt.axes([0.01, 0.01, 0.98, 0.90], axisbg="white", frameon=True)
+    plt.axes([0.01, 0.01, 0.98, 0.90], facecolor="white", frameon=True)
     plt.gca().set_xlim(0., 1.)
     plt.gca().set_ylim(0., 1.)
     plt.gca().set_title("Matplotlib's math rendering engine",

diff --git a/examples/pylab_examples/matplotlib_icon.py b/examples/pylab_examples/matplotlib_icon.py
@@ -7,7 +7,7 @@
 
 matplotlib.rc('grid', ls='-', lw=2, color='k')
 fig = plt.figure(figsize=(1, 1), dpi=72)
-plt.axes([0.025, 0.025, 0.95, 0.95], axisbg='#bfd1d4')
+plt.axes([0.025, 0.025, 0.95, 0.95], facecolor='#bfd1d4')
 
 t = np.arange(0, 2, 0.05)
 s = np.sin(2*np.pi*t)

diff --git a/examples/pylab_examples/polar_legend.py b/examples/pylab_examples/polar_legend.py
@@ -10,7 +10,7 @@
 
 # force square figure and square axes looks better for polar, IMO
 fig = figure(figsize=(8, 8))
-ax = fig.add_axes([0.1, 0.1, 0.8, 0.8], projection='polar', axisbg='#d5de9c')
+ax = fig.add_axes([0.1, 0.1, 0.8, 0.8], projection='polar', facecolor='#d5de9c')
 
 r = np.arange(0, 3.0, 0.01)
 theta = 2*np.pi*r

diff --git a/examples/pylab_examples/quadmesh_demo.py b/examples/pylab_examples/quadmesh_demo.py
@@ -27,12 +27,12 @@
 
 fig = figure()
 ax = fig.add_subplot(121)
-ax.set_axis_bgcolor("#bdb76b")
+ax.set_facecolor("#bdb76b")
 ax.pcolormesh(Qx, Qz, Z, shading='gouraud')
 ax.set_title('Without masked values')
 
 ax = fig.add_subplot(122)
-ax.set_axis_bgcolor("#bdb76b")
+ax.set_facecolor("#bdb76b")
 #  You can control the color of the masked region:
 #cmap = cm.jet
 #cmap.set_bad('r', 1.0)

diff --git a/examples/widgets/cursor.py b/examples/widgets/cursor.py
@@ -6,7 +6,7 @@
 
 
 fig = plt.figure(figsize=(8, 6))
-ax = fig.add_subplot(111, axisbg='#FFFFCC')
+ax = fig.add_subplot(111, facecolor='#FFFFCC')
 
 x, y = 4*(np.random.rand(2, 100) - .5)
 ax.plot(x, y, 'o')

diff --git a/examples/widgets/slider_demo.py b/examples/widgets/slider_demo.py
@@ -12,8 +12,8 @@
 plt.axis([0, 1, -10, 10])
 
 axcolor = 'lightgoldenrodyellow'
-axfreq = plt.axes([0.25, 0.1, 0.65, 0.03], axisbg=axcolor)
-axamp = plt.axes([0.25, 0.15, 0.65, 0.03], axisbg=axcolor)
+axfreq = plt.axes([0.25, 0.1, 0.65, 0.03], facecolor=axcolor)
+axamp = plt.axes([0.25, 0.15, 0.65, 0.03], facecolor=axcolor)
 
 sfreq = Slider(axfreq, 'Freq', 0.1, 30.0, valinit=f0)
 samp = Slider(axamp, 'Amp', 0.1, 10.0, valinit=a0)
@@ -36,7 +36,7 @@ def reset(event):
     samp.reset()
 button.on_clicked(reset)
 
-rax = plt.axes([0.025, 0.5, 0.15, 0.15], axisbg=axcolor)
+rax = plt.axes([0.025, 0.5, 0.15, 0.15], facecolor=axcolor)
 radio = RadioButtons(rax, ('red', 'blue', 'green'), active=0)
 
 

diff --git a/examples/widgets/span_selector.py b/examples/widgets/span_selector.py
@@ -8,7 +8,7 @@
 from matplotlib.widgets import SpanSelector
 
 fig = plt.figure(figsize=(8, 6))
-ax = fig.add_subplot(211, axisbg='#FFFFCC')
+ax = fig.add_subplot(211, facecolor='#FFFFCC')
 
 x = np.arange(0.0, 5.0, 0.01)
 y = np.sin(2*np.pi*x) + 0.5*np.random.randn(len(x))

diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -436,8 +436,6 @@ def __init__(self, fig, rect,
           *aspect*           [ 'auto' | 'equal' | aspect_ratio ]
           *autoscale_on*     [ *True* | *False* ] whether or not to
                              autoscale the *viewlim*
-          *axis_bgcolor*     any matplotlib color, see
-                             :func:`~matplotlib.pyplot.colors`
           *axisbelow*        draw the grids and ticks below the other
                              artists
           *cursor_props*     a (*float*, *color*) tuple
@@ -509,6 +507,9 @@ def __init__(self, fig, rect,
 
         if axisbg is None:
             axisbg = rcParams['axes.facecolor']
+        else:
+            cbook.warn_deprecated(
+                '2.0', name='axisbg', alternative='facecolor')
         self._axisbg = axisbg
         self._frameon = frameon
         self._axisbelow = rcParams['axes.axisbelow']
@@ -1065,6 +1066,14 @@ def clear(self):
         """clear the axes"""
         self.cla()
 
+    def get_facecolor(self):
+        return self.patch.get_facecolor()
+    get_fc = get_facecolor
+
+    def set_facecolor(self, color):
+        return self.patch.set_facecolor(color)
+    set_fc = set_facecolor
+
     def set_prop_cycle(self, *args, **kwargs):
         """
         Set the property cycle for any future plot commands on this Axes.
@@ -2620,18 +2629,22 @@ def set_axis_on(self):
         self.axison = True
         self.stale = True
 
+    @cbook.deprecated('2.0', alternative='get_facecolor')
     def get_axis_bgcolor(self):
         """Return the axis background color"""
         return self._axisbg
 
+    @cbook.deprecated('2.0', alternative='set_facecolor')
     def set_axis_bgcolor(self, color):
         """
         set the axes background color
 
         ACCEPTS: any matplotlib color - see
         :func:`~matplotlib.pyplot.colors`
         """
-
+        warnings.warn(
+            "set_axis_bgcolor is deprecated.  Use set_facecolor instead.",
+            cbook.mplDeprecation)
         self._axisbg = color
         self.patch.set_facecolor(color)
         self.stale = True

diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -851,7 +851,7 @@ def add_axes(self, *args, **kwargs):
 
             rect = l,b,w,h
             fig.add_axes(rect)
-            fig.add_axes(rect, frameon=False, axisbg='g')
+            fig.add_axes(rect, frameon=False, facecolor='g')
             fig.add_axes(rect, polar=True)
             fig.add_axes(rect, projection='polar')
             fig.add_axes(ax)
@@ -932,7 +932,7 @@ def add_subplot(self, *args, **kwargs):
             fig.add_subplot(1,1,1)
 
             # add subplot with red background
-            fig.add_subplot(212, axisbg='r')
+            fig.add_subplot(212, facecolor='r')
 
             # add a polar subplot
             fig.add_subplot(111, projection='polar')

diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -831,28 +831,28 @@ def axes(*args, **kwargs):
 
     - ``axes()`` by itself creates a default full ``subplot(111)`` window axis.
 
-    - ``axes(rect, axisbg='w')`` where *rect* = [left, bottom, width,
-      height] in normalized (0, 1) units.  *axisbg* is the background
+    - ``axes(rect, facecolor='w')`` where *rect* = [left, bottom, width,
+      height] in normalized (0, 1) units.  *facecolor* is the background
       color for the axis, default white.
 
     - ``axes(h)`` where *h* is an axes instance makes *h* the current
       axis.  An :class:`~matplotlib.axes.Axes` instance is returned.
 
-    =======   ==============   ==============================================
-    kwarg     Accepts          Description
-    =======   ==============   ==============================================
-    axisbg    color            the axes background color
-    frameon   [True|False]     display the frame?
-    sharex    otherax          current axes shares xaxis attribute
-                               with otherax
-    sharey    otherax          current axes shares yaxis attribute
-                               with otherax
-    polar     [True|False]     use a polar axes?
-    aspect    [str | num]      ['equal', 'auto'] or a number.  If a number
-                               the ratio of x-unit/y-unit in screen-space.
-                               Also see
-                               :meth:`~matplotlib.axes.Axes.set_aspect`.
-    =======   ==============   ==============================================
+    =========   ==============   ==============================================
+    kwarg       Accepts          Description
+    =========   ==============   ==============================================
+    facecolor   color            the axes background color
+    frameon     [True|False]     display the frame?
+    sharex      otherax          current axes shares xaxis attribute
+                                 with otherax
+    sharey      otherax          current axes shares yaxis attribute
+                                 with otherax
+    polar       [True|False]     use a polar axes?
+    aspect      [str | num]      ['equal', 'auto'] or a number.  If a number
+                                 the ratio of x-unit/y-unit in screen-space.
+                                 Also see
+                                 :meth:`~matplotlib.axes.Axes.set_aspect`.
+    =========   ==============   ==============================================
 
     Examples:
 
@@ -968,15 +968,15 @@ def subplot(*args, **kwargs):
           # first, the plot (and its axes) previously created, will be removed
           plt.subplot(211)
           plt.plot(range(12))
-          plt.subplot(212, axisbg='y') # creates 2nd subplot with yellow background
+          plt.subplot(212, facecolor='y') # creates 2nd subplot with yellow background
 
        If you do not want this behavior, use the
        :meth:`~matplotlib.figure.Figure.add_subplot` method or the
        :func:`~matplotlib.pyplot.axes` function instead.
 
     Keyword arguments:
 
-      *axisbg*:
+      *facecolor*:
         The background color of the subplot, which can be any valid
         color specifier.  See :mod:`matplotlib.colors` for more
         information.
@@ -1919,7 +1919,7 @@ def colors():
     The example below creates a subplot with a dark
     slate gray background::
 
-       subplot(111, axisbg=(0.1843, 0.3098, 0.3098))
+       subplot(111, facecolor=(0.1843, 0.3098, 0.3098))
 
     Here is an example that creates a pale turquoise title::
 

diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -14,6 +14,8 @@
 from numpy import ma
 from numpy import arange
 
+import warnings
+
 import matplotlib
 from matplotlib.testing.decorators import image_comparison, cleanup
 import matplotlib.pyplot as plt
@@ -4088,6 +4090,17 @@ def test_violin_point_mass():
     """Violin plot should handle point mass pdf gracefully."""
     plt.violinplot(np.array([0, 0]))
 
+
+@cleanup
+def test_axisbg_warning():
+    fig = plt.figure()
+    with warnings.catch_warnings(record=True) as w:
+        ax = matplotlib.axes.Axes(fig, [0, 0, 1, 1], axisbg='r')
+    assert len(w) == 1
+    assert (str(w[0].message).startswith(
+            ("The axisbg attribute was deprecated in version 2.0.")))
+
+
 if __name__ == '__main__':
     import nose
     import sys