API: Add return_type kwarg to boxplot

update docs

API: Let 'by' and groupby follow return_type

Write all the docs

Author: Tom Augspurger

doc/source/groupby.rst

@@ -909,6 +909,37 @@ To see the order in which each row appears within its group, use the
 
    df.groupby('A').cumcount(ascending=False)  # kwarg only
 
+Plotting
+~~~~~~~~
+
+Groupby also works with some plotting methods.  For example, suppose we
+suspect that some features in a DataFrame my differ by group, in this case,
+the values in column 1 where the group is "B" are 3 higher on average.
+
+.. ipython:: python
+
+   np.random.seed(1234)
+   df = DataFrame(np.random.randn(50, 2))
+   df['g'] = np.random.choice(['A', 'B'], size=50)
+   df.loc[df['g'] == 'B', 1] += 3
+
+We can easily visualize this with a boxplot:
+
+..ipython:: python
+
+   @savefig groupby_boxplot.png
+   bp = df.groupby('g').boxplot()
+
+The result of calling ``boxplot`` is a dictionary whose keys are the values
+of our grouping column ``g`` ("A" and "B"). The values of the resulting dictionary
+can be controlled by the ``return_type`` keyword of ``boxplot``.
+See the :ref:`visualization documentation<visualization.box>` for more.
+
+.. warning::
+
+  For historical reasons, ``df.groupby("g").boxplot()`` is not equivalent
+  to ``df.boxplot(by="g")``. See :ref:`here<visualization.box.return>`.
+
 Examples
 --------
 

doc/source/release.rst

@@ -208,6 +208,9 @@ API Changes
   returns a different Index (:issue:`7088`). Previously the index was unintentionally sorted.
 - arithmetic operations with **only** ``bool`` dtypes now raise an error
   (:issue:`7011`, :issue:`6762`, :issue:`7015`)
+- :meth:`DataFrame.boxplot` has a new keyword argument, `return_type`. It accepts ``'dict'``,
+  ``'axes'``, or ``'both'``, in which case a namedtuple with the matplotlib
+  axes and a dict of matplotlib Lines is returned.
 
 Deprecations
 ~~~~~~~~~~~~
@@ -258,6 +261,10 @@ Deprecations
   Use the `percentiles` keyword instead, which takes a list of percentiles to display. The
   default output is unchanged.
 
+- The default return type of :func:`boxplot` will change from a dict to a matpltolib Axes
+  in a future release. You can use the future behavior now by passing ``return_type='dict'``
+  to boxplot.
+
 Prior Version Deprecations/Changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/source/v0.14.0.txt

@@ -212,6 +212,10 @@ API changes
      # this now raises for arith ops like ``+``, ``*``, etc.
      NotImplementedError: operator '*' not implemented for bool dtypes
 
+- :meth:`DataFrame.boxplot` has a new keyword argument, `return_type`. It accepts ``'dict'``,
+  ``'axes'``, or ``'both'``, in which case a namedtuple with the matplotlib
+  axes and a dict of matplotlib Lines is returned.
+
 
 .. _whatsnew_0140.display:
 
@@ -574,6 +578,10 @@ Deprecations
   Use the `percentiles` keyword instead, which takes a list of percentiles to display. The
   default output is unchanged.
 
+- The default return type of :func:`boxplot` will change from a dict to a matpltolib Axes
+  in a future release. You can use the future behavior now by passing ``return_type='dict'``
+  to boxplot.
+
 .. _whatsnew_0140.enhancements:
 
 Enhancements

doc/source/visualization.rst

@@ -304,6 +304,42 @@ columns:
 
     plt.close('all')
 
+.. _visualization.box.return:
+
+The return type of ``boxplot`` depends on two keyword arguments: ``by`` and ``return_type``.
+When ``by`` is ``None``:
+
+* if ``return_type`` is ``'dict'``, a dictionary containing the :class:`matplotlib Lines <matplotlib.lines.Line2D>` is returned. The keys are "boxes", "caps", "fliers", "medians", and "whiskers".
+   This is the deafult.
+* if ``return_type`` is ``'axes'``, a :class:`matplotlib Axes <matplotlib.axes.Axes>` containing the boxplot is returned.
+* if ``return_type`` is ``'both'`` a namedtuple containging the :class:`matplotlib Axes <matplotlib.axes.Axes>`
+   and :class:`matplotlib Lines <matplotlib.lines.Line2D>` is returned
+
+When ``by`` is some column of the DataFrame, a dict of ``return_type`` is returned, where
+the keys are the columns of the DataFrame. The plot has a facet for each column of
+the DataFrame, with a separate box for each value of ``by``.
+
+Finally, when calling boxplot on a :class:`Groupby` object, a dict of ``return_type``
+is returned, where the keys are the same as the Groupby object. The plot has a
+facet for each key, with each facet containing a box for each column of the
+DataFrame.
+
+.. ipython:: python
+
+   np.random.seed(1234)
+   df_box = DataFrame(np.random.randn(50, 2))
+   df_box['g'] = np.random.choice(['A', 'B'], size=50)
+   df_box.loc[df_box['g'] == 'B', 1] += 3
+
+..ipython:: python
+
+   @savefig(boxplot_groupby.png)
+   df_box.boxplot(by='g')
+
+   @savefig groupby_boxplot_vis.png
+   df_box.groupby('g').boxplot()
+
+
 .. _visualization.area_plot:
 
 Area Plot

pandas/core/frame.py

@@ -4857,7 +4857,8 @@ def _put_str(s, space):
 
 
 def boxplot(self, column=None, by=None, ax=None, fontsize=None,
-            rot=0, grid=True, **kwds):
+            rot=0, grid=True, figsize=None, layout=None, return_type=None,
+            **kwds):
     """
     Make a box plot from DataFrame column/columns optionally grouped
     (stratified) by one or more columns
@@ -4875,17 +4876,32 @@ def boxplot(self, column=None, by=None, ax=None, fontsize=None,
         Rotation for ticks
     grid : boolean, default None (matlab style default)
         Axis grid lines
+    layout : tuple (optional)
+        (rows, columns) for the layout of the plot
+    return_type : bool, default False
+        Whether to return a dict whose values are the lines of the boxplot
+    kwds : other plotting keyword arguments to be passed to matplotlib boxplot
+           function
 
     Returns
     -------
     ax : matplotlib.axes.AxesSubplot
+    lines : dict (optional)
+
+    Notes
+    -----
+    Use ``return_dict=True`` when you want to modify the appearance
+    of the lines. In this case a named tuple is returned.
     """
     import pandas.tools.plotting as plots
     import matplotlib.pyplot as plt
     ax = plots.boxplot(self, column=column, by=by, ax=ax,
-                       fontsize=fontsize, grid=grid, rot=rot, **kwds)
+                       fontsize=fontsize, grid=grid, rot=rot,
+                       figsize=figsize, layout=layout, return_dict=return_dict,
+                       **kwds)
     plt.draw_if_interactive()
     return ax
+
 DataFrame.boxplot = boxplot
 
 ops.add_flex_arithmetic_methods(DataFrame, **ops.frame_flex_funcs)

pandas/tests/test_graphics.py

@@ -1309,14 +1309,14 @@ def test_boxplot(self):
         df['indic'] = ['foo', 'bar'] * 3
         df['indic2'] = ['foo', 'bar', 'foo'] * 2
 
-        _check_plot_works(df.boxplot)
-        _check_plot_works(df.boxplot, column=['one', 'two'])
+        _check_plot_works(df.boxplot, return_type='dict')
+        _check_plot_works(df.boxplot, column=['one', 'two'], return_type='dict')
         _check_plot_works(df.boxplot, column=['one', 'two'], by='indic')
         _check_plot_works(df.boxplot, column='one', by=['indic', 'indic2'])
         _check_plot_works(df.boxplot, by='indic')
         _check_plot_works(df.boxplot, by=['indic', 'indic2'])
-        _check_plot_works(plotting.boxplot, df['one'])
-        _check_plot_works(df.boxplot, notch=1)
+        _check_plot_works(plotting.boxplot, df['one'], return_type='dict')
+        _check_plot_works(df.boxplot, notch=1, return_type='dict')
         _check_plot_works(df.boxplot, by='indic', notch=1)
 
         df = DataFrame(np.random.rand(10, 2), columns=['Col1', 'Col2'])
@@ -1337,10 +1337,83 @@ def test_boxplot(self):
 
         # When by is None, check that all relevant lines are present in the dict
         fig, ax = self.plt.subplots()
-        d = df.boxplot(ax=ax)
+        d = df.boxplot(ax=ax, return_type='dict')
         lines = list(itertools.chain.from_iterable(d.values()))
         self.assertEqual(len(ax.get_lines()), len(lines))
 
+    @slow
+    def test_boxplot_return_type(self):
+        # API change in https://github.com/pydata/pandas/pull/7096
+        import matplotlib as mpl
+
+        df = DataFrame(randn(6, 4),
+                       index=list(string.ascii_letters[:6]),
+                       columns=['one', 'two', 'three', 'four'])
+        with tm.assertRaises(ValueError):
+            df.boxplot(return_type='NOTATYPE')
+
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.boxplot()
+        self.assertIsInstance(result, dict)  # change to Axes in future
+
+        with tm.assert_produces_warning(False):
+            result = df.boxplot(return_type='dict')
+        self.assertIsInstance(result, dict)
+
+        with tm.assert_produces_warning(False):
+            result = df.boxplot(return_type='axes')
+        self.assertIsInstance(result, mpl.axes.Axes)
+
+        with tm.assert_produces_warning(False):
+            result = df.boxplot(return_type='both')
+        self.assertIsInstance(result, tuple)
+
+    @slow
+    def test_boxplot_return_type_by(self):
+        import matplotlib as mpl
+
+        df = DataFrame(np.random.randn(10, 2))
+        df['g'] = ['a'] * 5 + ['b'] * 5
+
+        # old style: return_type=None
+        result = df.boxplot(by='g')
+        self.assertIsInstance(result, np.ndarray)
+        self.assertIsInstance(result[0], mpl.axes.Axes)
+
+        result = df.boxplot(by='g', return_type='dict')
+        self.assertIsInstance(result, dict)
+        self.assertIsInstance(result[0], dict)
+
+        result = df.boxplot(by='g', return_type='axes')
+        self.assertIsInstance(result, dict)
+        self.assertIsInstance(result[0], mpl.axes.Axes)
+
+        result = df.boxplot(by='g', return_type='both')
+        self.assertIsInstance(result, dict)
+        self.assertIsInstance(result[0], tuple)
+        self.assertIsInstance(result[0][0], mpl.axes.Axes)
+        self.assertIsInstance(result[0][1], dict)
+
+        # now for groupby
+        with tm.assert_produces_warning(FutureWarning):
+            result = df.groupby('g').boxplot()
+        self.assertIsInstance(result, dict)
+        self.assertIsInstance(result['a'], dict)
+
+        result = df.groupby('g').boxplot(return_type='dict')
+        self.assertIsInstance(result, dict)
+        self.assertIsInstance(result['a'], dict)
+
+        result = df.groupby('g').boxplot(return_type='axes')
+        self.assertIsInstance(result, dict)
+        self.assertIsInstance(result['a'], mpl.axes.Axes)
+
+        result = df.groupby('g').boxplot(return_type='both')
+        self.assertIsInstance(result, dict)
+        self.assertIsInstance(result['a'], tuple)
+        self.assertIsInstance(result['a'][0], mpl.axes.Axes)
+        self.assertIsInstance(result['a'][1], dict)
+
     @slow
     def test_kde(self):
         _skip_if_no_scipy()
@@ -2044,31 +2117,32 @@ class TestDataFrameGroupByPlots(TestPlotBase):
 
     @slow
     def test_boxplot(self):
-        # unable to check layout because boxplot doesn't return ndarray
-        # axes_num can be checked using gcf().axes
         grouped = self.hist_df.groupby(by='gender')
-        box = _check_plot_works(grouped.boxplot)
+        box = _check_plot_works(grouped.boxplot, return_type='dict')
         self._check_axes_shape(self.plt.gcf().axes, axes_num=2)
 
-        box = _check_plot_works(grouped.boxplot, subplots=False)
+        box = _check_plot_works(grouped.boxplot, subplots=False,
+                                return_type='dict')
         self._check_axes_shape(self.plt.gcf().axes, axes_num=2)
 
         tuples = lzip(string.ascii_letters[:10], range(10))
         df = DataFrame(np.random.rand(10, 3),
                        index=MultiIndex.from_tuples(tuples))
 
         grouped = df.groupby(level=1)
-        box = _check_plot_works(grouped.boxplot)
+        box = _check_plot_works(grouped.boxplot, return_type='dict')
         self._check_axes_shape(self.plt.gcf().axes, axes_num=10)
 
-        box = _check_plot_works(grouped.boxplot, subplots=False)
+        box = _check_plot_works(grouped.boxplot, subplots=False,
+                                return_type='dict')
         self._check_axes_shape(self.plt.gcf().axes, axes_num=10)
 
         grouped = df.unstack(level=1).groupby(level=0, axis=1)
-        box = _check_plot_works(grouped.boxplot)
+        box = _check_plot_works(grouped.boxplot, return_type='dict')
         self._check_axes_shape(self.plt.gcf().axes, axes_num=3)
 
-        box = _check_plot_works(grouped.boxplot, subplots=False)
+        box = _check_plot_works(grouped.boxplot, subplots=False,
+                                return_type='dict')
         self._check_axes_shape(self.plt.gcf().axes, axes_num=3)
 
     def test_series_plot_color_kwargs(self):
@@ -2133,31 +2207,38 @@ def test_grouped_box_layout(self):
         self.assertRaises(ValueError, df.boxplot, column=['weight', 'height'],
                           by=df.gender, layout=(1, 1))
         self.assertRaises(ValueError, df.boxplot, column=['height', 'weight', 'category'],
-                          layout=(2, 1))
+                          layout=(2, 1), return_type='dict')
 
-        box = _check_plot_works(df.groupby('gender').boxplot, column='height')
+        box = _check_plot_works(df.groupby('gender').boxplot, column='height',
+                                return_type='dict')
         self._check_axes_shape(self.plt.gcf().axes, axes_num=2)
 
-        box = _check_plot_works(df.groupby('category').boxplot, column='height')
+        box = _check_plot_works(df.groupby('category').boxplot, column='height',
+                                return_type='dict')
         self._check_axes_shape(self.plt.gcf().axes, axes_num=4)
 
         # GH 6769
-        box = _check_plot_works(df.groupby('classroom').boxplot, column='height')
+        box = _check_plot_works(df.groupby('classroom').boxplot,
+                                column='height', return_type='dict')
         self._check_axes_shape(self.plt.gcf().axes, axes_num=3)
 
         box = df.boxplot(column=['height', 'weight', 'category'], by='gender')
         self._check_axes_shape(self.plt.gcf().axes, axes_num=3)
 
-        box = df.groupby('classroom').boxplot(column=['height', 'weight', 'category'])
+        box = df.groupby('classroom').boxplot(
+            column=['height', 'weight', 'category'], return_type='dict')
         self._check_axes_shape(self.plt.gcf().axes, axes_num=3)
 
-        box = _check_plot_works(df.groupby('category').boxplot, column='height', layout=(3, 2))
+        box = _check_plot_works(df.groupby('category').boxplot, column='height',
+                                layout=(3, 2), return_type='dict')
         self._check_axes_shape(self.plt.gcf().axes, axes_num=4)
 
         box = df.boxplot(column=['height', 'weight', 'category'], by='gender', layout=(4, 1))
         self._check_axes_shape(self.plt.gcf().axes, axes_num=3)
 
-        box = df.groupby('classroom').boxplot(column=['height', 'weight', 'category'], layout=(1, 4))
+        box = df.groupby('classroom').boxplot(
+            column=['height', 'weight', 'category'], layout=(1, 4),
+            return_type='dict')
         self._check_axes_shape(self.plt.gcf().axes, axes_num=3)
 
     @slow