Skip to content

DOC: Rephrased doc for Series.asof. Added examples #21034

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
Nov 4, 2018
Merged

DOC: Rephrased doc for Series.asof. Added examples #21034

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
49f3e84
DOC: Rephrased doc for Series.asof. Added examples
May 14, 2018
2e66ff1
Merge remote-tracking branch 'upstream/master' into dragosthealex-aso…
TomAugspurger Nov 2, 2018
5b8bb9a
update
TomAugspurger Nov 2, 2018
65c1a2b
Fixing couple of formatting issues
datapythonista Nov 3, 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
54 changes: 42 additions & 12 deletions pandas/core/generic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6044,19 +6044,25 @@ def interpolate(self, method='linear', axis=0, limit=None, inplace=False,

def asof(self, where, subset=None):
"""
The last row without any NaN is taken (or the last row without
NaN considering only the subset of columns in the case of a DataFrame)
Return the last row(s) without any `NaN`s before `where`.
Copy link
Member

Choose a reason for hiding this comment

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

Something like `NaN`s fails in sphinx, we can only use ` on things that are quoted completely, without trailing 's' or so

Copy link
Member

Choose a reason for hiding this comment

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

Further, I am not fully sure we should quote NaN. It is not a pandas function name or keyword argument or so. I would rather say it is "code"-like, but then we should actually use the proper name like np.nan. Therefore, maybe a compromise to simply not quote?


The last row (for each element in `where`, if list) without any
`NaN` is taken.
In case of a :class:`~pandas.DataFrame`, the last row without `NaN`
considering only the subset of columns (if not `None`)

.. versionadded:: 0.19.0 For DataFrame

If there is no good value, NaN is returned for a Series
If there is no good value, `NaN` is returned for a Series or
a Series of NaN values for a DataFrame

Parameters
----------
where : date or array of dates
subset : string or list of strings, default None
if not None use these columns for NaN propagation
where : date or array-like of dates
Date(s) before which the last row(s) are returned.
subset : str or array-like of str, default `None`
Copy link
Member

Choose a reason for hiding this comment

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

I think in general we don't quote on the parameter type line?

For DataFrame, if not `None`, only use these columns to
check for `NaN`s.

Notes
-----
Expand All @@ -6065,19 +6071,43 @@ def asof(self, where, subset=None):

Returns
-------
where is scalar
`where` is scalar
Copy link
Contributor

Choose a reason for hiding this comment

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

This should be formatted as

possible types
    case 1
    case 2

so somehting like

scalar, Series, or DataFrame

* scalar : when `self` is a Series and `where` is a scalar
* Series: when `self` is a Series and `where` is an array-like, or when `self` is a DataFrame and `where` is a scalar
* DataFrame : when `self` is a DataFrame and `where` is an array-like


- value or NaN if input is Series
- Series if input is DataFrame
- value or `NaN` if input is Series
- Series if input is DataFrame

where is Index: same shape object as input
`where` is :class:`pandas.Index`:
Copy link
Contributor

Choose a reason for hiding this comment

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

Not sure I understand this. Is an Index for where treated differently than other inputes?

- same shape object as input

See Also
--------
merge_asof
merge_asof : Perform an asof merge. Similar to left join.

Examples
--------
Take all columns into consideration
Copy link
Contributor

Choose a reason for hiding this comment

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

Can you add additional examples for

  • Series w/ scalar where
  • Series w/ array-like where
  • DataFrame w/ scalar where


>>> df = pd.DataFrame({'a': [10, 20, 30, 40, 50],
... 'b': [None, None, None, None, 500]},
... index=pd.DatetimeIndex(['2018-02-27 09:01:00',
... '2018-02-27 09:02:00',
... '2018-02-27 09:03:00',
... '2018-02-27 09:04:00',
... '2018-02-27 09:05:00']))
>>> df.asof(pd.DatetimeIndex(['2018-02-27 09:03:30',
... '2018-02-27 09:04:30']))
a b
2018-02-27 09:03:30 NaN NaN
2018-02-27 09:04:30 NaN NaN

Take a single column into consideration

>>> df['a'].asof(pd.DatetimeIndex(['2018-02-27 09:03:30',
... '2018-02-27 09:04:30']))
2018-02-27 09:03:30 30.0
2018-02-27 09:04:30 40.0
Name: a, dtype: float64
"""

if isinstance(where, compat.string_types):
from pandas import to_datetime
where = to_datetime(where)
Expand Down