BUG: pivot_table always returns a DataFrame

Before this commit, if * `values` is not list like * `columns` is `None` * `aggfunc` is not instance of `list` `pivot_table` returns a `Series`. This commit adds checking for `columns.nlevels` is greater than 1 to prevent from casting `table` to a `Series`. This will fix pandas-dev#4386. DOC: add docs for pandas-dev#13554

Author: yui-knk

doc/source/whatsnew/v0.20.0.txt

@@ -1287,6 +1287,38 @@ joins, :meth:`DataFrame.join` and :func:`merge`, and the ``.align`` methods.
 
  left.join(right, how='inner')
 
+.. _whatsnew_0200.api_breaking.pivot_table:
+
+Pivot Table always returns a DataFrame
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The documentation for :meth:`pivot_table` states that a ``DataFrame`` is *always* returned. Here a bug
+is fixed that allowed this to return a ``Series`` under a narrow circumstance. (:issue:`4386`)
+
+.. ipython:: python
+
+ df = DataFrame({'col1': [3, 4, 5],
+ 'col2': ['C', 'D', 'E'],
+ 'col3': [1, 3, 9]})
+ df
+
+Previous Behavior:
+
+.. code-block:: ipython
+
+ In [2]: df.pivot_table('col1', index=['col3', 'col2'], aggfunc=np.sum)
+ Out[2]:
+ col3 col2
+ 1 C 3
+ 3 D 4
+ 9 E 5
+ Name: col1, dtype: int64
+
+New Behavior:
+
+.. ipython:: python
+
+ df.pivot_table('col1', index=['col3', 'col2'], aggfunc=np.sum)
 
 .. _whatsnew_0200.api:
 

pandas/core/reshape/pivot.py

@@ -170,7 +170,8 @@ def pivot_table(data, values=None, index=None, columns=None, aggfunc='mean',
  margins_name=margins_name)
 
  # discard the top level
- if values_passed and not values_multi and not table.empty:
+ if values_passed and not values_multi and not table.empty and \
+ (table.columns.nlevels > 1):
  table = table[values[0]]
 
  if len(index) == 0 and len(columns) > 0:

pandas/tests/reshape/test_pivot.py

@@ -940,6 +940,44 @@ def test_categorical_pivot_index_ordering(self):
  columns=expected_columns)
  tm.assert_frame_equal(result, expected)
 
+ def test_pivot_table_not_series(self):
+ # GH 4386
+ # pivot_table always returns a DataFrame
+ # when values is not list like and columns is None
+ # and aggfunc is not instance of list
+ df = DataFrame({'col1': [3, 4, 5],
+ 'col2': ['C', 'D', 'E'],
+ 'col3': [1, 3, 9]})
+
+ result = df.pivot_table('col1', index=['col3', 'col2'], aggfunc=np.sum)
+ m = MultiIndex.from_arrays([[1, 3, 9],
+ ['C', 'D', 'E']],
+ names=['col3', 'col2'])
+ expected = DataFrame([3, 4, 5],
+ index=m, columns=['col1'])
+
+ tm.assert_frame_equal(result, expected)
+
+ result = df.pivot_table(
+ 'col1', index='col3', columns='col2', aggfunc=np.sum
+ )
+ expected = DataFrame([[3, np.NaN, np.NaN],
+ [np.NaN, 4, np.NaN],
+ [np.NaN, np.NaN, 5]],
+ index=Index([1, 3, 9], name='col3'),
+ columns=Index(['C', 'D', 'E'], name='col2'))
+
+ tm.assert_frame_equal(result, expected)
+
+ result = df.pivot_table('col1', index='col3', aggfunc=[np.sum])
+ m = MultiIndex.from_arrays([['sum'],
+ ['col1']])
+ expected = DataFrame([3, 4, 5],
+ index=Index([1, 3, 9], name='col3'),
+ columns=m)
+
+ tm.assert_frame_equal(result, expected)
+
 
 class TestCrosstab(tm.TestCase):