Merge pull request matplotlib#21547 from doctronic/DTTOOL-13

ENH: Custom cap widths in box and whisker plots in bxp() and boxplot()

Author: tacaswell

doc/users/next_whats_new/custom_cap_widths.rst

@@ -0,0 +1,16 @@
+Custom cap widths in box and whisker plots in bxp() and boxplot()
+-----------------------------------------------------------------
+
+New bxp() and boxplot() parameter capwidths allows to control the
+widths of the caps in box and whisker plots.
+
+.. plot::
+    :include-source: true
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+    x = np.linspace(-7, 7, 140)
+    x = np.hstack([-25, x, 25])
+    fig, ax = plt.subplots()
+    ax.boxplot([x, x], notch=1, capwidths=[0.01, 0.2])
+    plt.show()

examples/statistics/boxplot_demo.py

@@ -231,6 +231,18 @@ def fake_bootstrapper(n):
 plt.setp(bp['fliers'], markersize=3.0)
 plt.show()
 
+
+###############################################################################
+# Here we customize the widths of the caps .
+
+x = np.linspace(-7, 7, 140)
+x = np.hstack([-25, x, 25])
+fig, ax = plt.subplots()
+
+ax.boxplot([x, x], notch=1, capwidths=[0.01, 0.2])
+
+plt.show()
+
 #############################################################################
 #
 # .. admonition:: References

lib/matplotlib/axes/_axes.py

@@ -3525,7 +3525,8 @@ 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_ticks=True, autorange=False, zorder=None):
+                manage_ticks=True, autorange=False, zorder=None,
+                capwidths=None):
         """
         Draw a box and whisker plot.
 
@@ -3692,6 +3693,8 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
             Show the arithmetic means.
         capprops : dict, default: None
             The style of the caps.
+        capwidths : float or array, default: None
+            The widths of the caps.
         boxprops : dict, default: None
             The style of the box.
         whiskerprops : dict, default: None
@@ -3820,15 +3823,17 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
                            medianprops=medianprops, meanprops=meanprops,
                            meanline=meanline, showfliers=showfliers,
                            capprops=capprops, whiskerprops=whiskerprops,
-                           manage_ticks=manage_ticks, zorder=zorder)
+                           manage_ticks=manage_ticks, zorder=zorder,
+                           capwidths=capwidths)
         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_ticks=True, zorder=None):
+            meanline=False, manage_ticks=True, zorder=None,
+            capwidths=None):
         """
         Drawing function for box and whisker plots.
 
@@ -3866,6 +3871,10 @@ def bxp(self, bxpstats, positions=None, widths=None, vert=True,
           The widths of the boxes.  The default is
           ``clip(0.15*(distance between extreme positions), 0.15, 0.5)``.
 
+        capwidths : float or array-like, default: None
+          Either a scalar or a vector and sets the width of each cap.
+          The default is ``0.5*(with of the box)``, see *widths*.
+
         vert : bool, default: True
           If `True` (default), makes the boxes vertical.
           If `False`, makes horizontal boxes.
@@ -3998,7 +4007,16 @@ def do_patch(xs, ys, **kwargs):
         elif len(widths) != N:
             raise ValueError(datashape_message.format("widths"))
 
-        for pos, width, stats in zip(positions, widths, bxpstats):
+        # capwidth
+        if capwidths is None:
+            capwidths = 0.5 * np.array(widths)
+        elif np.isscalar(capwidths):
+            capwidths = [capwidths] * N
+        elif len(capwidths) != N:
+            raise ValueError(datashape_message.format("capwidths"))
+
+        for pos, width, stats, capwidth in zip(positions, widths, bxpstats,
+                                               capwidths):
             # try to find a new label
             datalabels.append(stats.get('label', pos))
 
@@ -4007,8 +4025,8 @@ def do_patch(xs, ys, **kwargs):
             whislo_y = [stats['q1'], stats['whislo']]
             whishi_y = [stats['q3'], stats['whishi']]
             # cap coords
-            cap_left = pos - width * 0.25
-            cap_right = pos + width * 0.25
+            cap_left = pos - capwidth * 0.5
+            cap_right = pos + capwidth * 0.5
             cap_x = [cap_left, cap_right]
             cap_lo = np.full(2, stats['whislo'])
             cap_hi = np.full(2, stats['whishi'])
@@ -4018,14 +4036,16 @@ def do_patch(xs, ys, **kwargs):
             med_y = [stats['med'], stats['med']]
             # notched boxes
             if shownotches:
-                box_x = [box_left, box_right, box_right, cap_right, box_right,
-                         box_right, box_left, box_left, cap_left, box_left,
-                         box_left]
+                notch_left = pos - width * 0.25
+                notch_right = pos + width * 0.25
+                box_x = [box_left, box_right, box_right, notch_right,
+                         box_right, box_right, box_left, box_left, notch_left,
+                         box_left, box_left]
                 box_y = [stats['q1'], stats['q1'], stats['cilo'],
                          stats['med'], stats['cihi'], stats['q3'],
                          stats['q3'], stats['cihi'], stats['med'],
                          stats['cilo'], stats['q1']]
-                med_x = cap_x
+                med_x = [notch_left, notch_right]
             # plain boxes
             else:
                 box_x = [box_left, box_right, box_right, box_left, box_left]

lib/matplotlib/pyplot.py

@@ -2431,7 +2431,7 @@ def boxplot(
         showfliers=None, boxprops=None, labels=None, flierprops=None,
         medianprops=None, meanprops=None, capprops=None,
         whiskerprops=None, manage_ticks=True, autorange=False,
-        zorder=None, *, data=None):
+        zorder=None, capwidths=None, *, data=None):
     return gca().boxplot(
         x, notch=notch, sym=sym, vert=vert, whis=whis,
         positions=positions, widths=widths, patch_artist=patch_artist,
@@ -2442,7 +2442,7 @@ def boxplot(
         flierprops=flierprops, medianprops=medianprops,
         meanprops=meanprops, capprops=capprops,
         whiskerprops=whiskerprops, manage_ticks=manage_ticks,
-        autorange=autorange, zorder=zorder,
+        autorange=autorange, zorder=zorder, capwidths=capwidths,
         **({"data": data} if data is not None else {}))
 
 

lib/matplotlib/tests/baseline_images/test_axes/boxplot_custom_capwidths.png

@@ -1683,6 +1683,23 @@ def test_boxplot_dates_pandas(pd):
     plt.boxplot(data, positions=years)
 
 
+def test_boxplot_capwidths():
+    data = np.random.rand(5, 3)
+    fig, axs = plt.subplots(9)
+
+    axs[0].boxplot(data, capwidths=[0.3, 0.2, 0.1], widths=[0.1, 0.2, 0.3])
+    axs[1].boxplot(data, capwidths=[0.3, 0.2, 0.1], widths=0.2)
+    axs[2].boxplot(data, capwidths=[0.3, 0.2, 0.1])
+
+    axs[3].boxplot(data, capwidths=0.5, widths=[0.1, 0.2, 0.3])
+    axs[4].boxplot(data, capwidths=0.5, widths=0.2)
+    axs[5].boxplot(data, capwidths=0.5)
+
+    axs[6].boxplot(data, widths=[0.1, 0.2, 0.3])
+    axs[7].boxplot(data, widths=0.2)
+    axs[8].boxplot(data)
+
+
 def test_pcolor_regression(pd):
     from pandas.plotting import (
         register_matplotlib_converters,
@@ -2860,6 +2877,25 @@ def test_bxp_bad_positions():
         _bxp_test_helper(bxp_kwargs=dict(positions=[2, 3]))
 
 
+@image_comparison(['bxp_custom_capwidths.png'],
+                  savefig_kwarg={'dpi': 40},
+                  style='default')
+def test_bxp_custom_capwidths():
+    _bxp_test_helper(bxp_kwargs=dict(capwidths=[0.0, 0.1, 0.5, 1.0]))
+
+
+@image_comparison(['bxp_custom_capwidth.png'],
+                  savefig_kwarg={'dpi': 40},
+                  style='default')
+def test_bxp_custom_capwidth():
+    _bxp_test_helper(bxp_kwargs=dict(capwidths=0.6))
+
+
+def test_bxp_bad_capwidths():
+    with pytest.raises(ValueError):
+        _bxp_test_helper(bxp_kwargs=dict(capwidths=[1]))
+
+
 @image_comparison(['boxplot', 'boxplot'], tol=1.28, style='default')
 def test_boxplot():
     # Randomness used for bootstrapping.
@@ -2879,6 +2915,17 @@ def test_boxplot():
     ax.set_ylim((-30, 30))
 
 
+@image_comparison(['boxplot_custom_capwidths.png'],
+                  savefig_kwarg={'dpi': 40}, style='default')
+def test_boxplot_custom_capwidths():
+
+    x = np.linspace(-7, 7, 140)
+    x = np.hstack([-25, x, 25])
+    fig, ax = plt.subplots()
+
+    ax.boxplot([x, x], notch=1, capwidths=[0.01, 0.2])
+
+
 @image_comparison(['boxplot_sym2.png'], remove_text=True, style='default')
 def test_boxplot_sym2():
     # Randomness used for bootstrapping.