DOC: Clarified documentation for MultiIndexes

Add examples and rewrite an awkwardly-written bit

Cross-reference MultiIndex constructors

Author: Felix Lawrence

doc/source/indexing.rst

@@ -1638,6 +1638,10 @@ completely analogous way to selecting a column in a regular DataFrame:
    df['bar']['one']
    s['qux']
 
+See :ref:`Cross-section with hierarchical index <indexing.xs>` for how to select
+on a deeper level.
+
+
 Data alignment and using ``reindex``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1674,11 +1678,17 @@ following works as you would expect:
    df.ix['bar']
    df.ix['bar', 'two']
 
-"Partial" slicing also works quite nicely:
+"Partial" slicing also works quite nicely for the topmost level:
 
 .. ipython:: python
 
    df.ix['baz':'foo']
+
+But lower levels cannot be sliced in this way, because the MultiIndex uses
+its multiple index dimensions to slice along one dimension of your object:
+
+.. ipython:: python
+
    df.ix[('baz', 'two'):('qux', 'one')]
    df.ix[('baz', 'two'):'foo']
 

pandas/core/index.py

@@ -2472,14 +2472,25 @@ def from_arrays(cls, arrays, sortorder=None, names=None):
 
         Parameters
         ----------
-        arrays : list / sequence
+        arrays : list / sequence of array-likes
+            Each array-like gives one level's value for each data point.
+            len(arrays) is the number of levels.
         sortorder : int or None
             Level of sortedness (must be lexicographically sorted by that
             level)
 
         Returns
         -------
         index : MultiIndex
+
+        Examples
+        --------
+        >>> arrays = [[1, 1, 2, 2], ['red', 'blue', 'red', 'blue']]
+        >>> MultiIndex.from_arrays(arrays, names=('number', 'color'))
+
+        See Also
+        --------
+        MultiIndex.from_tuples : Convert list of tuples to MultiIndex
         """
         from pandas.core.categorical import Categorical
 
@@ -2504,14 +2515,25 @@ def from_tuples(cls, tuples, sortorder=None, names=None):
 
         Parameters
         ----------
-        tuples : array-like
+        tuples : list / sequence of tuple-likes
+            Each tuple is the index of one row/column.
         sortorder : int or None
             Level of sortedness (must be lexicographically sorted by that
             level)
 
         Returns
         -------
         index : MultiIndex
+
+        Examples
+        --------
+        >>> tuples = [(1, u'red'), (1, u'blue'),
+                      (2, u'red'), (2, u'blue')]
+        >>> MultiIndex.from_tuples(tuples, names=('number', 'color'))
+
+        See Also
+        --------
+        MultiIndex.from_arrays : Convert list of arrays to MultiIndex
         """
         if len(tuples) == 0:
             # I think this is right? Not quite sure...