DOC: start some docs re: integer API changes, GH #627

Author: wesm

doc/source/groupby.rst

@@ -125,7 +125,7 @@ only verifies that you've passed a valid mapping.
    GroupBy operations (though can't be guaranteed to be the most
    efficient). You can get quite creative with the label mapping functions.
 
-.. _groupby.atributes:
+.. _groupby.attributes:
 
 GroupBy object attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -302,6 +302,8 @@ same result as the column names are stored in the resulting ``MultiIndex``:
 
    df.groupby(['A', 'B']).sum().reset_index()
 
+.. _groupby.aggregate.multifunc:
+
 Applying multiple functions at once
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/source/whatsnew/v0.7.0.txt

@@ -3,8 +3,55 @@
 v.0.7.0 (Not Yet Released)
 --------------------------
 
-API Changes
-~~~~~~~~~~~
+API Changes to integer indexing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One of the potentially riskiest API changes in 0.7.0, but also one of the most
+important, was a complete review of how **integer indexes** are handled with
+regard to label-based indexing. Here is an example:
+
+.. ipython:: python
+
+    s = Series(randn(10), index=range(0, 20, 2))
+    s
+    s[0]
+    s[2]
+    s[4]
+
+This is all exactly identical to the behavior before. However, if you ask for a
+key **not** contained in the Series, in versions 0.6.1 and prior, Series would
+*fall back* on a location-based lookup. This now raises a ``KeyError``:
+
+.. code-block:: ipython
+
+   In [2]: s[1]
+   KeyError: 1
+
+This change also has the same impact on DataFrame:
+
+.. code-block:: ipython
+
+   In [3]: df = DataFrame(randn(8, 4), index=range(0, 16, 2))
+
+   In [4]: df
+       0        1       2       3
+   0   0.88427  0.3363 -0.1787  0.03162
+   2   0.14451 -0.1415  0.2504  0.58374
+   4  -1.44779 -0.9186 -1.4996  0.27163
+   6  -0.26598 -2.4184 -0.2658  0.11503
+   8  -0.58776  0.3144 -0.8566  0.61941
+   10  0.10940 -0.7175 -1.0108  0.47990
+   12 -1.16919 -0.3087 -0.6049 -0.43544
+   14 -0.07337  0.3410  0.0424 -0.16037
+
+   In [5]: df.ix[3]
+   KeyError: 3
+
+API refinements regarding label-based slicing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Other relevant API Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 New features
 ~~~~~~~~~~~~
@@ -75,7 +122,7 @@ New features
 - :ref:`Added <io.formatting>` ``justify`` argument to ``DataFrame.to_string``
   to allow different alignment of column headers
 
-- :ref:`Add <groupby.atributes>` ``sort`` option to GroupBy to allow disabling
+- :ref:`Add <groupby.attributes>` ``sort`` option to GroupBy to allow disabling
   sorting of the group keys for potential speedups (GH595_)
 
 - :ref:`Can <basics.dataframe.from_series>` pass MaskedArray to Series