DOC" update the Pandas core window rolling count docstring" #20264

tommy-stone · 2018-03-11T00:05:46Z

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

PR title is "DOC: update the docstring"
The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
The html version looks good: python doc/make.py --single <your-function-or-method>
It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

################################################################################
################# Docstring (pandas.core.window.Rolling.count) #################
################################################################################

The rolling sum if it is a non-Nan value inside the window.

Returns
-------
Returns the object type with the sum of the window values
in the current row.

See Also
--------
Series.rolling : Calling object with Series data
DataFrame.rolling : Calling object with DataFrames

Examples
--------
>>> s = pd.Series([2, 3, np.nan, 'values'])
>>> s.rolling(2).count()
0    1.0
1    2.0
2    1.0
3    1.0
dtype: float64
>>> s.rolling(3).count()
0    1.0
1    2.0
2    2.0
3    2.0
dtype: float64
>>> s.rolling(4).count()
0    1.0
1    2.0
2    2.0
3    3.0
dtype: float64

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	No extended summary found

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

closes #xxxx
tests added / passed
passes git diff upstream/master -u -- "*.py" | flake8 --diff
whatsnew entry

WillAyd · 2018-03-11T00:54:26Z

pandas/core/window.py

-    _shared_docs['count'] = """%(name)s count of number of non-NaN
-    observations inside provided window."""
+    _shared_docs['count'] = dedent(r"""
+    The %(name)s sum if it is a non-Nan value inside the window.


Using the word sum is confusing here for a count. Can you reword to the effect of "count of non-NaN observations..."?

"count of non-Nan observations inside the rolling window" would work?

@scriptomation be sure that you actually surround your reference to NaN in back ticks, so literally you would write non-`NaN` (capitalization matters too)

WillAyd · 2018-03-11T00:55:06Z

pandas/core/window.py

+    See Also
+    --------
+    Series.%(name)s : Calling object with Series data
+    DataFrame.%(name)s : Calling object with DataFrames


Can you link to Series / DataFrame sum methods?

You can take a look at how the other PRs did this, see eg https://github.com/pandas-dev/pandas/pull/19999/files

Sounds good, I will update that information.

WillAyd · 2018-03-11T00:57:43Z

pandas/core/window.py

+
+    Returns
+    -------
+    Returns the object type with the sum of the window values


Can you make note of what the return type is? Also similar comment as above - referring to sum within a count function is confusing. I'm not sure current row is the right concept here, though I understand what you are trying to get at

You can use a similar wording as here: https://github.com/pandas-dev/pandas/pull/20263/files

That makes sense. How does this work?

Returns
-------
Series or Dataframe
Returned object type is determined by the caller of %(name)

I would just copy verbatim, so Returned object type is determined by the caller of the %(name)s calculation

jorisvandenbossche · 2018-03-11T12:07:48Z

pandas/core/window.py

+    See Also
+    --------
+    Series.%(name)s : Calling object with Series data
+    DataFrame.%(name)s : Calling object with DataFrames


You can take a look at how the other PRs did this, see eg https://github.com/pandas-dev/pandas/pull/19999/files

jorisvandenbossche · 2018-03-11T12:08:58Z

pandas/core/window.py

+
+    Examples
+    --------
+    >>> s = pd.Series([2, 3, np.nan, 'values'])


It's a bit strange to give an example with mixed floats / strings (I mean, in general that's not really good practice to have data like that). I think only using floats (with nans) is fine.

I wanted to show an example of mixed values being counted, in case a mistake is made by having different types of data. I see what you are saying though since it's already stated in the description. I will update to only use floats and nans. Thanks!

jorisvandenbossche · 2018-03-11T12:10:17Z

pandas/core/window.py

+
+    Returns
+    -------
+    Returns the object type with the sum of the window values


You can use a similar wording as here: https://github.com/pandas-dev/pandas/pull/20263/files

jorisvandenbossche · 2018-03-17T11:42:14Z

@scriptomation do you have time to update this based on the feedback?

tommy-stone · 2018-03-17T18:15:27Z

@jorisvandenbossche Thank you for the feed back. Updating it this weekend and will resubmit.

…nd examples. Updated information

codecov · 2018-03-19T21:12:02Z

Codecov Report

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

@@            Coverage Diff             @@
##           master   #20264      +/-   ##
==========================================
- Coverage   91.77%   91.77%   -0.01%     
==========================================
  Files         152      152              
  Lines       49205    49204       -1     
==========================================
- Hits        45159    45158       -1     
  Misses       4046     4046

Flag	Coverage Δ
#multiple	`90.16% <100%> (-0.01%)`	⬇️
#single	`41.85% <41.66%> (-0.01%)`	⬇️

Impacted Files	Coverage Δ
pandas/core/window.py	`96.26% <100%> (-0.01%)`	⬇️
pandas/core/indexes/timedeltas.py	`91.22% <0%> (ø)`	⬆️
pandas/core/internals.py	`95.53% <0%> (ø)`	⬆️
pandas/core/indexes/base.py	`96.68% <0%> (ø)`	⬆️

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 7273ea0...946836c. Read the comment docs.

jorisvandenbossche

Thanks for the update!

(added a small fixup to also have this working with expanding)

jorisvandenbossche · 2018-03-19T21:13:32Z

Thanks for the PR!

…ame_describe * upstream/master: (158 commits) Add link to "Craft Minimal Bug Report" blogpost (pandas-dev#20431) BUG: fixed json_normalize for subrecords with NoneTypes (pandas-dev#20030) (pandas-dev#20399) BUG: ExtensionArray.fillna for scalar values (pandas-dev#20412) DOC" update the Pandas core window rolling count docstring" (pandas-dev#20264) DOC: update the pandas.DataFrame.plot.hist docstring (pandas-dev#20155) DOC: Only use ~ in class links to hide prefixes. (pandas-dev#20402) Bug: Allow np.timedelta64 objects to index TimedeltaIndex (pandas-dev#20408) DOC: add disallowing of Series construction of len-1 list with index to whatsnew (pandas-dev#20392) MAINT: Remove weird pd file DOC: update the Index.isin docstring (pandas-dev#20249) BUG: Handle all-NA blocks in concat (pandas-dev#20382) DOC: update the pandas.core.resample.Resampler.fillna docstring (pandas-dev#20379) BUG: Don't raise exceptions splitting a blank string (pandas-dev#20067) DOC: update the pandas.DataFrame.cummax docstring (pandas-dev#20336) DOC: update the pandas.core.window.x.mean docstring (pandas-dev#20265) DOC: update the api.types.is_number docstring (pandas-dev#20196) Fix linter (pandas-dev#20389) DOC: Improved the docstring of pandas.Series.dt.to_pytimedelta (pandas-dev#20142) DOC: update the pandas.Series.dt.is_month_end docstring (pandas-dev#20181) DOC: update the window.Rolling.min docstring (pandas-dev#20263) ...

…ev#20264)

tommy-stone added 2 commits March 10, 2018 15:50

updated windows.py count docstring

6f59df9

DOC: update the pandas.core.window.Rolling.count docstring

4c1500c

WillAyd requested changes Mar 11, 2018

View reviewed changes

jorisvandenbossche added Docs and removed Docs labels Mar 11, 2018

jorisvandenbossche reviewed Mar 11, 2018

View reviewed changes

tommy-stone and others added 4 commits March 17, 2018 14:44

Received comments on updating description to use count, return type a…

a59c9cb

…nd examples. Updated information

updated See Also section to remove typo with calling objects

122f930

updated count docstring based on comments

f8d77ef

also remove doc_template for expanding

946836c

jorisvandenbossche approved these changes Mar 19, 2018

View reviewed changes

jorisvandenbossche added this to the 0.23.0 milestone Mar 19, 2018

jorisvandenbossche merged commit bd8a3cf into pandas-dev:master Mar 19, 2018

nikoskaragiannakis pushed a commit to nikoskaragiannakis/pandas that referenced this pull request Mar 25, 2018

DOC" update the Pandas core window rolling count docstring" (pandas-d…

ddb904f

…ev#20264)

dworvos pushed a commit to dworvos/pandas that referenced this pull request Apr 2, 2018

DOC" update the Pandas core window rolling count docstring" (pandas-d…

e7b87f7

…ev#20264)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC" update the Pandas core window rolling count docstring" #20264

DOC" update the Pandas core window rolling count docstring" #20264

tommy-stone commented Mar 11, 2018

WillAyd Mar 11, 2018

tommy-stone Mar 17, 2018

jorisvandenbossche Mar 17, 2018

WillAyd Mar 19, 2018

WillAyd Mar 11, 2018

jorisvandenbossche Mar 11, 2018

tommy-stone Mar 17, 2018

WillAyd Mar 11, 2018

jorisvandenbossche Mar 11, 2018

tommy-stone Mar 17, 2018

WillAyd Mar 17, 2018

jorisvandenbossche Mar 11, 2018

jorisvandenbossche Mar 11, 2018

tommy-stone Mar 17, 2018

jorisvandenbossche Mar 11, 2018

jorisvandenbossche commented Mar 17, 2018

tommy-stone commented Mar 17, 2018

codecov bot commented Mar 19, 2018

jorisvandenbossche left a comment

jorisvandenbossche commented Mar 19, 2018

DOC" update the Pandas core window rolling count docstring" #20264

DOC" update the Pandas core window rolling count docstring" #20264

Conversation

tommy-stone commented Mar 11, 2018

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

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

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorisvandenbossche commented Mar 17, 2018

tommy-stone commented Mar 17, 2018

codecov bot commented Mar 19, 2018

Codecov Report

jorisvandenbossche left a comment

Choose a reason for hiding this comment

jorisvandenbossche commented Mar 19, 2018