DEPR: deprecate irow,icol,iget_value,iget in Series/DataFrame, #10711

Author: jreback

doc/source/api.rst

@@ -1558,7 +1558,6 @@ application to columns of a specific data type.
    DataFrameGroupBy.hist
    DataFrameGroupBy.idxmax
    DataFrameGroupBy.idxmin
-   DataFrameGroupBy.irow
    DataFrameGroupBy.mad
    DataFrameGroupBy.pct_change
    DataFrameGroupBy.plot

doc/source/indexing.rst

@@ -121,18 +121,6 @@ the specification are assumed to be ``:``. (e.g. ``p.loc['a']`` is equiv to
     DataFrame; ``df.loc[row_indexer,column_indexer]``
     Panel; ``p.loc[item_indexer,major_indexer,minor_indexer]``
 
-Deprecations
-------------
-
-Beginning with version 0.11.0, it's recommended that you transition away from
-the following methods as they *may* be deprecated in future versions.
-
-  - ``irow``
-  - ``icol``
-  - ``iget_value``
-
-See the section :ref:`Selection by Position <indexing.integer>` for substitutes.
-
 .. _indexing.basics:
 
 Basics
@@ -432,20 +420,14 @@ Select via integer list
 
    df1.iloc[[1,3,5],[1,3]]
 
-For slicing rows explicitly (equiv to deprecated ``df.irow(slice(1,3))``).
-
 .. ipython:: python
 
    df1.iloc[1:3,:]
 
-For slicing columns explicitly (equiv to deprecated ``df.icol(slice(1,3))``).
-
 .. ipython:: python
 
    df1.iloc[:,1:3]
 
-For getting a scalar via integer position (equiv to deprecated ``df.get_value(1,1)``)
-
 .. ipython:: python
 
    # this is also equivalent to ``df1.iat[1,1]``

doc/source/whatsnew/v0.17.0.txt

@@ -434,6 +434,26 @@ Other API Changes
 Deprecations
 ^^^^^^^^^^^^
 
+.. note:: These indexing function have been deprecated in the documentation since 0.11.0.
+
+- For ``Series`` the following indexing functions are deprecated (:issue:`10177`).
+  =====================     ==============================================================
+  Deprecated Function       Replacement
+  =====================     ==============================================================
+  ``.irow(i)``              ``.iloc[i]`` or ``.iat[i]``
+  ``.iget(i)``              ``.iloc[i]`` or ``.iat[i]``
+  ``.iget_value(i)``        ``.iloc[i]`` or ``.iat[i]``
+  =====================     ==============================================================
+
+- For ``DataFrame`` the following indexing functions are deprecated (:issue:`10177`).
+  =====================     ==============================================================
+  Deprecated Function       Replacement
+  =====================     ==============================================================
+  ``.irow(i)``              ``.iloc[i]``
+  ``.iget_value(i, j)``     ``.iloc[i, j]`` or ``.iat[i, j]``
+  ``.icol(j)``              ``.iloc[:, j]``
+  =====================     ==============================================================
+
 .. _whatsnew_0170.prior_deprecations:
 
 Removal of prior version deprecations/changes

pandas/core/frame.py

@@ -552,7 +552,7 @@ def iteritems(self):
                 yield k, self._get_item_cache(k)
         else:
             for i, k in enumerate(self.columns):
-                yield k, self.icol(i)
+                yield k, self._ixs(i,axis=1)
 
     def iterrows(self):
         """
@@ -1697,9 +1697,20 @@ def set_value(self, index, col, value, takeable=False):
             return self
 
     def irow(self, i, copy=False):
+        """
+        DEPRECATED. Use ``.iloc[i]`` instead
+        """
+
+        warnings.warn("irow(i) is deprecated. Please use .iloc[i]",
+                      FutureWarning, stacklevel=2)
         return self._ixs(i, axis=0)
 
     def icol(self, i):
+        """
+        DEPRECATED. Use ``.iloc[:, i]`` instead
+        """
+        warnings.warn("icol(i) is deprecated. Please use .iloc[:,i]",
+                      FutureWarning, stacklevel=2)
         return self._ixs(i, axis=1)
 
     def _ixs(self, i, axis=0):
@@ -1773,6 +1784,11 @@ def _ixs(self, i, axis=0):
                 return result
 
     def iget_value(self, i, j):
+        """
+        DEPRECATED. Use ``.iat[i, j]`` instead
+        """
+        warnings.warn("iget_value(i, j) is deprecated. Please use .iat[i, j]",
+                      FutureWarning, stacklevel=2)
         return self.iat[i, j]
 
     def __getitem__(self, key):
@@ -3769,7 +3785,7 @@ def _apply_standard(self, func, axis, ignore_failures=False, reduce=True):
 
         dtype = object if self._is_mixed_type else None
         if axis == 0:
-            series_gen = (self.icol(i) for i in range(len(self.columns)))
+            series_gen = (self._ixs(i,axis=1) for i in range(len(self.columns)))
             res_index = self.columns
             res_columns = self.index
         elif axis == 1:
@@ -4900,11 +4916,11 @@ def _to_arrays(data, columns, coerce_float=False, dtype=None):
     """
     if isinstance(data, DataFrame):
         if columns is not None:
-            arrays = [data.icol(i).values for i, col in enumerate(data.columns)
+            arrays = [data._ixs(i,axis=1).values for i, col in enumerate(data.columns)
                       if col in columns]
         else:
             columns = data.columns
-            arrays = [data.icol(i).values for i in range(len(columns))]
+            arrays = [data._ixs(i,axis=1).values for i in range(len(columns))]
 
         return arrays, columns
 

pandas/core/groupby.py

@@ -3,6 +3,7 @@
 import numpy as np
 import datetime
 import collections
+import warnings
 
 from pandas.compat import(
     zip, builtins, range, long, lzip,
@@ -71,7 +72,7 @@
     'fillna',
     'mad',
     'any', 'all',
-    'irow', 'take',
+    'take',
     'idxmax', 'idxmin',
     'shift', 'tshift',
     'ffill', 'bfill',
@@ -170,7 +171,7 @@ class Grouper(object):
     freq : string / frequency object, defaults to None
         This will groupby the specified frequency if the target selection (via key or level) is
         a datetime-like object. For full specification of available frequencies, please see
-        `here <http://pandas.pydata.org/pandas-docs/stable/timeseries.html>`_. 
+        `here <http://pandas.pydata.org/pandas-docs/stable/timeseries.html>`_.
     axis : number/name of the axis, defaults to 0
     sort : boolean, default to False
         whether to sort the resulting labels
@@ -188,7 +189,7 @@ class Grouper(object):
 
     Examples
     --------
-    
+
     Syntactic sugar for ``df.groupby('A')``
 
     >>> df.groupby(Grouper(key='A'))
@@ -198,9 +199,9 @@ class Grouper(object):
     >>> df.groupby(Grouper(key='date', freq='60s'))
 
     Specify a resample operation on the level 'date' on the columns axis
-    with a frequency of 60s 
+    with a frequency of 60s
 
-    >>> df.groupby(Grouper(level='date', freq='60s', axis=1)) 
+    >>> df.groupby(Grouper(level='date', freq='60s', axis=1))
     """
 
     def __new__(cls, *args, **kwargs):
@@ -711,6 +712,16 @@ def _iterate_slices(self):
     def transform(self, func, *args, **kwargs):
         raise AbstractMethodError(self)
 
+    def irow(self, i):
+        """
+        DEPRECATED. Use ``.nth(i)`` instead
+        """
+
+        # 10177
+        warnings.warn("irow(i) is deprecated. Please use .nth(i)",
+                      FutureWarning, stacklevel=2)
+        return self.nth(i)
+
     def mean(self):
         """
         Compute mean of groups, excluding missing values

pandas/core/series.py

@@ -781,9 +781,30 @@ def reshape(self, *args, **kwargs):
 
         return self.values.reshape(shape, **kwargs)
 
-    iget_value = _ixs
-    iget = _ixs
-    irow = _ixs
+    def iget_value(self, i, axis=0):
+        """
+        DEPRECATED. Use ``.iloc[i]`` or ``.iat[i]`` instead
+        """
+        warnings.warn("iget_value(i) is deprecated. Please use .iloc[i] or .iat[i]",
+                      FutureWarning, stacklevel=2)
+        return self._ixs(i)
+
+    def iget(self, i, axis=0):
+        """
+        DEPRECATED. Use ``.iloc[i]`` or ``.iat[i]`` instead
+        """
+
+        warnings.warn("iget(i) is deprecated. Please use .iloc[i] or .iat[i]",
+                      FutureWarning, stacklevel=2)
+        return self._ixs(i)
+
+    def irow(self, i, axis=0):
+        """
+        DEPRECATED. Use ``.iloc[i]`` or ``.iat[i]`` instead
+        """
+        warnings.warn("irow(i) is deprecated. Please use .iloc[i] or iat[i]",
+                      FutureWarning, stacklevel=2)
+        return self._ixs(i)
 
     def get_value(self, label, takeable=False):
         """
@@ -2323,7 +2344,7 @@ def from_csv(cls, path, sep=',', parse_dates=True, header=None,
                                 sep=sep, parse_dates=parse_dates,
                                 encoding=encoding,
                                 infer_datetime_format=infer_datetime_format)
-        result = df.icol(0)
+        result = df.iloc[:,0]
         if header is None:
             result.index.name = result.name = None
 

pandas/sparse/tests/test_sparse.py

@@ -1240,16 +1240,18 @@ def test_getitem(self):
         self.assertRaises(Exception, sdf.__getitem__, ['a', 'd'])
 
     def test_icol(self):
+        # 10711 deprecated
+
         # 2227
-        result = self.frame.icol(0)
+        result = self.frame.iloc[:, 0]
         self.assertTrue(isinstance(result, SparseSeries))
         assert_sp_series_equal(result, self.frame['A'])
 
         # preserve sparse index type. #2251
         data = {'A': [0, 1]}
         iframe = SparseDataFrame(data, default_kind='integer')
         self.assertEqual(type(iframe['A'].sp_index),
-                         type(iframe.icol(0).sp_index))
+                         type(iframe.iloc[:, 0].sp_index))
 
     def test_set_value(self):
 

pandas/tests/test_categorical.py

@@ -2203,27 +2203,27 @@ def test_slicing_and_getting_ops(self):
         self.assertEqual(res_val, exp_val)
 
         # i : int, slice, or sequence of integers
-        res_row = df.irow(2)
+        res_row = df.iloc[2]
         tm.assert_series_equal(res_row, exp_row)
         tm.assertIsInstance(res_row["cats"], compat.string_types)
 
-        res_df = df.irow(slice(2,4))
+        res_df = df.iloc[slice(2,4)]
         tm.assert_frame_equal(res_df, exp_df)
         self.assertTrue(com.is_categorical_dtype(res_df["cats"]))
 
-        res_df = df.irow([2,3])
+        res_df = df.iloc[[2,3]]
         tm.assert_frame_equal(res_df, exp_df)
         self.assertTrue(com.is_categorical_dtype(res_df["cats"]))
 
-        res_col = df.icol(0)
+        res_col = df.iloc[:,0]
         tm.assert_series_equal(res_col, exp_col)
         self.assertTrue(com.is_categorical_dtype(res_col))
 
-        res_df = df.icol(slice(0,2))
+        res_df = df.iloc[:,slice(0,2)]
         tm.assert_frame_equal(res_df, df)
         self.assertTrue(com.is_categorical_dtype(res_df["cats"]))
 
-        res_df = df.icol([0,1])
+        res_df = df.iloc[:,[0,1]]
         tm.assert_frame_equal(res_df, df)
         self.assertTrue(com.is_categorical_dtype(res_df["cats"]))
 

pandas/tests/test_expressions.py

@@ -97,7 +97,7 @@ def run_arithmetic_test(self, df, other, assert_func, check_dtype=False,
     def test_integer_arithmetic(self):
         self.run_arithmetic_test(self.integer, self.integer,
                                  assert_frame_equal)
-        self.run_arithmetic_test(self.integer.icol(0), self.integer.icol(0),
+        self.run_arithmetic_test(self.integer.iloc[:,0], self.integer.iloc[:, 0],
                                  assert_series_equal, check_dtype=True)
 
     @nose.tools.nottest
@@ -182,7 +182,7 @@ def test_integer_arithmetic_frame(self):
         self.run_frame(self.integer, self.integer)
 
     def test_integer_arithmetic_series(self):
-        self.run_series(self.integer.icol(0), self.integer.icol(0))
+        self.run_series(self.integer.iloc[:, 0], self.integer.iloc[:, 0])
 
     @slow
     def test_integer_panel(self):
@@ -192,7 +192,7 @@ def test_float_arithemtic_frame(self):
         self.run_frame(self.frame2, self.frame2)
 
     def test_float_arithmetic_series(self):
-        self.run_series(self.frame2.icol(0), self.frame2.icol(0))
+        self.run_series(self.frame2.iloc[:, 0], self.frame2.iloc[:, 0])
 
     @slow
     def test_float_panel(self):
@@ -220,7 +220,7 @@ def test_mixed_panel(self):
 
     def test_float_arithemtic(self):
         self.run_arithmetic_test(self.frame, self.frame, assert_frame_equal)
-        self.run_arithmetic_test(self.frame.icol(0), self.frame.icol(0),
+        self.run_arithmetic_test(self.frame.iloc[:, 0], self.frame.iloc[:, 0],
                                  assert_series_equal, check_dtype=True)
 
     def test_mixed_arithmetic(self):
@@ -232,7 +232,7 @@ def test_mixed_arithmetic(self):
     def test_integer_with_zeros(self):
         self.integer *= np.random.randint(0, 2, size=np.shape(self.integer))
         self.run_arithmetic_test(self.integer, self.integer, assert_frame_equal)
-        self.run_arithmetic_test(self.integer.icol(0), self.integer.icol(0),
+        self.run_arithmetic_test(self.integer.iloc[:, 0], self.integer.iloc[:, 0],
                                  assert_series_equal)
 
     def test_invalid(self):