From f803199ddf8bfa9e6f40fe65cc40bd3ec4912e4c Mon Sep 17 00:00:00 2001
From: Felix Lawrence <felix.lawrence@nicta.com.au>
Date: Thu, 16 Jan 2014 15:27:02 +1100
Subject: [PATCH] DOC: Clarified documentation for MultiIndexes

Add examples and rewrite an awkwardly-written bit

Cross-reference MultiIndex constructors
---
 doc/source/indexing.rst | 12 +++++++++++-
 pandas/core/index.py    | 26 ++++++++++++++++++++++++--
 2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/doc/source/indexing.rst b/doc/source/indexing.rst
index 8813e9d838d22..9c3412d35d286 100644
--- a/doc/source/indexing.rst
+++ b/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']
 
diff --git a/pandas/core/index.py b/pandas/core/index.py
index ed964e76dd470..86344b1cc2161 100644
--- a/pandas/core/index.py
+++ b/pandas/core/index.py
@@ -2472,7 +2472,9 @@ 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)
@@ -2480,6 +2482,15 @@ def from_arrays(cls, arrays, sortorder=None, names=None):
         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,7 +2515,8 @@ 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)
@@ -2512,6 +2524,16 @@ def from_tuples(cls, tuples, sortorder=None, names=None):
         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...