From df427e8b12dac99d88312192f942f208e054ba84 Mon Sep 17 00:00:00 2001
From: Wouter Overmeire <lodagro@gmail.com>
Date: Thu, 26 Jul 2012 21:12:50 +0200
Subject: [PATCH] DOC: update DataFrame.xs docstring and add examples

---
 pandas/core/frame.py | 56 +++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 53 insertions(+), 3 deletions(-)

diff --git a/pandas/core/frame.py b/pandas/core/frame.py
index dc5c6c0f67307..4fc9205c25860 100644
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -1831,8 +1831,8 @@ def _series(self):
 
     def xs(self, key, axis=0, level=None, copy=True):
         """
-        Returns a cross-section (row or column) from the DataFrame as a Series
-        object. Defaults to returning a row (axis 0)
+        Returns a cross-section (row(s) or column(s)) from the DataFrame.
+        Defaults to cross-section on the rows (axis=0).
 
         Parameters
         ----------
@@ -1840,12 +1840,62 @@ def xs(self, key, axis=0, level=None, copy=True):
             Some label contained in the index, or partially in a MultiIndex
         axis : int, default 0
             Axis to retrieve cross-section on
+        level : object, defaults to first n levels (n=1 or len(key))
+            In case of a key partially contained in a MultiIndex, indicate
+            which levels are used. Levels can be referred by label or position.
         copy : boolean, default True
             Whether to make a copy of the data
 
+        Examples
+        --------
+        >>> df
+           A  B  C
+        a  4  5  2
+        b  4  0  9
+        c  9  7  3
+        >>> df.xs('a')
+        A    4
+        B    5
+        C    2
+        Name: a
+        >>> df.xs('C', axis=1)
+        a    2
+        b    9
+        c    3
+        Name: C
+        >>> s = df.xs('a', copy=False)
+        >>> s['A'] = 100
+        >>> df
+             A  B  C
+        a  100  5  2
+        b    4  0  9
+        c    9  7  3
+
+
+        >>> df
+                            A  B  C  D
+        first second third
+        bar   one    1      4  1  8  9
+              two    1      7  5  5  0
+        baz   one    1      6  6  8  0
+              three  2      5  3  5  3
+        >>> df.xs(('baz', 'three'))
+               A  B  C  D
+        third
+        2      5  3  5  3
+        >>> df.xs('one', level=1)
+                     A  B  C  D
+        first third
+        bar   1      4  1  8  9
+        baz   1      6  6  8  0
+        >>> df.xs(('baz', 2), level=[0, 'third'])
+                A  B  C  D
+        second
+        three   5  3  5  3
+
         Returns
         -------
-        xs : Series
+        xs : Series or DataFrame
         """
         labels = self._get_axis(axis)
         if level is not None: