Skip to content

DOC: update the pd.Index.asof docstring #20344

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

Merged
merged 4 commits into from
Jul 7, 2018
Merged

DOC: update the pd.Index.asof docstring #20344

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1cf723a
DOC: update the pd.Index.asof docstring
Mar 14, 2018
d75bf5b
clearer descriptions, restructured examples.
Mar 19, 2018
f6e3b2e
extended See Also section, dates instead of integers in Examples
Apr 25, 2018
9bc532a
minor formatting
Apr 25, 2018
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
43 changes: 40 additions & 3 deletions pandas/core/indexes/base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2378,12 +2378,49 @@ def identical(self, other):

def asof(self, label):
"""
For a sorted index, return the most recent label up to and including
the passed label. Return NaN if not found.
Return the latest index label up to and including the passed label.

For sorted indexes, return the index label that is the latest among
the labels that are not later than the passed index label.
Copy link
Member

Choose a reason for hiding this comment

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

I find this whole docstring a bit confusing to be honest. I think it's a complex method to document, but I think we can do better.

For the examples, I find this much clearer:

import pandas

idx = pandas.Index(['a', 'b', 'd', 'e'])
idx.asof('c')

For the description, it's difficult, but something like "Return the label from the index, or the previous if not found" would be something easier to understand for me.

For the rest looks quite good.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It's hard to be completely understandable within a single line. But I'll try again using your suggestions. Thanks!


Parameters
----------
label : object
The label up to which the method returns the latest index label.

Returns
-------
object : The index label that is the latest as of the passed label,
or NaN if there is no such label.

See also
--------
get_loc : asof is a thin wrapper around get_loc with method='pad'
Index.get_loc : `asof` is a thin wrapper around `get_loc`
with method='pad'.

Examples
--------
The method returns the latest index label up to the passed label.

>>> pd.Index([13, 18, 20]).asof(14)
13

If the label is in the index, the method returns the passed label.

>>> pd.Index([13, 18, 20]).asof(18)
18

If all of the labels in the index are later than the passed label,
NaN is returned.

>>> pd.Index([13, 18, 20]).asof(1)
nan

If the index is not sorted, an error is raised.

>>> pd.Index([13, 20, 18]).asof(18)
Traceback (most recent call last):
ValueError: index must be monotonic increasing or decreasing
Copy link
Member

Choose a reason for hiding this comment

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

Looks great. The only think that comes to my mind is if it'd make sense to use dates in the examples. I think the example with integers is simpler, and easier to understand. But I'd say in practice the method is only used with dates.

Like, if you want to know the price of a stock, and you say, give me the price asof 1st of January. The 1st of January the markets are closed, so the price returned would be the one of the 31st of December or the last day the markets were open.

I'm not quite sure what would be the best. If you think you can improve the docstring with the user case I just mentioned, that would be great. Otherwise looks good to me.

And may be we could also add Series.asof and pandas.merge_asof to the See Also section.

Thanks for the good work.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Thanks for the feedback! I've updated the docs using your suggestions.

"""
try:
loc = self.get_loc(label, method='pad')
Expand Down