DOC: update the Rolling.var docstring #20233

mmaybeno · 2018-03-10T20:30:28Z

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.var) ##################
################################################################################

Calculate unbiased rolling variance.

Normalized by N-1 by default. This can be changed using the ddof argument.

Parameters
----------
ddof : int, default 1
    Delta Degrees of Freedom.  The divisor used in calculations
    is ``N - ddof``, where ``N`` represents the number of elements.
args
    Under Review.
kwargs
    Under Review.

Returns
-------
Series or DataFrame
    Returned object type is determined by the caller of the rolling
    calculation

See Also
--------
Series.rolling : Calling object with Series data
DataFrame.rolling : Calling object with DataFrames
Series.var : Equivalent method for Series
DataFrame.var : Equivalent method for DataFrame
numpy.var : Equivalent method for Numpy array

Notes
-----
A minimum of 1 periods is required for the rolling calculation.

Examples
--------
The below example will show a rolling example

>>> s = pd.Series((5,5,5,5,6,7,9,10,5,5,5,5))
>>> s.rolling(3).var(1)
0          NaN
1          NaN
2     0.000000
3     0.000000
4     0.333333
5     1.000000
6     2.333333
7     2.333333
8     7.000000
9     8.333333
10    0.000000
11    0.000000
dtype: float64

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

Errors found:
        Errors in parameters section
                Parameter "args" has no type
                Parameter "kwargs" has no type


################################################################################
################# Docstring (pandas.core.window.Expanding.var) #################
################################################################################

Calculate unbiased expanding variance.

Normalized by N-1 by default. This can be changed using the ddof argument.

Parameters
----------
ddof : int, default 1
    Delta Degrees of Freedom.  The divisor used in calculations
    is ``N - ddof``, where ``N`` represents the number of elements.
args
    Under Review.
kwargs
    Under Review.

Returns
-------
Series or DataFrame
    Returned object type is determined by the caller of the expanding
    calculation

See Also
--------
Series.expanding : Calling object with Series data
DataFrame.expanding : Calling object with DataFrames
Series.var : Equivalent method for Series
DataFrame.var : Equivalent method for DataFrame
numpy.var : Equivalent method for Numpy array

Notes
-----
A minimum of 1 periods is required for the rolling calculation.

Examples
--------
The below example will show a rolling example

>>> s = pd.Series((5,5,5,5,6,7,9,10,5,5,5,5))
>>> s.rolling(3).var(1)
0          NaN
1          NaN
2     0.000000
3     0.000000
4     0.333333
5     1.000000
6     2.333333
7     2.333333
8     7.000000
9     8.333333
10    0.000000
11    0.000000
dtype: float64

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

Errors found:
        Errors in parameters section
                Parameter "args" has no type
                Parameter "kwargs" has no type

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.

mmaybeno · 2018-03-10T20:40:28Z

Also updates docs for expanding window

TomAugspurger · 2018-03-10T20:36:46Z

pandas/core/window.py

-    %(name)s variance
+    Calculate unbiased %(name)s variance.
+
+    Normalized by N-1 by default. This can be changed using the ddof argument.


single backtics around ddof since it's a parameter.

TomAugspurger · 2018-03-10T20:38:23Z

pandas/core/window.py

+    10    0.000000
+    11    0.000000
+    dtype: float64
+    """)


Can you show s.expanding(3).var(1) as well?

TomAugspurger · 2018-03-10T20:40:27Z

pandas/core/window.py


    Parameters
    ----------
    ddof : int, default 1
        Delta Degrees of Freedom.  The divisor used in calculations
-        is ``N - ddof``, where ``N`` represents the number of elements.""")
+        is ``N - ddof``, where ``N`` represents the number of elements.
+    args


I don't think the underlying function takes any additional arguments. Can remove (I think).

I can remove it, it looks like it passes them through, but I didn't dive into it's usage.. I'll remove for now.

TomAugspurger · 2018-03-10T20:40:59Z

pandas/core/window.py

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


It's always the same type as the original object, right? Series.rolling().var is always a Series? Let's say that.

But DataFrame.rolling().var() is a DataFrame, so that is what the above sentences tries to say. What do you want to change?

"is determined by " -> "same type as" ?

datapythonista

Nice one, added some comments.

datapythonista · 2018-03-10T20:38:15Z

pandas/core/window.py

-    %(name)s variance
+    Calculate unbiased %(name)s variance.
+
+    Normalized by N-1 by default. This can be changed using the ddof argument.


Can you add backticks around ddof please?

datapythonista · 2018-03-10T20:39:44Z

pandas/core/window.py

+    --------
+    The below example will show a rolling example
+
+    >>> s = pd.Series((5,5,5,5,6,7,9,10,5,5,5,5))


Can you add spaces after the commas, so this passes PEP-8

datapythonista · 2018-03-10T20:40:06Z

pandas/core/window.py

+
+    Examples
+    --------
+    The below example will show a rolling example


I'd take this sentence out, I think users will assume that.

datapythonista · 2018-03-10T20:43:43Z

pandas/core/window.py

+    args
+        Under Review.
+    kwargs
+        Under Review.


*args and **kwargs should have the stars. We changed the convention last minute, and the validation script is wrong, ignore the messages.

jorisvandenbossche · 2018-03-10T21:12:25Z

pandas/core/window.py

+
+    Returns
+    -------
+    Returns the same object type as determined by the caller of the %(name)s


I would keep the Series or DataFrame on the line above (as you had it before), that makes it clearer it is one of those.

If you use "same object type", then you can omit "as determined by" I think

jorisvandenbossche · 2018-03-10T21:13:29Z

pandas/core/window.py

+
+    Examples
+    --------
+    >>> s = pd.Series((5, 5, 5, 5, 6, 7, 9, 10, 5, 5, 5, 5))


See comment on other PR, can you use a list here instead of tuple?
I also think it can maybe a bit shorter? Or is there something specific you want to illustrate with this exact sequence of numbers ?

I can do that, no specific reason why I used such a long tuple.

jreback · 2018-03-10T21:34:15Z

pandas/core/window.py

+    numpy.var : Equivalent method for Numpy array
+
+    Notes
+    -----


so in both this one and the std one, should put in the Notes that the ddof default is different than numpy. (we use 1, they use 0). This is in the Series.var/std strings already.

jreback · 2018-03-11T14:57:10Z

pandas/core/window.py

-        is ``N - ddof``, where ``N`` represents the number of elements.""")
+        is ``N - ddof``, where ``N`` represents the number of elements.
+    *args
+        Under Review.


@jorisvandenbossche ?

It was mentioned that the exact content for what should be documented for args/kwargs was to be determined. If you'd rather me add the documentation I can do that too.

I think we're noting that they're accepted, but not used.

TomAugspurger · 2018-03-12T17:08:03Z

Thanks again @mmaybeno.

mmaybeno added 2 commits March 10, 2018 12:01

DOC: update the Rolling.var docstring

1c7f700

remove whitespace

b7690ef

TomAugspurger reviewed Mar 10, 2018

View reviewed changes

datapythonista reviewed Mar 10, 2018

View reviewed changes

Addressing comments

be9733f

jorisvandenbossche reviewed Mar 10, 2018

View reviewed changes

jorisvandenbossche mentioned this pull request Mar 10, 2018

DOC: update Rolling.std docstring #20235

Merged

5 tasks

jreback requested changes Mar 10, 2018

View reviewed changes

jreback added Docs Reshaping Concat, Merge/Join, Stack/Unstack, Explode Numeric Operations Arithmetic, Comparison, and Logical operations labels Mar 10, 2018

Addressing comments 2

1dded7c

jreback reviewed Mar 11, 2018

View reviewed changes

args, kwargs

8de2598

TomAugspurger approved these changes Mar 11, 2018

View reviewed changes

TomAugspurger merged commit eea0350 into pandas-dev:master Mar 12, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: update the Rolling.var docstring #20233

DOC: update the Rolling.var docstring #20233

mmaybeno commented Mar 10, 2018 •

edited

Loading

mmaybeno commented Mar 10, 2018

TomAugspurger Mar 10, 2018

TomAugspurger Mar 10, 2018

TomAugspurger Mar 10, 2018

mmaybeno Mar 10, 2018

TomAugspurger Mar 10, 2018

jorisvandenbossche Mar 10, 2018

datapythonista left a comment

datapythonista Mar 10, 2018

datapythonista Mar 10, 2018

datapythonista Mar 10, 2018

datapythonista Mar 10, 2018

jorisvandenbossche Mar 10, 2018

jorisvandenbossche Mar 10, 2018

mmaybeno Mar 11, 2018

jreback Mar 10, 2018

mmaybeno Mar 11, 2018

jreback Mar 11, 2018

mmaybeno Mar 11, 2018

TomAugspurger Mar 11, 2018

TomAugspurger commented Mar 12, 2018

DOC: update the Rolling.var docstring #20233

DOC: update the Rolling.var docstring #20233

Conversation

mmaybeno commented Mar 10, 2018 • edited Loading

mmaybeno commented Mar 10, 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

datapythonista 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

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

TomAugspurger commented Mar 12, 2018

mmaybeno commented Mar 10, 2018 •

edited

Loading