diff --git a/doc/source/indexing.rst b/doc/source/indexing.rst index f988fb7cd6806..322e147b6d8de 100644 --- a/doc/source/indexing.rst +++ b/doc/source/indexing.rst @@ -78,8 +78,9 @@ of multi-axis indexing. *label* of the index. This use is **not** an integer position along the index) - A list or array of labels ``['a', 'b', 'c']`` - - A slice object with labels ``'a':'f'``, (note that contrary to usual python - slices, **both** the start and the stop are included!) + - A slice object with labels ``'a':'f'`` (note that contrary to usual python + slices, **both** the start and the stop are included, when present in the + index!) - A boolean array - A ``callable`` function with one argument (the calling Series, DataFrame or Panel) and that returns valid output for indexing (one of the above) @@ -330,13 +331,15 @@ Selection By Label dfl.loc['20130102':'20130104'] pandas provides a suite of methods in order to have **purely label based indexing**. This is a strict inclusion based protocol. -**At least 1** of the labels for which you ask, must be in the index or a ``KeyError`` will be raised! When slicing, the start bound is *included*, **AND** the stop bound is *included*. Integers are valid labels, but they refer to the label **and not the position**. +**At least 1** of the labels for which you ask, must be in the index or a ``KeyError`` will be raised! When slicing, both the start bound **AND** the stop bound are *included*, if present in the index. Integers are valid labels, but they refer to the label **and not the position**. The ``.loc`` attribute is the primary access method. The following are valid inputs: - A single label, e.g. ``5`` or ``'a'``, (note that ``5`` is interpreted as a *label* of the index. This use is **not** an integer position along the index) - A list or array of labels ``['a', 'b', 'c']`` -- A slice object with labels ``'a':'f'`` (note that contrary to usual python slices, **both** the start and the stop are included!) +- A slice object with labels ``'a':'f'`` (note that contrary to usual python + slices, **both** the start and the stop are included, when present in the + index!) - A boolean array - A ``callable``, see :ref:`Selection By Callable ` @@ -370,6 +373,15 @@ Accessing via label slices df1.loc['d':, 'A':'C'] +.. warning:: + + If both the start and the stop labels are present in the index, then + elements *located* between the two (including them) are returned. If at + least one of the two is absent but the index is sorted (and can be compared + against start and stop labels), then slicing will still work, by selecting + labels which *rank* between the two. However, if at least one of the two is + absent *and* the index is not sorted, a ``TypeError`` will be raised. + For getting a cross section using a label (equiv to ``df.xs('a')``) .. ipython:: python