Skip to content

DOC: clarify loc slice step behavior with example closes #63311 #63346

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
PR-HARIHARAN wants to merge 2 commits into
base: main
Choose a base branch
from
+30 −0
Open

DOC: clarify loc slice step behavior with example closes #63311 #63346

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8a4d720
DOC: clarify loc slice step behavior with example
PR-HARIHARAN Dec 12, 2025
99e1382
Add non-numeric index example for loc slice step behavior
PR-HARIHARAN Dec 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions doc/source/user_guide/indexing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -431,6 +431,24 @@ an error will be raised. For instance, in the above example, ``s.loc[2:5]`` woul
For more information about duplicate labels, see
:ref:`Duplicate Labels <duplicates>`.

Also, when using a slice with a step, such as ``.loc[start:stop:step]``, note that
Copy link
Member

@rhshadrach rhshadrach Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The previous paragraph also starts with Also,, just from a prose standpoint I think we should avoid this.

Suggested change
Also, when using a slice with a step, such as ``.loc[start:stop:step]``, note that
When using a slice with a step, such as ``.loc[start:stop:step]``, note that

*start* and *stop* are interpreted as **labels**, while *step* is applied over
the **positional index** within that label range. This means a stepped slice
may return different labels than selecting an explicit list, even when they
appear similar.
Copy link
Member

@rhshadrach rhshadrach Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this could be made a little more specific.

Suggested change
the **positional index** within that label range. This means a stepped slice
may return different labels than selecting an explicit list, even when they
appear similar.
the **positional index** within that label range. This means a stepped slice
will behave differently than using the labels `range(start, stop, step)` when
the index is not contiguous integers.


For example, in a ``Series`` with a non-contiguous integer index:

.. ipython:: python
s = pd.Series(range(10), index=[0, 5, 10, 15, 20, 25, 30, 35, 40, 45])
s.loc[10:50:5] # (10), then skip 3 positions → 35 only
Copy link
Member

@mroeschke mroeschke Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you also show a similar example where the index is not numeric?

s.loc[[10, 15, 20, 25]] # explicit label selection
The first applies *step* across **positional locations** between the start/stop
labels. The second selects each label directly.


.. _indexing.integer:

Selection by position
Expand Down
Loading