DOC: add addtl docs for FloatIndexing changes in 0.18.0

closes #12322

Author: Jeff Reback <[email protected]>

Closes #12330 from jreback/deprecate_docs and squashes the following commits:

5a9585c [Jeff Reback] DOC: add addtl docs for FloatIndexing changes in 0.18.0

Author: jreback

doc/source/advanced.rst

@@ -795,12 +795,23 @@ In non-float indexes, slicing using floats will raise a ``TypeError``
    In [1]: pd.Series(range(5))[3.5:4.5]
    TypeError: the slice start [3.5] is not a proper indexer for this index type (Int64Index)
 
-Using a scalar float indexer will be deprecated in a future version, but is allowed for now.
+.. warning::
 
-.. code-block:: python
+   Using a scalar float indexer has been removed in 0.18.0, so the following will raise a ``TypeError``
+
+   .. code-block:: python
+
+      In [3]: pd.Series(range(5))[3.0]
+      TypeError: cannot do label indexing on <class 'pandas.indexes.range.RangeIndex'> with these indexers [3.0] of <type 'float'>
+
+   Further the treatment of ``.ix`` with a float indexer on a non-float index, will be label based, and thus coerce the index.
+
+   .. ipython:: python
 
-   In [3]: pd.Series(range(5))[3.0]
-   Out[3]: 3
+      s2 = pd.Series([1, 2, 3], index=list('abc'))
+      s2
+      s2.ix[1.0] = 10
+      s2
 
 Here is a typical use-case for using this type of indexing. Imagine that you have a somewhat
 irregular timedelta-like indexing scheme, but the data is recorded as floats. This could for

doc/source/whatsnew/v0.18.0.txt

@@ -704,8 +704,8 @@ performed with the ``Resampler`` objects with :meth:`~Resampler.backfill`,
 
 .. ipython:: python
 
-   s = Series(np.arange(5,dtype='int64'),
-              index=date_range('2010-01-01', periods=5, freq='Q'))
+   s = pd.Series(np.arange(5,dtype='int64'),
+                 index=date_range('2010-01-01', periods=5, freq='Q'))
    s
 
 Previously
@@ -838,7 +838,7 @@ Deprecations
 
   .. code-block:: python
 
-     In [1]: s = Series(range(3))
+     In [1]: s = pd.Series(range(3))
 
      In [2]: pd.rolling_mean(s,window=2,min_periods=1)
              FutureWarning: pd.rolling_mean is deprecated for Series and
@@ -884,11 +884,17 @@ Removal of deprecated float indexers
 In :issue:`4892` indexing with floating point numbers on a non-``Float64Index`` was deprecated (in version 0.14.0).
 In 0.18.0, this deprecation warning is removed and these will now raise a ``TypeError``. (:issue:`12165`)
 
+.. ipython:: python
+
+   s = pd.Series([1,2,3])
+   s
+   s2 = pd.Series([1, 2, 3], index=list('abc'))
+   s2
+
 Previous Behavior:
 
 .. code-block:: python
 
-   In [1]: s = Series([1,2,3])
    In [2]: s[1.0]
    FutureWarning: scalar indexers for index type Int64Index should be integers and not floating point
    Out[2]: 2
@@ -901,24 +907,46 @@ Previous Behavior:
    FutureWarning: scalar indexers for index type Int64Index should be integers and not floating point
    Out[4]: 2
 
+   # .ix would coerce 1.0 to the positional 1, and index
+   In [5]: s2.ix[1.0] = 10
+   FutureWarning: scalar indexers for index type Index should be integers and not floating point
+
+   In [6]: s2
+   Out[6]:
+   a     1
+   b    10
+   c     3
+   dtype: int64
+
 New Behavior:
 
 .. code-block:: python
 
-   In [4]: s[1.0]
+   In [2]: s[1.0]
    TypeError: cannot do label indexing on <class 'pandas.indexes.range.RangeIndex'> with these indexers [1.0] of <type 'float'>
 
-   In [4]: s.iloc[1.0]
+   In [3]: s.iloc[1.0]
    TypeError: cannot do label indexing on <class 'pandas.indexes.range.RangeIndex'> with these indexers [1.0] of <type 'float'>
 
    In [4]: s.loc[1.0]
    TypeError: cannot do label indexing on <class 'pandas.indexes.range.RangeIndex'> with these indexers [1.0] of <type 'float'>
 
+   # .ix will now cause this to be a label lookup and coerce to and Index
+   In [5]: s2.ix[1.0] = 10
+
+   In [6]: s2
+   Out[3]:
+   a       1
+   b       2
+   c       3
+   1.0    10
+   dtype: int64
+
 Float indexing on a ``Float64Index`` is unchanged.
 
 .. ipython:: python
 
-   s = Series([1,2,3],index=np.arange(3.))
+   s = pd.Series([1,2,3],index=np.arange(3.))
    s[1.0]
    s[1.0:2.5]
 
@@ -945,7 +973,7 @@ Performance Improvements
 - Improved huge ``DatetimeIndex``, ``PeriodIndex`` and ``TimedeltaIndex``'s ops performance including ``NaT`` (:issue:`10277`)
 - Improved performance of ``pandas.concat`` (:issue:`11958`)
 - Improved performance of ``StataReader`` (:issue:`11591`)
-- Improved performance in construction of ``Categoricals`` with Series of datetimes containing ``NaT`` (:issue:`12077`)
+- Improved performance in construction of ``Categoricals`` with ``Series`` of datetimes containing ``NaT`` (:issue:`12077`)
 
 
 - Improved performance of ISO 8601 date parsing for dates without separators (:issue:`11899`), leading zeros (:issue:`11871`) and with whitespace preceding the time zone (:issue:`9714`)

pandas/indexes/base.py

@@ -974,7 +974,7 @@ def _convert_scalar_indexer(self, key, kind=None):
         if kind == 'iloc':
             if is_integer(key):
                 return key
-            return self._invalid_indexer('label', key)
+            return self._invalid_indexer('positional', key)
         else:
 
             if len(self):

pandas/tests/test_indexing.py

@@ -5406,6 +5406,23 @@ def test_index_type_coercion(self):
             s2['0'] = 0
             self.assertTrue(s2.index.is_object())
 
+    def test_invalid_scalar_float_indexers_error(self):
+
+        for index in [tm.makeStringIndex, tm.makeUnicodeIndex,
+                      tm.makeCategoricalIndex,
+                      tm.makeDateIndex, tm.makeTimedeltaIndex,
+                      tm.makePeriodIndex]:
+
+            i = index(5)
+
+            s = Series(np.arange(len(i)), index=i)
+
+            def f():
+                s.iloc[3.0]
+            self.assertRaisesRegexp(TypeError,
+                                    'cannot do positional indexing',
+                                    f)
+
     def test_invalid_scalar_float_indexers(self):
 
         # GH 4892