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

dragosthealex · 2018-05-14T18:26:18Z

Used code from #20652 as example, to illustrate different behaviours.

closes DataFrame.asof() fails when some columns are NaN #20652
tests added / passed (N/A, docs)
passes git diff upstream/master -u -- "*.py" | flake8 --diff
whatsnew entry

TomAugspurger · 2018-05-14T18:52:44Z

pandas/core/generic.py

+        --------
+        Take all columns into consideration
+
+        >>> data = u'''dt,a,b


Probably best to construct this directly, rather than using read_csv. Can you do

df = pd.DataFrame({'a': [...], 'b': [...], index=pd.DatetimeIndex([...])

instead? Also, these floating point values are a bit hard to understand when just glancing. Could you change to integers instead?

TomAugspurger

We recently added a docstring guide http://pandas-docs.github.io/pandas-docs-travis/contributing_docstring.html

Can you validate that your changes pass this guide?

codecov · 2018-05-14T19:34:46Z

Codecov Report

Merging #21034 into master will decrease coverage by <.01%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master   #21034      +/-   ##
==========================================
- Coverage   92.23%   92.23%   -0.01%     
==========================================
  Files         161      161              
  Lines       51187    51197      +10     
==========================================
+ Hits        47211    47220       +9     
- Misses       3976     3977       +1

Flag	Coverage Δ
#multiple	`90.61% <100%> (-0.01%)`	⬇️
#single	`42.27% <100%> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/core/generic.py	`96.81% <100%> (ø)`	⬆️
pandas/core/arrays/timedeltas.py	`93.75% <0%> (-0.56%)`	⬇️
pandas/util/testing.py	`86.64% <0%> (-0.2%)`	⬇️
pandas/core/indexes/api.py	`99% <0%> (ø)`	⬆️
pandas/core/series.py	`93.87% <0%> (ø)`	⬆️
pandas/core/indexes/datetimelike.py	`98.01% <0%> (ø)`	⬆️
pandas/core/indexes/timedeltas.py	`90.74% <0%> (+0.12%)`	⬆️
pandas/core/indexes/frozen.py	`92.1% <0%> (+0.43%)`	⬆️
pandas/core/arrays/period.py	`98.08% <0%> (+0.59%)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update c30c07f...65c1a2b. Read the comment docs.

pep8speaks · 2018-05-14T19:35:44Z

Hello @dragosthealex! Thanks for updating the PR.

Cheers ! There are no PEP8 issues in this Pull Request. 🍻

Comment last updated on May 14, 2018 at 20:44 Hours UTC

Used code from #20652 as example, to illustrate different behaviours.

dragosthealex · 2018-05-15T15:26:53Z

@TomAugspurger Yes, the validation passes

TomAugspurger · 2018-05-17T12:59:01Z

pandas/core/generic.py

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

        Returns
        -------
-        where is scalar
+        `where` is scalar


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

TomAugspurger · 2018-05-17T13:00:58Z

pandas/core/generic.py


-        where is Index: same shape object as input
+        `where` is :class:`pandas.Index`:


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

TomAugspurger · 2018-05-17T13:01:58Z

pandas/core/generic.py


+        Examples
+        --------
+        Take all columns into consideration


Can you add additional examples for

Series w/ scalar where

Series w/ array-like where

DataFrame w/ scalar where

jreback · 2018-06-19T01:45:52Z

can you update for comments

jreback · 2018-11-01T01:41:28Z

closing as stale. if you'd like to continue pls ping.

jreback · 2018-11-01T01:42:22Z

@datapythonista this looks close.

…f-docs

TomAugspurger · 2018-11-02T14:17:18Z

Pushed a quick update. Probably good to merge.

datapythonista

Pushed couple of additional formatting fixes, merging on green

jreback · 2018-11-04T15:01:19Z

thanks @dragosthealex

jorisvandenbossche

@datapythonista I was fixing some doc warnings in #23636, and came across those ones.

In the PR I simply removed all quotes on "NaN" (as that also avoids the problem with "NaNs"), but can certainly discuss further.

jorisvandenbossche · 2018-11-12T12:34:02Z

pandas/core/generic.py

@@ -6495,40 +6495,98 @@ 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`.


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

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?

jorisvandenbossche · 2018-11-12T12:35:29Z

pandas/core/generic.py

-           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`


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

datapythonista · 2018-11-12T13:22:21Z

Yes, those are good points I wanted to discuss at some point.

This is something I fixed in the past, as the rendering in sphinx was broken:

`DataFrame`s -> `DataFrame` objects

For what I know, single backticks should be used for argument names, variables, functions, methods, classes... So, NaN as a value or concept, could use double backticks, considering it code, normal quotes, or nothing. I don't have a preference.

In the type, we don't usually use backticks (but I've seen some cases where we do):

fill_value : object, default None

fill_value : object, default ``None``

I don't have a preference either, but we should start to be consistent.

May be we should create an issue, have some discussion, and then start enforcing it? Not sure how difficult can be to add validation for this in validate_docstrings.py at this point, but surely something can (and should) be done.

TomAugspurger reviewed May 14, 2018

View reviewed changes

DOC: Rephrased doc for Series.asof. Added examples

49f3e84

Used code from #20652 as example, to illustrate different behaviours.

TomAugspurger reviewed May 17, 2018

View reviewed changes

gfyoung added the Docs label May 21, 2018

datapythonista self-assigned this Jul 22, 2018

datapythonista mentioned this pull request Aug 22, 2018

Series as of docstring #20226

Closed

9 tasks

jreback closed this Nov 1, 2018

jreback reopened this Nov 1, 2018

TomAugspurger added 2 commits November 2, 2018 07:04

Merge remote-tracking branch 'upstream/master' into dragosthealex-aso…

2e66ff1

…f-docs

update

5b8bb9a

Fixing couple of formatting issues

65c1a2b

datapythonista approved these changes Nov 3, 2018

View reviewed changes

jreback added this to the 0.24.0 milestone Nov 4, 2018

jreback merged commit 17e3c5c into pandas-dev:master Nov 4, 2018

jorisvandenbossche reviewed Nov 12, 2018

View reviewed changes

JustinZhengBC pushed a commit to JustinZhengBC/pandas that referenced this pull request Nov 14, 2018

DOC: Rephrased doc for Series.asof. Added examples (pandas-dev#21034)

8c29ede

tm9k1 pushed a commit to tm9k1/pandas that referenced this pull request Nov 19, 2018

DOC: Rephrased doc for Series.asof. Added examples (pandas-dev#21034)

d808011

Pingviinituutti pushed a commit to Pingviinituutti/pandas that referenced this pull request Feb 28, 2019

DOC: Rephrased doc for Series.asof. Added examples (pandas-dev#21034)

688e5a3

Pingviinituutti pushed a commit to Pingviinituutti/pandas that referenced this pull request Feb 28, 2019

DOC: Rephrased doc for Series.asof. Added examples (pandas-dev#21034)

64b150a

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

dragosthealex commented May 14, 2018 •

edited

Loading

TomAugspurger May 14, 2018

dragosthealex May 14, 2018

TomAugspurger left a comment

codecov bot commented May 14, 2018 •

edited

Loading

pep8speaks commented May 14, 2018 •

edited

Loading

dragosthealex commented May 15, 2018

TomAugspurger May 17, 2018

TomAugspurger May 17, 2018

TomAugspurger May 17, 2018

jreback commented Jun 19, 2018

jreback commented Nov 1, 2018

jreback commented Nov 1, 2018

TomAugspurger commented Nov 2, 2018

datapythonista left a comment

jreback commented Nov 4, 2018

jorisvandenbossche left a comment

jorisvandenbossche Nov 12, 2018

jorisvandenbossche Nov 12, 2018

jorisvandenbossche Nov 12, 2018

datapythonista commented Nov 12, 2018


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

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

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

Conversation

dragosthealex commented May 14, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TomAugspurger left a comment

Choose a reason for hiding this comment

codecov bot commented May 14, 2018 • edited Loading

Codecov Report

pep8speaks commented May 14, 2018 • edited Loading

Comment last updated on May 14, 2018 at 20:44 Hours UTC

dragosthealex commented May 15, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jreback commented Jun 19, 2018

jreback commented Nov 1, 2018

jreback commented Nov 1, 2018

TomAugspurger commented Nov 2, 2018

datapythonista left a comment

Choose a reason for hiding this comment

jreback commented Nov 4, 2018

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

datapythonista commented Nov 12, 2018

dragosthealex commented May 14, 2018 •

edited

Loading

codecov bot commented May 14, 2018 •

edited

Loading

pep8speaks commented May 14, 2018 •

edited

Loading