matplotlib · tacaswell · Jan 24, 2014 · Nov 29, 2013 · Dec 2, 2013 · Dec 3, 2013
diff --git a/CHANGELOG b/CHANGELOG
@@ -2,6 +2,11 @@
            argument. A 30x30 grid is now used for both density=1 and
            density=(1, 1).
 
+2013-12-03 Added a pure boxplot-drawing method that allow a more complete
+           customization of boxplots. It takes a list of dicts contains stats.
+           Also created a function (`cbook.boxplot_stats`) that generates the
+           stats needed.
+
 2013-11-28 Added qhull extension module to perform Delaunay triangulation more
            robustly than before.  It is used by tri.Triangulation (and hence
            all pyplot.tri* methods) and mlab.griddata.  Deprecated

diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst
@@ -32,6 +32,31 @@ Phil Elson rewrote of the documentation and userguide for both Legend and PathEf
 New plotting features
 ---------------------
 
+Fully customizable boxplots
+````````````````````````````
+Paul Hobson overhauled the :func:`~matplotlib.pyplot.boxplot` method such
+that it is now completely customizable in terms of the styles and positions
+of the individual artists. Under the hood, :func:`~matplotlib.pyplot.boxplot`
+relies on a new function (:func:`~matplotlib.cbook.boxplot_stats`), which
+accepts any data structure currently compatible with
+:func:`~matplotlib.pyplot.boxplot`, and returns a list of dictionaries
+containing the positions for each element of the boxplots. Then
+a second method, :func:`~matplotlib.Axes.bxp` is called to draw the boxplots
+based on the stats.
+
+The :func:~matplotlib.pyplot.boxplot function can be used as before to
+generate boxplots from data in one step. But now the user has the
+flexibility to generate the statistics independently, or to modify the
+output of :func:~matplotlib.cbook.boxplot_stats prior to plotting
+with :func:~matplotlib.Axes.bxp.
+
+Lastly, each artist (e.g., the box, outliers, cap, notches) can now be
+toggled on or off and their styles can be passed in through individual
+kwargs. See the examples:
+:ref:`~examples/statistics/boxplot_demo.py` and
+:ref:`~examples/statistics/bxp_demo.py`
+
+
 Support for datetime axes in 2d plots
 `````````````````````````````````````
 Andrew Dawson added support for datetime axes to

diff --git a/examples/statistics/boxplot_demo.py b/examples/statistics/boxplot_demo.py
@@ -0,0 +1,77 @@
+"""
+Demo of the new boxplot functionality
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+# fake data
+np.random.seed(937)
+data = np.random.lognormal(size=(37, 4), mean=1.5, sigma=1.75)
+labels = list('ABCD')
+fs = 10 # fontsize
+
+# demonstrate how to toggle the display of different elements:
+fig, axes = plt.subplots(nrows=2, ncols=3, figsize=(6,6))
+axes[0, 0].boxplot(data, labels=labels)
+axes[0, 0].set_title('Default', fontsize=fs)
+
+axes[0, 1].boxplot(data, labels=labels, showmeans=True)
+axes[0, 1].set_title('showmeans=True', fontsize=fs)
+
+axes[0, 2].boxplot(data, labels=labels, showmeans=True, meanline=True)
+axes[0, 2].set_title('showmeans=True,\nmeanline=True', fontsize=fs)
+
+axes[1, 0].boxplot(data, labels=labels, showbox=False, showcaps=False)
+axes[1, 0].set_title('Tufte Style \n(showbox=False,\nshowcaps=False)', fontsize=fs)
+
+axes[1, 1].boxplot(data, labels=labels, notch=True, bootstrap=10000)
+axes[1, 1].set_title('notch=True,\nbootstrap=10000', fontsize=fs)
+
+axes[1, 2].boxplot(data, labels=labels, showfliers=False)
+axes[1, 2].set_title('showfliers=False', fontsize=fs)
+
+for ax in axes.flatten():
+    ax.set_yscale('log')
+    ax.set_yticklabels([])
+
+fig.subplots_adjust(hspace=0.4)
+plt.show()
+
+
+# demonstrate how to customize the display different elements:
+boxprops = dict(linestyle='--', linewidth=3, color='darkgoldenrod')
+flierprops = dict(marker='o', markerfacecolor='green', markersize=12,
+                  linestyle='none')
+medianprops = dict(linestyle='-.', linewidth=2.5, color='firebrick')
+meanpointprops = dict(marker='D', markeredgecolor='black',
+                      markerfacecolor='firebrick')
+meanlineprops = dict(linestyle='--', linewidth=2.5, color='purple')
+
+fig, axes = plt.subplots(nrows=2, ncols=3, figsize=(6,6))
+axes[0, 0].boxplot(data, boxprops=boxprops)
+axes[0, 0].set_title('Custom boxprops', fontsize=fs)
+
+axes[0, 1].boxplot(data, flierprops=flierprops, medianprops=medianprops)
+axes[0, 1].set_title('Custom medianprops\nand flierprops', fontsize=fs)
+
+axes[0, 2].boxplot(data, whis='range')
+axes[0, 2].set_title('whis="range"', fontsize=fs)
+
+axes[1, 0].boxplot(data, meanprops=meanpointprops, meanline=False,
+                   showmeans=True)
+axes[1, 0].set_title('Custom mean\nas point', fontsize=fs)
+
+axes[1, 1].boxplot(data, meanprops=meanlineprops, meanline=True, showmeans=True)
+axes[1, 1].set_title('Custom mean\nas line', fontsize=fs)
+
+axes[1, 2].boxplot(data, whis=[15, 85])
+axes[1, 2].set_title('whis=[15, 85]\n#percentiles', fontsize=fs)
+
+for ax in axes.flatten():
+    ax.set_yscale('log')
+    ax.set_yticklabels([])
+
+fig.suptitle("I never said they'd be pretty")
+fig.subplots_adjust(hspace=0.4)
+plt.show()
diff --git a/examples/statistics/bxp_demo.py b/examples/statistics/bxp_demo.py
@@ -0,0 +1,83 @@
+"""
+Demo of the new boxplot drawer function
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.cbook as cbook
+
+# fake data
+np.random.seed(937)
+data = np.random.lognormal(size=(37, 4), mean=1.5, sigma=1.75)
+labels = list('ABCD')
+
+# compute the boxplot stats
+stats = cbook.boxplot_stats(data, labels=labels, bootstrap=10000)
+# After we've computed the stats, we can go through and change anything.
+# Just to prove it, I'll set the median of each set to the median of all
+# the data, and double the means
+for n in range(len(stats)):
+    stats[n]['med'] = np.median(data)
+    stats[n]['mean'] *= 2
+
+print(stats[0].keys())
+fs = 10 # fontsize
+
+# demonstrate how to toggle the display of different elements:
+fig, axes = plt.subplots(nrows=2, ncols=3, figsize=(6,6))
+axes[0, 0].bxp(stats)
+axes[0, 0].set_title('Default', fontsize=fs)
+
+axes[0, 1].bxp(stats, showmeans=True)
+axes[0, 1].set_title('showmeans=True', fontsize=fs)
+
+axes[0, 2].bxp(stats, showmeans=True, meanline=True)
+axes[0, 2].set_title('showmeans=True,\nmeanline=True', fontsize=fs)
+
+axes[1, 0].bxp(stats, showbox=False, showcaps=False)
+axes[1, 0].set_title('Tufte Style\n(showbox=False,\nshowcaps=False)', fontsize=fs)
+
+axes[1, 1].bxp(stats, shownotches=True)
+axes[1, 1].set_title('notch=True', fontsize=fs)
+
+axes[1, 2].bxp(stats, showfliers=False)
+axes[1, 2].set_title('showfliers=False', fontsize=fs)
+
+for ax in axes.flatten():
+    ax.set_yscale('log')
+    ax.set_yticklabels([])
+
+fig.subplots_adjust(hspace=0.4)
+plt.show()
+
+
+# demonstrate how to customize the display different elements:
+boxprops = dict(linestyle='--', linewidth=3, color='darkgoldenrod')
+flierprops = dict(marker='o', markerfacecolor='green', markersize=12,
+                  linestyle='none')
+medianprops = dict(linestyle='-.', linewidth=2.5, color='firebrick')
+meanpointprops = dict(marker='D', markeredgecolor='black',
+                      markerfacecolor='firebrick')
+meanlineprops = dict(linestyle='--', linewidth=2.5, color='purple')
+
+fig, axes = plt.subplots(nrows=2, ncols=2, figsize=(6,6))
+axes[0, 0].bxp(stats, boxprops=boxprops)
+axes[0, 0].set_title('Custom boxprops', fontsize=fs)
+
+axes[0, 1].bxp(stats, flierprops=flierprops, medianprops=medianprops)
+axes[0, 1].set_title('Custom medianprops\nand flierprops', fontsize=fs)
+
+axes[1, 0].bxp(stats, meanprops=meanpointprops, meanline=False,
+                   showmeans=True)
+axes[1, 0].set_title('Custom mean\nas point', fontsize=fs)
+
+axes[1, 1].bxp(stats, meanprops=meanlineprops, meanline=True, showmeans=True)
+axes[1, 1].set_title('Custom mean\nas line', fontsize=fs)
+
+for ax in axes.flatten():
+    ax.set_yscale('log')
+    ax.set_yticklabels([])
+
+fig.suptitle("I never said they'd be pretty")
+fig.subplots_adjust(hspace=0.4)
+plt.show()