API: Accept 'axis' keyword argument for reindex

TomAugspurger · TomAugspurger · commit 895e68ac8664 · 2017-10-06T08:09:40.000-05:00
diff --git a/doc/source/whatsnew/v0.21.0.txt b/doc/source/whatsnew/v0.21.0.txt
@@ -109,20 +109,32 @@ For example:
     # the following is now equivalent
     df.drop(columns=['B', 'C'])
 
-``rename`` now also accepts axis keyword
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``rename``, ``reindex`` now also accepts axis keyword
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The :meth:`~DataFrame.rename` method has gained the ``axis`` keyword as an
-alternative to specify the ``axis`` to target (:issue:`12392`).
+The :meth:`DataFrame.rename` and :meth:`DataFrame.reindex` methods have gained
+the ``axis`` keyword to specify the axis to target with the operation. This
+harmonizes the method signature of these methods with most of the rest of the
+library (:issue:`12392`).
+
+Here's ``rename``:
 
 .. ipython:: 
 
     df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
     df.rename(str.lower, axis='columns')
     df.rename(id, axis='index')
 
+And ``reindex``:
+
+.. ipython::
+
+    df.reindex(['A', 'B', 'C'], axis='columns')
+    df.reindex([0, 1, 3], axis='index')
+
 The ``.rename(index=id, columns=str.lower)`` style continues to work as before.
-We *highly* encourage using named arguments to avoid confusion.
+We *highly* encourage using named arguments to avoid confusion when using either
+style.
 
 .. _whatsnew_0210.enhancements.categorical_dtype:
 
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
@@ -114,6 +114,8 @@
     versionadded_to_excel='',
     optional_mapper="""mapper : dict-like or function
             Applied to the axis specified by `axis`""",
+    optional_labels="""labels : array-like
+            New labels / index to conform the axis specified by 'axis' to.""",
     optional_axis="""axis : int or str, optional
             Axis to target. Can be either the axis name ('rows', 'columns')
             or number (0, 1).""",
@@ -2805,7 +2807,7 @@ def _validate_axis_style_args(self, arg, arg_name, index, columns,
                 "'.{method_name}(index=a, columns=b)'. "
                 "Use keyword arguments to remove any ambiguity."
             ).format(method_name=method_name)
-            warnings.warn(msg)
+            warnings.warn(msg, stacklevel=3)
             index, columns = arg, index
         elif index is None and columns is None:
             index = arg
@@ -2937,7 +2939,11 @@ def align(self, other, join='outer', axis=None, level=None, copy=True,
                                             broadcast_axis=broadcast_axis)
 
     @Appender(_shared_docs['reindex'] % _shared_doc_kwargs)
-    def reindex(self, index=None, columns=None, **kwargs):
+    def reindex(self, labels=None, index=None, columns=None, axis=None,
+                **kwargs):
+        index, columns = self._validate_axis_style_args(labels, 'labels',
+                                                        index, columns,
+                                                        axis, 'reindex')
         return super(DataFrame, self).reindex(index=index, columns=columns,
                                               **kwargs)
 
diff --git a/pandas/core/generic.py b/pandas/core/generic.py
@@ -2758,10 +2758,11 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False,
 
         Parameters
         ----------
-        %(axes)s : array-like, optional (can be specified in order, or as
-            keywords)
+        %(optional_labels)s
+        %(axes)s : array-like, optional (should be specified using keywords)
             New labels / index to conform to. Preferably an Index object to
             avoid duplicating data
+        %(optional_axis)s
         method : {None, 'backfill'/'bfill', 'pad'/'ffill', 'nearest'}, optional
             method to use for filling holes in reindexed DataFrame.
             Please note: this is only  applicable to DataFrames/Series with a
@@ -2793,6 +2794,11 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False,
         Examples
         --------
 
+        Note that ``.reindex`` can be called by specifying either
+
+            * One or both of ``index`` and ``columns``
+            * ``labels`` and ``axis``
+
         Create a dataframe with some fictional data.
 
         >>> index = ['Firefox', 'Chrome', 'Safari', 'IE10', 'Konqueror']
@@ -2843,6 +2849,26 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False,
         IE10                  404          0.08
         Chrome                200          0.02
 
+        We can also reindex the columns.
+
+        >>> df.reindex(columns=['http_status', 'user_agent'])
+                   http_status  user_agent
+        Firefox            200         NaN
+        Chrome             200         NaN
+        Safari             404         NaN
+        IE10               404         NaN
+        Konqueror          301         NaN
+
+        Or we can use "axis-style" keyword arguments
+
+        >>> df.reindex(['http_status', 'user_agent'], axis="columns")
+                   http_status  user_agent
+        Firefox            200         NaN
+        Chrome             200         NaN
+        Safari             404         NaN
+        IE10               404         NaN
+        Konqueror          301         NaN
+
         To further illustrate the filling functionality in
         ``reindex``, we will create a dataframe with a
         monotonically increasing index (for example, a sequence
@@ -2913,7 +2939,9 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False,
     # TODO: Decide if we care about having different examples for different
     #       kinds
 
-    @Appender(_shared_docs['reindex'] % dict(axes="axes", klass="NDFrame"))
+    @Appender(_shared_docs['reindex'] % dict(axes="axes", klass="NDFrame",
+                                             optional_labels="",
+                                             optional_axis=""))
     def reindex(self, *args, **kwargs):
 
         # construct the args
diff --git a/pandas/core/panel.py b/pandas/core/panel.py
@@ -40,7 +40,7 @@
     axes='items, major_axis, minor_axis',
     klass="Panel",
     axes_single_arg="{0, 1, 2, 'items', 'major_axis', 'minor_axis'}",
-    optional_mapper='', optional_axis='')
+    optional_mapper='', optional_axis='', optional_labels='')
 _shared_doc_kwargs['args_transpose'] = ("three positional arguments: each one"
                                         "of\n%s" %
                                         _shared_doc_kwargs['axes_single_arg'])
diff --git a/pandas/core/series.py b/pandas/core/series.py
@@ -85,7 +85,7 @@
     inplace="""inplace : boolean, default False
         If True, performs operation inplace and returns None.""",
     unique='np.ndarray', duplicated='Series',
-    optional_by='', optional_mapper='', optional_axis='',
+    optional_by='', optional_mapper='', optional_labels='', optional_axis='',
     versionadded_to_excel='\n    .. versionadded:: 0.20.0\n')
 
 
diff --git a/pandas/core/sparse/series.py b/pandas/core/sparse/series.py
@@ -35,7 +35,8 @@
 
 
 _shared_doc_kwargs = dict(axes='index', klass='SparseSeries',
-                          axes_single_arg="{0, 'index'}")
+                          axes_single_arg="{0, 'index'}",
+                          optional_labels='', optional_axis='')
 
 # -----------------------------------------------------------------------------
 # Wrapper function for Series arithmetic methods
diff --git a/pandas/tests/frame/test_axis_select_reindex.py b/pandas/tests/frame/test_axis_select_reindex.py
@@ -447,6 +447,80 @@ def test_reindex_dups(self):
         # reindex fails
         pytest.raises(ValueError, df.reindex, index=list(range(len(df))))
 
+    def test_reindex_axis_style(self):
+        df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
+        expected = pd.DataFrame({"A": [1, 2, np.nan], "B": [4, 5, np.nan]},
+                                index=[0, 1, 3])
+        result = df.reindex([0, 1, 3])
+        assert_frame_equal(result, expected)
+
+        result = df.reindex([0, 1, 3], axis=0)
+        assert_frame_equal(result, expected)
+
+        result = df.reindex([0, 1, 3], axis='index')
+        assert_frame_equal(result, expected)
+
+    def test_reindex_positional_warns(self):
+        df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
+        expected = pd.DataFrame({"A": [1., 2], 'B': [4., 5],
+                                 "C": [np.nan, np.nan]})
+        with tm.assert_produces_warning(UserWarning):
+            result = df.reindex([0, 1], ['A', 'B', 'C'])
+
+        assert_frame_equal(result, expected)
+
+    def test_reindex_axis_style_raises(self):
+        df = pd.DataFrame({"A": [1, 2, 3], 'B': [4, 5, 6]})
+        with tm.assert_raises_regex(TypeError, ''):
+            df.reindex([0, 1], ['A'], axis=1)
+
+        with tm.assert_raises_regex(TypeError, ''):
+            df.reindex([0, 1], ['A'], axis='index')
+
+        with tm.assert_raises_regex(TypeError, ''):
+            df.reindex(index=[0, 1], axis='index')
+
+        with tm.assert_raises_regex(TypeError, ''):
+            df.reindex(index=[0, 1], axis='columns')
+
+        with tm.assert_raises_regex(TypeError, ''):
+            df.reindex(columns=[0, 1], axis='columns')
+
+        with tm.assert_raises_regex(TypeError, ''):
+            df.reindex(index=[0, 1], columns=[0, 1], axis='columns')
+
+        with tm.assert_raises_regex(TypeError, ''):
+            df.reindex([0, 1], [0], ['A'])
+
+    def test_reindex_api_equivalence(self):
+        # equivalence of the labels/axis and index/columns API's
+        df = DataFrame([[1, 2, 3], [3, 4, 5], [5, 6, 7]],
+                       index=['a', 'b', 'c'],
+                       columns=['d', 'e', 'f'])
+
+        res1 = df.reindex(['b', 'a'])
+        res2 = df.reindex(index=['b', 'a'])
+        res3 = df.reindex(labels=['b', 'a'])
+        res4 = df.reindex(labels=['b', 'a'], axis=0)
+        res5 = df.reindex(['b', 'a'], axis=0)
+        for res in [res2, res3, res4, res5]:
+            tm.assert_frame_equal(res1, res)
+
+        res1 = df.reindex(columns=['e', 'd'])
+        res2 = df.reindex(['e', 'd'], axis=1)
+        res3 = df.reindex(labels=['e', 'd'], axis=1)
+        for res in [res2, res3]:
+            tm.assert_frame_equal(res1, res)
+
+        with tm.assert_produces_warning(UserWarning) as m:
+            res1 = df.reindex(['b', 'a'], ['e', 'd'])
+        assert 'reindex' in str(m[0].message)
+        res2 = df.reindex(columns=['e', 'd'], index=['b', 'a'])
+        res3 = df.reindex(labels=['b', 'a'], axis=0).reindex(labels=['e', 'd'],
+                                                             axis=1)
+        for res in [res2, res3]:
+            tm.assert_frame_equal(res1, res)
+
     def test_align(self):
         af, bf = self.frame.align(self.frame)
         assert af._data is not self.frame._data
@@ -974,21 +1048,21 @@ def test_reindex_with_nans(self):
     def test_reindex_multi(self):
         df = DataFrame(np.random.randn(3, 3))
 
-        result = df.reindex(lrange(4), lrange(4))
+        result = df.reindex(index=lrange(4), columns=lrange(4))
         expected = df.reindex(lrange(4)).reindex(columns=lrange(4))
 
         assert_frame_equal(result, expected)
 
         df = DataFrame(np.random.randint(0, 10, (3, 3)))
 
-        result = df.reindex(lrange(4), lrange(4))
+        result = df.reindex(index=lrange(4), columns=lrange(4))
         expected = df.reindex(lrange(4)).reindex(columns=lrange(4))
 
         assert_frame_equal(result, expected)
 
         df = DataFrame(np.random.randint(0, 10, (3, 3)))
 
-        result = df.reindex(lrange(2), lrange(2))
+        result = df.reindex(index=lrange(2), columns=lrange(2))
         expected = df.reindex(lrange(2)).reindex(columns=lrange(2))
 
         assert_frame_equal(result, expected)
