Merge pull request matplotlib#7178 from bcongdon/boxplot-zorder

Boxplot zorder kwarg

Author: NelleV

doc/users/whats_new/boxplot_zorder_kwarg.rst

@@ -0,0 +1,11 @@
+Boxplot Zorder Keyword Argument
+-------------------------------
+
+The ``zorder`` parameter now exists for :func:`boxplot`. This allows the zorder
+of a boxplot to be set in the plotting function call.
+
+Example
+```````
+::
+
+    boxplot(np.arange(10), zorder=10)

lib/matplotlib/axes/_axes.py

@@ -3100,7 +3100,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
                 showbox=None, showfliers=None, boxprops=None,
                 labels=None, flierprops=None, medianprops=None,
                 meanprops=None, capprops=None, whiskerprops=None,
-                manage_xticks=True, autorange=False):
+                manage_xticks=True, autorange=False, zorder=None):
         """
         Make a box and whisker plot.
 
@@ -3113,7 +3113,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
                   showbox=True, showfliers=True, boxprops=None,
                   labels=None, flierprops=None, medianprops=None,
                   meanprops=None, capprops=None, whiskerprops=None,
-                  manage_xticks=True, autorange=False):
+                  manage_xticks=True, autorange=False, zorder=None):
 
         Make a box and whisker plot for each column of ``x`` or each
         vector in sequence ``x``.  The box extends from the lower to
@@ -3225,6 +3225,9 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
             ``shownotches`` is also True. Otherwise, means will be shown
             as points.
 
+        zorder : scalar, optional (None)
+            Sets the zorder of the boxplot.
+
         Other Parameters
         ----------------
         The following boolean options toggle the drawing of individual
@@ -3395,15 +3398,15 @@ def _update_dict(dictionary, rc_name, properties):
                            medianprops=medianprops, meanprops=meanprops,
                            meanline=meanline, showfliers=showfliers,
                            capprops=capprops, whiskerprops=whiskerprops,
-                           manage_xticks=manage_xticks)
+                           manage_xticks=manage_xticks, zorder=zorder)
         return artists
 
     def bxp(self, bxpstats, positions=None, widths=None, vert=True,
             patch_artist=False, shownotches=False, showmeans=False,
             showcaps=True, showbox=True, showfliers=True,
             boxprops=None, whiskerprops=None, flierprops=None,
             medianprops=None, capprops=None, meanprops=None,
-            meanline=False, manage_xticks=True):
+            meanline=False, manage_xticks=True, zorder=None):
         """
         Drawing function for box and whisker plots.
 
@@ -3414,7 +3417,7 @@ def bxp(self, bxpstats, positions=None, widths=None, vert=True,
               showcaps=True, showbox=True, showfliers=True,
               boxprops=None, whiskerprops=None, flierprops=None,
               medianprops=None, capprops=None, meanprops=None,
-              meanline=False, manage_xticks=True):
+              meanline=False, manage_xticks=True, zorder=None):
 
         Make a box and whisker plot for each column of *x* or each
         vector in sequence *x*.  The box extends from the lower to
@@ -3518,6 +3521,9 @@ def bxp(self, bxpstats, positions=None, widths=None, vert=True,
         manage_xticks : bool, default = True
           If the function should adjust the xlim and xtick locations.
 
+        zorder : scalar,  default = None
+          The zorder of the resulting boxplot
+
         Returns
         -------
         result : dict
@@ -3560,7 +3566,10 @@ def bxp(self, bxpstats, positions=None, widths=None, vert=True,
         # empty list of xticklabels
         datalabels = []
 
-        zorder = mlines.Line2D.zorder
+        # Use default zorder if none specified
+        if zorder is None:
+            zorder = mlines.Line2D.zorder
+
         zdelta = 0.1
         # box properties
         if patch_artist:

lib/matplotlib/tests/test_axes.py

@@ -2012,6 +2012,14 @@ def test_boxplot_bad_ci_1():
                   conf_intervals=[[1, 2]])
 
 
+@cleanup
+def test_boxplot_zorder():
+    x = np.arange(10)
+    fix, ax = plt.subplots()
+    assert ax.boxplot(x)['boxes'][0].get_zorder() == 2
+    assert ax.boxplot(x, zorder=10)['boxes'][0].get_zorder() == 10
+
+
 @cleanup
 def test_boxplot_bad_ci_2():
     x = np.linspace(-7, 7, 140)