ENH/API: DataFrame.stack() supports level=None and sequentially=True/False.

Author: seth-p

pandas/core/frame.py

@@ -3392,7 +3392,7 @@ def pivot(self, index=None, columns=None, values=None):
         from pandas.core.reshape import pivot
         return pivot(self, index=index, columns=columns, values=values)
 
-    def stack(self, level=-1, dropna=True):
+    def stack(self, level=-1, dropna=True, sequentially=True):
         """
         Pivot a level of the (possibly hierarchical) column labels, returning a
         DataFrame (or Series in the case of an object with a single level of
@@ -3402,11 +3402,15 @@ def stack(self, level=-1, dropna=True):
 
         Parameters
         ----------
-        level : int, string, or list of these, default last level
-            Level(s) to stack, can pass level name
+        level : int, string, list of these, or None; default -1 (last level)
+            Level(s) to stack, can pass level name(s).
+            None specifies all column levels, i.e. list(range(columns.nlevels)).
         dropna : boolean, default True
             Whether to drop rows in the resulting Frame/Series with no valid
             values
+        sequentially : boolean, default True
+            When level is a list (or None), whether the multiple column levels
+            should be stacked sequentially (if True) or simultaneously (if False).
 
         Examples
         ----------
@@ -3425,14 +3429,15 @@ def stack(self, level=-1, dropna=True):
         -------
         stacked : DataFrame or Series
         """
-        from pandas.core.reshape import stack, stack_multiple
+        from pandas.core.reshape import stack_levels_sequentially, stack_multi_levels_simultaneously
 
-        if isinstance(level, (tuple, list)):
-            return stack_multiple(self, level, dropna=dropna)
+        level_num = self.columns._get_level_numbers(level, allow_mixed_names_and_numbers=False)
+        if isinstance(level_num, (tuple, list, set)) and isinstance(self.columns, MultiIndex) and (not sequentially):
+                return stack_multi_levels_simultaneously(self, level_num, dropna=dropna)
         else:
-            return stack(self, level, dropna=dropna)
+            return stack_levels_sequentially(self, level_num, dropna=dropna)
 
-    def unstack(self, level=-1):
+    def unstack(self, level=-1, sequentially=True):
         """
         Pivot a level of the (necessarily hierarchical) index labels, returning
         a DataFrame having a new level of column labels whose inner-most level
@@ -3443,8 +3448,12 @@ def unstack(self, level=-1):
 
         Parameters
         ----------
-        level : int, string, or list of these, default -1 (last level)
-            Level(s) of index to unstack, can pass level name
+        level : int, string, list of these, or None; default -1 (last level)
+            Level(s) of index to unstack, can pass level name(s).
+            None specifies all index levels, i.e. list(range(index.nlevels)).
+        sequentially : boolean, default True
+            When level is a list (or None), whether the multiple index levels
+            should be stacked sequentially (if True) or simultaneously (if False).
 
         See also
         --------

pandas/core/index.py

@@ -824,10 +824,26 @@ def _validate_index_level(self, level):
             raise KeyError('Level %s must be same as name (%s)'
                            % (level, self.name))
 
-    def _get_level_number(self, level):
+    def _get_level_number(self, level, ignore_names=False):
+        if ignore_names and (not isinstance(level, int)):
+            raise KeyError('Level %s not found' % str(level))
         self._validate_index_level(level)
         return 0
 
+    def _get_level_numbers(self, levels, allow_mixed_names_and_numbers=False):
+        if levels is None:
+            return list(range(self.nlevels))
+        elif isinstance(levels, (list, tuple, set)):
+            if (not allow_mixed_names_and_numbers) and (not all(lev in self.names for lev in levels)):
+                if all(isinstance(lev, int) for lev in levels):
+                    return type(levels)(self._get_level_number(level, ignore_names=True) for level in levels)
+                else:
+                    raise ValueError("level should contain all level names or all level numbers, "
+                                     "not a mixture of the two.")
+            return type(levels)(self._get_level_number(level) for level in levels)
+        else:
+            return self._get_level_number(levels)
+
     @cache_readonly
     def inferred_type(self):
         """ return a string of the type inferred from the values """
@@ -3161,28 +3177,30 @@ def _from_elements(values, labels=None, levels=None, names=None,
                        sortorder=None):
         return MultiIndex(levels, labels, names, sortorder=sortorder)
 
-    def _get_level_number(self, level):
-        try:
+    def _get_level_number(self, level, ignore_names=False):
+        if not ignore_names:
             count = self.names.count(level)
             if count > 1:
                 raise ValueError('The name %s occurs multiple times, use a '
                                  'level number' % level)
-            level = self.names.index(level)
-        except ValueError:
-            if not isinstance(level, int):
-                raise KeyError('Level %s not found' % str(level))
-            elif level < 0:
-                level += self.nlevels
-                if level < 0:
-                    orig_level = level - self.nlevels
-                    raise IndexError(
-                        'Too many levels: Index has only %d levels, '
-                        '%d is not a valid level number' % (self.nlevels, orig_level)
-                    )
-            # Note: levels are zero-based
-            elif level >= self.nlevels:
-                raise IndexError('Too many levels: Index has only %d levels, '
-                                 'not %d' % (self.nlevels, level + 1))
+            try:
+                return self.names.index(level)
+            except ValueError:
+                pass
+        if not isinstance(level, int):
+            raise KeyError('Level %s not found' % str(level))
+        elif level < 0:
+            level += self.nlevels
+            if level < 0:
+                orig_level = level - self.nlevels
+                raise IndexError(
+                    'Too many levels: Index has only %d levels, '
+                    '%d is not a valid level number' % (self.nlevels, orig_level)
+                )
+        # Note: levels are zero-based
+        elif level >= self.nlevels:
+            raise IndexError('Too many levels: Index has only %d levels, '
+                             'not %d' % (self.nlevels, level + 1))
         return level
 
     _tuples = None
@@ -4852,7 +4870,7 @@ def _trim_front(strings):
 
 
 def _sanitize_and_check(indexes):
-    kinds = list(set([type(index) for index in indexes]))
+    kinds = list(set(type(index) for index in indexes))
 
     if list in kinds:
         if len(kinds) > 1:
@@ -4873,11 +4891,11 @@ def _get_consensus_names(indexes):
 
     # find the non-none names, need to tupleify to make
     # the set hashable, then reverse on return
-    consensus_names = set([
+    consensus_names = set(
         tuple(i.names) for i in indexes if all(n is not None for n in i.names)
-    ])
+    )
     if len(consensus_names) == 1:
-        return list(list(consensus_names)[0])
+        return list(consensus_names.pop())
     return [None] * indexes[0].nlevels