Skip to content

Commit

Permalink
DOC: behavior when slicing with missing bounds
Browse files Browse the repository at this point in the history
closes #16917
  • Loading branch information
toobaz committed Jul 15, 2017
1 parent a587d56 commit 71c5b23
Showing 1 changed file with 16 additions and 4 deletions.
20 changes: 16 additions & 4 deletions doc/source/indexing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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 <indexing.callable>`

Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 71c5b23

Please sign in to comment.