DOC: add docstring re: #477

Author: wesm

pandas/core/frame.py

@@ -2419,7 +2419,9 @@ def stack(self, level=-1, dropna=True):
 
     def unstack(self, level=-1):
         """
-        "Unstack" level from MultiLevel index to produce reshaped DataFrame
+        "Unstack" level from MultiLevel index to produce reshaped DataFrame. If
+        the index is not a MultiIndex, the output will be a Series (the
+        analogue of stack when the columns are not a MultiIndex)
 
         Parameters
         ----------
@@ -2439,14 +2441,21 @@ def unstack(self, level=-1):
         one  1.  2.
         two  3.  4.
 
-        >>> s.unstack(level=0)
+        >>> df = s.unstack(level=0)
+        >>> df
            one  two
         a  1.   2.
         b  3.   4.
 
+        >>> df.unstack()
+        one  a  1.
+             b  3.
+        two  a  2.
+             b  4.
+
         Returns
         -------
-        unstacked : DataFrame
+        unstacked : DataFrame or Series
         """
         from pandas.core.reshape import unstack
         if isinstance(level, (tuple, list)):

pandas/core/reshape.py

@@ -286,7 +286,7 @@ def unstack(obj, level):
         if isinstance(obj.index, MultiIndex):
             return _unstack_frame(obj, level)
         else:
-            return obj.transpose().stack(dropna=False)
+            return obj.T.stack(dropna=False)
     else:
         unstacker = _Unstacker(obj.values, obj.index, level=level)
         return unstacker.get_result()

pandas/tests/test_frame.py

@@ -3904,8 +3904,9 @@ def test_stack_unstack(self):
     def test_unstack_to_series(self):
         # check reversibility
         data = self.frame.unstack()
+
         self.assertTrue(isinstance(data, Series))
-        undo = data.unstack().transpose()
+        undo = data.unstack().T
         assert_frame_equal(undo, self.frame)
 
         # check NA handling

pandas/tests/test_multilevel.py

@@ -502,6 +502,7 @@ def test_unstack_bug(self):
                         'extra': np.arange(6.)})
 
         result = df.groupby(['state','exp','barcode','v']).apply(len)
+
         unstacked = result.unstack()
         restacked = unstacked.stack()
         assert_series_equal(restacked,