DOC: update the DataFrame.loc[] docstring

pandas/core/indexing.py

@@ -1413,7 +1413,8 @@ def _get_slice_axis(self, slice_obj, axis=None):
 
 
 class _LocIndexer(_LocationIndexer):
-    """Purely label-location based indexer for selection by label.
+    """
+    Access a group of rows and columns by label(s) or a boolean array.
 
     ``.loc[]`` is primarily label based, but may also be used with a
     boolean array.
@@ -1426,14 +1427,220 @@ class _LocIndexer(_LocationIndexer):
     - A list or array of labels, e.g. ``['a', 'b', 'c']``.
     - A slice object with labels, e.g. ``'a':'f'`` (note that contrary
       to usual python slices, **both** the start and the stop are included!).
-    - A boolean array.
+    - A boolean array of the same length as the axis being sliced,
+      e.g. ``[True, False, True]``.
     - A ``callable`` function with one argument (the calling Series, DataFrame
       or Panel) and that returns valid output for indexing (one of the above)
 
-    ``.loc`` will raise a ``KeyError`` when the items are not found.
-
     See more at :ref:`Selection by Label <indexing.label>`
 
+    See Also
+    --------
+    DateFrame.at
+        Access a single value for a row/column label pair
+    DateFrame.iloc
+        Access group of rows and columns by integer position(s)
+    Series.loc
+        Access group of values using labels
+
+    Examples
+    --------
+    >>> df = pd.DataFrame([[12, 2, 3], [0, 4, 1], [10, 20, 30]],
+    ...      index=['r0', 'r1', 'r2'], columns=['c0', 'c1', 'c2'])
+    >>> df
+        c0  c1  c2
+    r0  12   2   3
+    r1   0   4   1
+    r2  10  20  30
+
+    Single label. Note this returns a Series.
+
+    >>> df.loc['r1']
+    c0    0
+    c1    4
+    c2    1
+    Name: r1, dtype: int64
+
+    List with a single label. Note using ``[[]]`` returns a DataFrame.
+
+    >>> df.loc[['r1']]
+        c0  c1  c2
+    r1   0   4   1
+
+    Single label for row and column
+
+    >>> df.loc['r0', 'c1']
+    2
+
+    A list of labels
+
+    >>> df.loc[['r1', 'r2']]
+        c0  c1  c2
+    r1   0   4   1
+    r2  10  20  30
+
+    Slice with labels for row and single label for column. Note that
+    contrary to usual python slices, both the start and the stop are
+    included!
+
+    >>> df.loc['r0':'r1', 'c0']
+    r0    12
+    r1     0
+    Name: c0, dtype: int64
+
+    Boolean list with the same length as the row axis
+
+    >>> df.loc[[False, False, True]]
+        c0  c1  c2
+    r2  10  20  30
+
+    Callable that returns valid output for indexing
+
+    >>> df.loc[df['c1'] > 10]
+        c0  c1  c2
+    r2  10  20  30
+
+    Callable that returns valid output with column labels specified
+
+    >>> df.loc[df['c1'] > 10, ['c0', 'c2']]
+        c0  c2
+    r2  10  30
+
+    Set value for all items matching the list of labels
+
+    >>> df.loc[['r1', 'r2'], ['c1']] = 70
+    >>> df
+        c0  c1  c2
+    r0  12   2   3
+    r1   0  70   1
+    r2  10  70  30
+
+    Set value for an entire row
+
+    >>> df.loc['r0'] = 70
+    >>> df
+        c0  c1  c2
+    r0  70  70  70
+    r1   0  70   1
+    r2  10  70  30
+
+    Set value for an entire column
+
+    >>> df.loc[:, 'c0'] = 30
+    >>> df
+        c0  c1  c2
+    r0  30  70  70
+    r1  30  70   1
+    r2  30  70  30
+
+    Set value for rows matching callable condition
+
+    >>> df.loc[df['c2'] < 10] = 0
+    >>> df
+        c0  c1  c2
+    r0  30  70  70
+    r1   0   0   0
+    r2  30  70  30
+
+    Another example using integers for the index
+
+    >>> df = pd.DataFrame([[12, 2, 3], [0, 4, 1], [10, 20, 30]],
+    ...      index=[7, 8, 9], columns=['c0', 'c1', 'c2'])
+    >>> df
+        c0  c1  c2
+    7  12   2   3
+    8   0   4   1
+    9  10  20  30
+
+    Slice with integer labels for rows. Note that contrary to usual
+    python slices, both the start and the stop are included!
+
+    >>> df.loc[7:9]
+       c0  c1  c2
+    7  12   2   3
+    8   0   4   1
+    9  10  20  30
+
+    A number of examples using a DataFrame with a multi-index
+
+    >>> tuples = [('r0', 'bar'), ('r0', 'foo'), ('r1', 'bar'),
+    ... 	('r1', 'foo'), ('r2', 'bar'), ('r2', 'baz')]
+    >>> index = pd.MultiIndex.from_tuples(tuples)
+    >>> values = [[12,2,3], [0,4,1], [10,20,30],
+    ...         [1, 4, 1], [7, 1, 2], [16, 36, 40]]
+    >>> df = pd.DataFrame(values, columns=['c0', 'c1', 'c2'], index=index)
+    >>> df
+            c0  c1  c2
+    r0 bar  12   2   3
+       foo   0   4   1
+    r1 bar  10  20  30
+       foo   1   4   1
+    r2 bar   7   1   2
+       baz  16  36  40
+
+    Single label. Note this returns a DataFrame with a single index.
+
+    >>> df.loc['r0']
+         c0  c1  c2
+    bar  12   2   3
+    foo   0   4   1
+
+    Single index tuple. Note this returns a Series.
+
+    >>> df.loc[('r0', 'bar')]
+    c0    12
+    c1     2
+    c2     3
+    Name: (r0, bar), dtype: int64
+
+    Single label for row and column. Similar to passing in a tuple, this
+    returns a Series.
+
+    >>> df.loc['r0', 'foo']
+    c0    0
+    c1    4
+    c2    1
+    Name: (r0, foo), dtype: int64
+
+    Single tuple. Note using ``[[]]`` returns a DataFrame.
+
+    >>> df.loc[[('r0', 'bar')]]
+            c0  c1  c2
+    r0 bar  12   2   3
+
+    Single tuple for the index with a single label for the column
+
+    >>> df.loc[('r0', 'foo'), 'c1']
+    4
+
+    Boolean list
+
+    >>> df.loc[[True, False, True, False, True, True]]
+            c0  c1  c2
+    r0 bar  12   2   3
+    r1 bar  10  20  30
+    r2 bar   7   1   2
+       baz  16  36  40
+
+    Slice from index tuple to single label
+
+    >>> df.loc[('r0', 'foo'):'r1']
+            c0  c1  c2
+    r0 foo   0   4   1
+    r1 bar  10  20  30
+       foo   1   4   1
+
+    Slice from index tuple to index tuple
+
+    >>> df.loc[('r0', 'foo'):('r1', 'bar')]
+            c0  c1  c2
+    r0 foo   0   4   1
+    r1 bar  10  20  30
+
+    Raises
+    ------
+    KeyError:
+        when items are not found
     """
 
     _valid_types = ("labels (MUST BE IN THE INDEX), slices of labels (BOTH "