API: Change faceted boxplot return_type

Aligns behavior of `Groupby.boxplot` and DataFrame.boxplot(by=.)
to return a Series.

Author: TomAugspurger

doc/source/visualization.rst

@@ -458,22 +458,27 @@ columns:
 
 .. warning::
 
-   The default changed from ``'dict'`` to ``'axes'`` in version 0.18.0.
-
-Plot functions return scalar or arrays of :class:`matplotlib Axes <matplotlib.axes.Axes>`.
-In ``boxplot``, the return type can be controlled by the ``return_type``, keyword. The valid choices are ``{"axes", "dict", "both"}``. If the ``by`` argument is ``None``,
-
-* ``'axes'`` returns a single matplotlib axes.
-* ``'dict'`` returns a dict of matplotlib artists, similar to the matplotlib boxplot function.
-* ``'both'`` returns a named tuple of axes and dicts.
-
-When ``by`` is not None, you get back an ``OrderedDict`` of whatever ``return_type`` is.
-Unless ``return_type`` is just ``None``, in which case you get back an array of axes.
-
-Finally, when calling boxplot on a :class:`Groupby` object, an  ``OrderedDict`` 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.
+   The default changed from ``'dict'`` to ``'axes'`` in version 0.19.0.
+
+In ``boxplot``, the return type can be controlled by the ``return_type``, keyword. The valid choices are ``{"axes", "dict", "both", None}``.
+Faceting, created by ``DataFrame.boxplot`` with the ``by``
+keyword, will affect the output type as well:
+
+================ ======= ==========================
+``return_type=`` Faceted Output type
+---------------- ------- --------------------------
+
+``None``         No      axes
+``None``         Yes     2-D ndarray of axes
+``'axes'``       No      axes
+``'axes'``       Yes     Series of axes
+``'dict'``       No      dict of artists
+``'dict'``       Yes     Series of dicts of artists
+``'both'``       No      namedtuple
+``'both'``       Yes     Series of namedtuples
+================ ======= ==========================
+
+``Groupby.boxplot`` always returns a Series of ``return_type``.
 
 .. ipython:: python
    :okwarning:

doc/source/whatsnew/v0.18.0.txt

@@ -1168,7 +1168,6 @@ Removal of prior version deprecations/changes
 - Removal of ``rolling_corr_pairwise`` in favor of ``.rolling().corr(pairwise=True)`` (:issue:`4950`)
 - Removal of ``expanding_corr_pairwise`` in favor of ``.expanding().corr(pairwise=True)`` (:issue:`4950`)
 - Removal of ``DataMatrix`` module. This was not imported into the pandas namespace in any event (:issue:`12111`)
-- Changed the default value for the ``return_type`` parameter for ``DataFrame.plot.box`` and ``DataFrame.boxplot`` from ``None`` to ``"axes"``. These methods will now return a matplotlib axes by default instead of a dictionary of artists. See :ref:`here <visualization.box.return>` (:issue:`6581`).
 - Removal of ``cols`` keyword in favor of ``subset`` in ``DataFrame.duplicated()`` and ``DataFrame.drop_duplicates()`` (:issue:`6680`)
 - Removal of the ``read_frame`` and ``frame_query`` (both aliases for ``pd.read_sql``)
   and ``write_frame`` (alias of ``to_sql``) functions in the ``pd.io.sql`` namespace,

doc/source/whatsnew/v0.19.0.txt

@@ -494,6 +494,7 @@ API changes
 - ``__setitem__`` will no longer apply a callable rhs as a function instead of storing it. Call ``where`` directly to get the previous behavior. (:issue:`13299`)
 - Passing ``Period`` with multiple frequencies to normal ``Index`` now returns ``Index`` with ``object`` dtype (:issue:`13664`)
 - ``PeriodIndex.fillna`` with ``Period`` has different freq now coerces to ``object`` dtype (:issue:`13664`)
+- Faceted boxplots from ``DataFrame.boxplot(by=col)`` now return a ``Series`` when ``return_type`` is not None. Previously these returned an ``OrderedDict``. Note that when ``return_type=None``, the default, these still return a 2-D NumPy array. (:issue:`12216`, :issue:`7096`)
 - More informative exceptions are passed through the csv parser. The exception type would now be the original exception type instead of ``CParserError``. (:issue:`13652`)
 - ``astype()`` will now accept a dict of column name to data types mapping as the ``dtype`` argument. (:issue:`12086`)
 - The ``pd.read_json`` and ``DataFrame.to_json`` has gained support for reading and writing json lines with ``lines`` option see :ref:`Line delimited json <io.jsonl>` (:issue:`9180`)
@@ -1282,9 +1283,9 @@ Removal of prior version deprecations/changes
 
   Now legacy time rules raises ``ValueError``. For the list of currently supported offsets, see :ref:`here <timeseries.offset_aliases>`
 
+- The default value for the ``return_type`` parameter for ``DataFrame.plot.box`` and ``DataFrame.boxplot`` changed from ``None`` to ``"axes"``. These methods will now return a matplotlib axes by default instead of a dictionary of artists. See :ref:`here <visualization.box.return>` (:issue:`6581`).
 - The ``tquery`` and ``uquery`` functions in the ``pandas.io.sql`` module are removed (:issue:`5950`).
 
-
 .. _whatsnew_0190.performance:
 
 Performance Improvements

pandas/tests/plotting/common.py

@@ -5,8 +5,8 @@
 import os
 import warnings
 
-from pandas import DataFrame
-from pandas.compat import zip, iteritems, OrderedDict
+from pandas import DataFrame, Series
+from pandas.compat import zip, iteritems
 from pandas.util.decorators import cache_readonly
 from pandas.types.api import is_list_like
 import pandas.util.testing as tm
@@ -445,7 +445,8 @@ def _check_box_return_type(self, returned, return_type, expected_keys=None,
                     self.assertIsInstance(r, Axes)
                 return
 
-            self.assertTrue(isinstance(returned, OrderedDict))
+            self.assertTrue(isinstance(returned, Series))
+
             self.assertEqual(sorted(returned.keys()), sorted(expected_keys))
             for key, value in iteritems(returned):
                 self.assertTrue(isinstance(value, types[return_type]))

pandas/tests/plotting/test_boxplot_method.py

@@ -92,6 +92,12 @@ def test_boxplot_legacy(self):
         lines = list(itertools.chain.from_iterable(d.values()))
         self.assertEqual(len(ax.get_lines()), len(lines))
 
+    @slow
+    def test_boxplot_return_type_none(self):
+        # GH 12216; return_type=None & by=None -> axes
+        result = self.hist_df.boxplot()
+        self.assertTrue(isinstance(result, self.plt.Axes))
+
     @slow
     def test_boxplot_return_type_legacy(self):
         # API change in https://github.com/pydata/pandas/pull/7096
@@ -103,10 +109,8 @@ def test_boxplot_return_type_legacy(self):
         with tm.assertRaises(ValueError):
             df.boxplot(return_type='NOTATYPE')
 
-        with tm.assert_produces_warning(FutureWarning):
-            result = df.boxplot()
-        # change to Axes in future
-        self._check_box_return_type(result, 'dict')
+        result = df.boxplot()
+        self._check_box_return_type(result, 'axes')
 
         with tm.assert_produces_warning(False):
             result = df.boxplot(return_type='dict')
@@ -140,6 +144,7 @@ def _check_ax_limits(col, ax):
         p = df.boxplot(['height', 'weight', 'age'], by='category')
         height_ax, weight_ax, age_ax = p[0, 0], p[0, 1], p[1, 0]
         dummy_ax = p[1, 1]
+
         _check_ax_limits(df['height'], height_ax)
         _check_ax_limits(df['weight'], weight_ax)
         _check_ax_limits(df['age'], age_ax)
@@ -163,8 +168,7 @@ def test_boxplot_legacy(self):
         grouped = self.hist_df.groupby(by='gender')
         with tm.assert_produces_warning(UserWarning):
             axes = _check_plot_works(grouped.boxplot, return_type='axes')
-        self._check_axes_shape(list(axes.values()), axes_num=2, layout=(1, 2))
-
+        self._check_axes_shape(list(axes.values), axes_num=2, layout=(1, 2))
         axes = _check_plot_works(grouped.boxplot, subplots=False,
                                  return_type='axes')
         self._check_axes_shape(axes, axes_num=1, layout=(1, 1))
@@ -175,7 +179,7 @@ def test_boxplot_legacy(self):
         grouped = df.groupby(level=1)
         with tm.assert_produces_warning(UserWarning):
             axes = _check_plot_works(grouped.boxplot, return_type='axes')
-        self._check_axes_shape(list(axes.values()), axes_num=10, layout=(4, 3))
+        self._check_axes_shape(list(axes.values), axes_num=10, layout=(4, 3))
 
         axes = _check_plot_works(grouped.boxplot, subplots=False,
                                  return_type='axes')
@@ -184,8 +188,7 @@ def test_boxplot_legacy(self):
         grouped = df.unstack(level=1).groupby(level=0, axis=1)
         with tm.assert_produces_warning(UserWarning):
             axes = _check_plot_works(grouped.boxplot, return_type='axes')
-        self._check_axes_shape(list(axes.values()), axes_num=3, layout=(2, 2))
-
+        self._check_axes_shape(list(axes.values), axes_num=3, layout=(2, 2))
         axes = _check_plot_works(grouped.boxplot, subplots=False,
                                  return_type='axes')
         self._check_axes_shape(axes, axes_num=1, layout=(1, 1))
@@ -226,8 +229,7 @@ def test_grouped_box_return_type(self):
             expected_keys=['height', 'weight', 'category'])
 
         # now for groupby
-        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
-            result = df.groupby('gender').boxplot()
+        result = df.groupby('gender').boxplot(return_type='dict')
         self._check_box_return_type(
             result, 'dict', expected_keys=['Male', 'Female'])
 
@@ -347,7 +349,7 @@ def test_grouped_box_multiple_axes(self):
         with tm.assert_produces_warning(UserWarning):
             returned = df.boxplot(column=['height', 'weight', 'category'],
                                   by='gender', return_type='axes', ax=axes[0])
-        returned = np.array(list(returned.values()))
+        returned = np.array(list(returned.values))
         self._check_axes_shape(returned, axes_num=3, layout=(1, 3))
         self.assert_numpy_array_equal(returned, axes[0])
         self.assertIs(returned[0].figure, fig)
@@ -357,7 +359,7 @@ def test_grouped_box_multiple_axes(self):
             returned = df.groupby('classroom').boxplot(
                 column=['height', 'weight', 'category'],
                 return_type='axes', ax=axes[1])
-        returned = np.array(list(returned.values()))
+        returned = np.array(list(returned.values))
         self._check_axes_shape(returned, axes_num=3, layout=(1, 3))
         self.assert_numpy_array_equal(returned, axes[1])
         self.assertIs(returned[0].figure, fig)

pandas/tests/plotting/test_frame.py

@@ -1233,7 +1233,7 @@ def test_boxplot_subplots_return_type(self):
 
         # normal style: return_type=None
         result = df.plot.box(subplots=True)
-        self.assertIsInstance(result, np.ndarray)
+        self.assertIsInstance(result, Series)
         self._check_box_return_type(result, None, expected_keys=[
                                     'height', 'weight', 'category'])