From 1c7f700e6ef91cc5156b77e7fef3557d798ecfc2 Mon Sep 17 00:00:00 2001 From: Matt Maybeno Date: Sat, 10 Mar 2018 12:01:12 -0800 Subject: [PATCH 1/5] DOC: update the Rolling.var docstring --- pandas/core/window.py | 53 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 5 deletions(-) diff --git a/pandas/core/window.py b/pandas/core/window.py index c41b07759d555..4f99ea2d85ccb 100644 --- a/pandas/core/window.py +++ b/pandas/core/window.py @@ -879,13 +879,58 @@ def f(arg, *args, **kwargs): ddof=ddof, **kwargs) _shared_docs['var'] = dedent(""" - %(name)s variance - + Calculate unbiased %(name)s 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.""") + 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 %(name)s + calculation + + See Also + -------- + Series.%(name)s : Calling object with Series data + DataFrame.%(name)s : 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 + """) def var(self, ddof=1, *args, **kwargs): nv.validate_window_func('var', args, kwargs) @@ -1257,7 +1302,6 @@ def std(self, ddof=1, *args, **kwargs): return super(Rolling, self).std(ddof=ddof, **kwargs) @Substitution(name='rolling') - @Appender(_doc_template) @Appender(_shared_docs['var']) def var(self, ddof=1, *args, **kwargs): nv.validate_rolling_func('var', args, kwargs) @@ -1496,7 +1540,6 @@ def std(self, ddof=1, *args, **kwargs): return super(Expanding, self).std(ddof=ddof, **kwargs) @Substitution(name='expanding') - @Appender(_doc_template) @Appender(_shared_docs['var']) def var(self, ddof=1, *args, **kwargs): nv.validate_expanding_func('var', args, kwargs) From b7690ef8a5ad9cd3f0070027041eaf73f1ae49af Mon Sep 17 00:00:00 2001 From: Matt Maybeno Date: Sat, 10 Mar 2018 12:24:15 -0800 Subject: [PATCH 2/5] remove whitespace --- pandas/core/window.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/pandas/core/window.py b/pandas/core/window.py index 4f99ea2d85ccb..083b6438c6d53 100644 --- a/pandas/core/window.py +++ b/pandas/core/window.py @@ -880,9 +880,9 @@ def f(arg, *args, **kwargs): _shared_docs['var'] = dedent(""" Calculate unbiased %(name)s variance. - + Normalized by N-1 by default. This can be changed using the ddof argument. - + Parameters ---------- ddof : int, default 1 @@ -892,13 +892,13 @@ def f(arg, *args, **kwargs): Under Review. kwargs Under Review. - + Returns ------- Series or DataFrame Returned object type is determined by the caller of the %(name)s calculation - + See Also -------- Series.%(name)s : Calling object with Series data @@ -906,15 +906,15 @@ def f(arg, *args, **kwargs): 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 - + 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 From be9733f8187e4187c6c838b9f37a45f2194c1b1a Mon Sep 17 00:00:00 2001 From: Matt Maybeno Date: Sat, 10 Mar 2018 13:05:01 -0800 Subject: [PATCH 3/5] Addressing comments --- pandas/core/window.py | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/pandas/core/window.py b/pandas/core/window.py index 083b6438c6d53..a918f5d6895a7 100644 --- a/pandas/core/window.py +++ b/pandas/core/window.py @@ -881,23 +881,23 @@ def f(arg, *args, **kwargs): _shared_docs['var'] = dedent(""" Calculate unbiased %(name)s variance. - Normalized by N-1 by default. This can be changed using the ddof argument. + 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 + *args Under Review. - kwargs + **kwargs Under Review. Returns ------- - Series or DataFrame - Returned object type is determined by the caller of the %(name)s - calculation + Returns the same object type as determined by the caller of the %(name)s + calculation. See Also -------- @@ -913,9 +913,7 @@ def f(arg, *args, **kwargs): 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 = pd.Series((5, 5, 5, 5, 6, 7, 9, 10, 5, 5, 5, 5)) >>> s.rolling(3).var(1) 0 NaN 1 NaN @@ -930,6 +928,20 @@ def f(arg, *args, **kwargs): 10 0.000000 11 0.000000 dtype: float64 + >>> s.expanding(3).var(1) + 0 NaN + 1 NaN + 2 0.000000 + 3 0.000000 + 4 0.200000 + 5 0.700000 + 6 2.333333 + 7 4.000000 + 8 3.750000 + 9 3.511111 + 10 3.290909 + 11 3.090909 + dtype: float64 """) def var(self, ddof=1, *args, **kwargs): From 1dded7cfc29d9ce3f3246326ded6d8b420705989 Mon Sep 17 00:00:00 2001 From: Matt Maybeno Date: Sun, 11 Mar 2018 07:56:08 -0700 Subject: [PATCH 4/5] Addressing comments 2 --- pandas/core/window.py | 52 +++++++++++++++++++------------------------ 1 file changed, 23 insertions(+), 29 deletions(-) diff --git a/pandas/core/window.py b/pandas/core/window.py index a918f5d6895a7..7de18bd41c743 100644 --- a/pandas/core/window.py +++ b/pandas/core/window.py @@ -896,8 +896,8 @@ def f(arg, *args, **kwargs): Returns ------- - Returns the same object type as determined by the caller of the %(name)s - calculation. + Series or DataFrame + Returns the same object type as the caller of the %(name)s calculation. See Also -------- @@ -909,38 +909,32 @@ def f(arg, *args, **kwargs): Notes ----- + The default `ddof` of 1 used in Series.var is different than the default + `ddof` of 0 in numpy.var. + A minimum of 1 periods is required for the rolling calculation. Examples -------- - >>> 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 + >>> s = pd.Series([5, 5, 6, 7, 5, 5, 5]) + >>> s.rolling(3).var() + 0 NaN + 1 NaN + 2 0.333333 + 3 1.000000 + 4 1.000000 + 5 1.333333 + 6 0.000000 dtype: float64 - >>> s.expanding(3).var(1) - 0 NaN - 1 NaN - 2 0.000000 - 3 0.000000 - 4 0.200000 - 5 0.700000 - 6 2.333333 - 7 4.000000 - 8 3.750000 - 9 3.511111 - 10 3.290909 - 11 3.090909 + + >>> s.expanding(3).var() + 0 NaN + 1 NaN + 2 0.333333 + 3 0.916667 + 4 0.800000 + 5 0.700000 + 6 0.619048 dtype: float64 """) From 8de2598848361e2dcfa97fe9570b2972a1803ef8 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Sun, 11 Mar 2018 10:02:42 -0500 Subject: [PATCH 5/5] args, kwargs --- pandas/core/window.py | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/pandas/core/window.py b/pandas/core/window.py index 7de18bd41c743..40b94d2fe2507 100644 --- a/pandas/core/window.py +++ b/pandas/core/window.py @@ -889,10 +889,8 @@ def f(arg, *args, **kwargs): 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. + *args, **kwargs + For NumPy compatibility. No additional arguments are used. Returns ------- @@ -909,10 +907,10 @@ def f(arg, *args, **kwargs): Notes ----- - The default `ddof` of 1 used in Series.var is different than the default - `ddof` of 0 in numpy.var. + The default `ddof` of 1 used in :meth:`Series.var` is different than the + default `ddof` of 0 in :func:`numpy.var`. - A minimum of 1 periods is required for the rolling calculation. + A minimum of 1 period is required for the rolling calculation. Examples --------