DOC: starting on pivot docs. some indexing additions given new functi…

…onality

doc/source/indexing.rst

@@ -473,6 +473,14 @@ which will lexicographically sort an axis with a ``MultiIndex``:
    s.sortlevel(0)
    s.sortlevel(1)
 
+Some indexing will work even if the data are not sorted, but will be rather
+inefficient and will also return a copy of the data rather than a view:
+
+.. ipython:: python
+
+   s['qux']
+   s.sortlevel(1)['qux']
+
 On higher dimensional objects, you can sort any of the other axes by level if
 they have a MultiIndex:
 
@@ -501,7 +509,7 @@ However:
 ::
 
    >>> s.ix[('a', 'b'):('b', 'a')]
-   Exception: MultiIndex lexsort depth 1, key was 2 long
+   Exception: MultiIndex lexsort depth 1, key was length 2
 
 Some gory internal details
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/source/reshaping.rst

@@ -7,17 +7,88 @@
    import numpy as np
    np.random.seed(123456)
    from pandas import *
+   import pandas.util.testing as tm
    randn = np.random.randn
    np.set_printoptions(precision=4, suppress=True)
 
 ***************************
 Pivoting and reshaping data
 ***************************
 
-"Pivoting" DataFrame objects
-----------------------------
+Reshaping by pivoting DataFrame objects
+---------------------------------------
 
+.. ipython::
+   :suppress:
+
+   In [1]: import pandas.util.testing as tm; tm.N = 3
+
+   In [2]: def unpivot(frame):
+      ...:         N, K = frame.shape
+      ...:         data = {'value' : frame.values.ravel('F'),
+      ...:                 'variable' : np.asarray(frame.columns).repeat(N),
+      ...:                 'date' : np.tile(np.asarray(frame.index), K)}
+      ...:         columns = ['date', 'variable', 'value']
+      ...:         return DataFrame(data, columns=columns)
+      ...:
+
+   In [3]: df = unpivot(tm.makeTimeDataFrame())
+
+Data is often stored in CSV files or databases in so-called "stacked" or
+"record" format:
+
+.. ipython:: python
+
+   df
+
+
+For the curious here is how the above DataFrame was created:
+
+.. code-block:: python
+
+   import pandas.util.testing as tm; tm.N = 3
+   def unpivot(frame):
+       N, K = frame.shape
+       data = {'value' : frame.values.ravel('F'),
+               'variable' : np.asarray(frame.columns).repeat(N),
+               'date' : np.tile(np.asarray(frame.index), K)}
+       return DataFrame(data, columns=['date', 'variable', 'value'])
+   df = unpivot(tm.makeTimeDataFrame())
+
+To select out everything for variable ``A`` we could do:
+
+.. ipython:: python
+
+   df[df['variable'] == 'A']
+
+But if we wished to do time series operations between variables, this will
+hardly do at all. This is really just a representation of a DataFrame whose
+``columns`` are formed from the unique ``variable`` values and ``index`` from
+the ``date`` values. To reshape the data into this form, use the ``pivot``
+function:
+
+.. ipython:: python
+
+   df.pivot(index='date', columns='variable', values='value')
+
+If the ``values`` argument is omitted, the resulting "pivoted" DataFrame will
+have :ref:`hierarchical columns <indexing.hierarchical>` with the top level
+being the set of value columns:
+
+.. ipython:: python
+
+   df['value2'] = df['value'] * 2
+   pivoted = df.pivot('date', 'variable')
+   pivoted
+
+You of course can then select subsets from the pivoted DataFrame:
+
+.. ipython:: python
+
+   pivoted['value2']
 
+Note that this returns a view on the underlying data in the case where the data
+are homogeneously-typed.
 
-Stacking and unstacking data
-----------------------------
+Reshaping by stacking and unstacking
+------------------------------------

pandas/core/index.py

@@ -917,7 +917,7 @@ def slice_locs(self, start=None, end=None):
 
     def _partial_tup_index(self, tup, side='left'):
         if len(tup) > self.lexsort_depth:
-            raise Exception('MultiIndex lexsort depth %d, key was %d long' %
+            raise Exception('MultiIndex lexsort depth %d, key was length %d' %
                             (self.lexsort_depth, len(tup)))
 
         n = len(tup)