Skip to content

DOC: Updated kurt docstring (for pandas sprint) #19999

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 6 commits into from
Mar 7, 2018
Merged

DOC: Updated kurt docstring (for pandas sprint) #19999

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
101f14a
Updated kurt docstring (for pandas sprint)
WillAyd Mar 5, 2018
38e5787
Fixed docstr indentation
WillAyd Mar 5, 2018
a2bde20
Fixed error called out by validation script
WillAyd Mar 5, 2018
1151e10
Merge remote-tracking branch 'upstream/master' into kurt-docstr
WillAyd Mar 6, 2018
61dff85
Updated kurt docstring
WillAyd Mar 6, 2018
dd61858
Stylistic updates
WillAyd Mar 6, 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
Next Next commit
Updated kurt docstring (for pandas sprint)
  • Loading branch information
@WillAyd
WillAyd committed Mar 5, 2018
commit 101f14a9fe74425de128288d261e68471f633609
42 changes: 37 additions & 5 deletions pandas/core/window.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -899,11 +899,45 @@ def skew(self, **kwargs):
return self._apply('roll_skew', 'skew',
check_minp=_require_min_periods(3), **kwargs)

_shared_docs['kurt'] = """Unbiased %(name)s kurtosis"""
_shared_docs['kurt'] = dedent("""Calculate unbiased %(name)s kurtosis.

def kurt(self, **kwargs):
This function uses Fisher's definition of kurtosis (kurtosis of normal
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 by using dedent, you can actually keep this indented (so it doesn't look that 'off' inside the class)

(I am not even sure the dedent is needed, as there are many places where we don't use it, but that is something else)

Copy link
Member Author

Choose a reason for hiding this comment

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

Yep mistake on initial push. Subsequently indented in the next push

== 0.0) without bias.
Copy link
Member

Choose a reason for hiding this comment

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

I know this is copied from the DataFrame/Series one, but I personally don't find "kurtosis of normal == 0.0" very clear. I suppose it is about a normal distribution having a kurtosis of 0.0 ?


Returns
-------
same type as input
Copy link
Member

Choose a reason for hiding this comment

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

Again, I know this was already there ..:) But I also find this not very clear. What is the "input"? As I didn't provide anything to the function .. (it's rather the object calling rolling)

But not directly sure how to document this very well. Maybe just "Series/DataFrame" (depending on the calling object)

Copy link
Member Author

Choose a reason for hiding this comment

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

So when I did this originally I had:

Series or DataFrame
    Like-indexed object containing the result of the kurt operation

However, I ended up with the above because all of the other rolling / expanding functions used this in the _doc_template variable (linked below). We could either break that consistency or update the _doc_template variable to reflect the above (perhaps substituting kurt for %(name)) if we think that's a better generally applicable description

pandas/pandas/core/window.py

Line 51 in aedbd94

same type as input

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 we should break the consistency for now, with the idea that if all those docstrings get updated during the sprint, we should strive again for consistency with the new wording?

Or indeed already update the template, then it is changed for all as well.

In any case I think we should try to make the docstring that you are now editing, as good as possible.


See Also
--------
scipy.stats.kurtosis
pandas.DataFrame.kurtosis
pandas.Series.kurtosis

Notes
-----
A minimum of 4 periods is required for the rolling calculation
Copy link
Member

Choose a reason for hiding this comment

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

period at and


Examples
--------
>>> arr = [1, 2, 3, 4, 5]
>>> import scipy.stats
>>> scipy.stats.kurtosis(arr, bias=False)
-1.200000000000000

>>> df = pd.DataFrame(arr)
Copy link
Member

Choose a reason for hiding this comment

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

Can you put a small explanation? Very dummy saying what the example is doing

>>> df.rolling(5).kurt()
0
0 NaN
1 NaN
2 NaN
3 NaN
4 -1.2
""")

def kurt(self):
return self._apply('roll_kurt', 'kurt',
check_minp=_require_min_periods(4), **kwargs)
check_minp=_require_min_periods(4))

_shared_docs['quantile'] = dedent("""
%(name)s quantile
Expand Down Expand Up @@ -1221,7 +1255,6 @@ def skew(self, **kwargs):
return super(Rolling, self).skew(**kwargs)

@Substitution(name='rolling')
@Appender(_doc_template)
@Appender(_shared_docs['kurt'])
def kurt(self, **kwargs):
return super(Rolling, self).kurt(**kwargs)
Expand Down Expand Up @@ -1461,7 +1494,6 @@ def skew(self, **kwargs):
return super(Expanding, self).skew(**kwargs)

@Substitution(name='expanding')
@Appender(_doc_template)
@Appender(_shared_docs['kurt'])
def kurt(self, **kwargs):
return super(Expanding, self).kurt(**kwargs)
Expand Down