Skip to content

DOC: update the pandas.DataFrame.cummax docstring #20336

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.

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 23 commits into from
Mar 17, 2018
Merged
Changes from 1 commit
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
5ccedc2
DOC: Improve the docstring of DataFrame.cummax
arminv Mar 13, 2018
04f70dd
Merge remote-tracking branch 'upstream/master' into docstring_cummax
arminv Mar 13, 2018
aec6084
Merge remote-tracking branch 'upstream/master' into docstring_cummax
arminv Mar 13, 2018
4acf753
DOC: Improve the docstring of DataFrame.cummax()
arminv Mar 13, 2018
1214c93
DOC: Improve the docstring of pandas.DataFrame.cummax
arminv Mar 13, 2018
a88e95a
Merge remote-tracking branch 'upstream/master' into docstring_cummax
arminv Mar 14, 2018
fe94dad
DOC: Improve the docstring of DataFrame.cummax
arminv Mar 14, 2018
f73b52f
Merge remote-tracking branch 'upstream/master' into docstring_cummax
arminv Mar 14, 2018
33e5337
Merge remote-tracking branch 'upstream/master' into docstring_cummax
arminv Mar 15, 2018
15b38dd
Merge remote-tracking branch 'upstream/master' into docstring_cummax
arminv Mar 15, 2018
3c30d18
Improved examples
arminv Mar 16, 2018
0cb3168
Merge remote-tracking branch 'upstream/master' into docstring_cummax
arminv Mar 16, 2018
9d46623
Addressed PEP8 issues
arminv Mar 16, 2018
5d502cb
Addressed PEP 8 issues
arminv Mar 16, 2018
e1e190f
Merge remote-tracking branch 'upstream/master' into docstring_cummax
arminv Mar 17, 2018
aa34ea0
Made See also of Series consistent
arminv Mar 17, 2018
94fc1b3
Merge remote-tracking branch 'upstream/master' into docstring_cummax
arminv Mar 17, 2018
657feac
Merge remote-tracking branch 'upstream/master' into docstring_cummax
arminv Mar 17, 2018
77789a8
Improved example wording. Addressed PEP8
arminv Mar 17, 2018
463eef7
Merge remote-tracking branch 'upstream/master' into docstring_cummax
arminv Mar 17, 2018
b03c32a
More templating in See also.Fixed typos
arminv Mar 17, 2018
9b05313
Merge remote-tracking branch 'upstream/master' into docstring_cummax
arminv Mar 17, 2018
1147a0d
Improved templating of See also section
arminv Mar 17, 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
Prev Previous commit
Next Next commit
More templating in See also.Fixed typos
  • Loading branch information
arminv committed Mar 17, 2018
commit b03c32acce04a735d2d32bef123cc8542adf4683
29 changes: 15 additions & 14 deletions pandas/core/generic.py
Original file line number Diff line number Diff line change
Expand Up @@ -8487,19 +8487,19 @@ def compound(self, axis=None, skipna=None, level=None):
cls.compound = compound

cls.cummin = _make_cum_function(
cls, 'cummin', name, name2, axis_descr, "cumulative minimum",
cls, 'cummin', name, name2, axis_descr, "minimum",
lambda y, axis: np.minimum.accumulate(y, axis), "min",
np.inf, np.nan, _cummin_examples)
cls.cumsum = _make_cum_function(
cls, 'cumsum', name, name2, axis_descr, "cumulative sum",
cls, 'cumsum', name, name2, axis_descr, "sum",
lambda y, axis: y.cumsum(axis), "sum", 0.,
np.nan, _cumsum_examples)
cls.cumprod = _make_cum_function(
cls, 'cumprod', name, name2, axis_descr, "cumulative product",
cls, 'cumprod', name, name2, axis_descr, "product",
lambda y, axis: y.cumprod(axis), "prod", 1.,
np.nan, _cumprod_examples)
cls.cummax = _make_cum_function(
cls, 'cummax', name, name2, axis_descr, "cumulative maximum",
cls, 'cummax', name, name2, axis_descr, "maximum",
lambda y, axis: np.maximum.accumulate(y, axis), "max",
-np.inf, np.nan, _cummax_examples)

Expand Down Expand Up @@ -8763,9 +8763,10 @@ def _doc_parms(cls):
"""

_cnum_doc = """
Return %(desc)s over a DataFrame or Series axis.
Return cumulative %(desc)s over a DataFrame or Series axis.

Returns a DataFrame or Series of the same size containing the %(desc)s.
Returns a DataFrame or Series of the same size containing the cumulative
%(desc)s.

Parameters
----------
Expand All @@ -8786,8 +8787,8 @@ def _doc_parms(cls):
--------
pandas.core.window.Expanding.%(accum_func_name)s : Similar functionality
but ignores ``NaN`` values.
Series.%(outname)s : Return %(desc)s over Series axis.
%(name2)s.%(accum_func_name)s : Return the %(accum_func_name)s over
Series.%(outname)s : Return cumulative %(desc)s over Series axis.
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 this one can be left out, as it will already be included in one of the 4 last ones.

%(name2)s.%(accum_func_name)s : Return the %(desc)s over
%(name2)s axis.
DataFrame.cummax : Return cumulative maximum over DataFrame axis.
Copy link
Contributor Author

@arminv arminv Mar 15, 2018

Choose a reason for hiding this comment

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

@datapythonista @jorisvandenbossche Is it a good idea to also add: DataFrame.sum as a relevant method in the 'See also' section?

Copy link
Member

Choose a reason for hiding this comment

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

Yes, that might be a good idea, if you can automatically make it link in DataFrame.cumsum to DataFrame.sum, in DataFrame.cummin to DataFrame.min, etc (using the templating)

Copy link
Member

Choose a reason for hiding this comment

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

This also %(name2)s like below ?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

If I implement these changes, we won't get a reference to any corresponding Series in 'See also' of DataFrame methods and vice versa. That's why I left them like this (at the expense of repeating one of them).

I agree that we don't really need them because we have examples of both Series & DataFrame in all docstrings and this should be informative enough.

Just out of curiosity, is there a simple way to determine whether a Series or DataFrame method is being accessed at any one time? For example, if we were generating the doc for Series.cummax, we would determine it is a Series method. Based on this, we know that we need to show cummax but for a DataFrame.

Copy link
Member

Choose a reason for hiding this comment

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

The thing is that the docstring for both Series and DataFrame (of the same method) will be exactly the same (apart from some of the links here in see also). So linking to the same method but on the other object, is not that important I think, as the other one does not give you more information

Just out of curiosity, is there a simple way to determine whether a Series or DataFrame method is being accessed at any one time? For example, if we were generating the doc for Series.cummax, we would determine it is a Series method. Based on this, we know that we need to show cummax but for a DataFrame.

Yes, the cls that is passed to _make_cum_function is either the Series or DataFrame class. So you can pass cls.__name__ as a variable to the template, but I think this is already done as name2 ? Based on that you can know the other.

%(name2)s.cummin : Return cumulative minimum over %(name2)s axis.
Expand Down Expand Up @@ -8906,7 +8907,7 @@ def _doc_parms(cls):
1 3.0 NaN
2 1.0 0.0

By default, iterates over rows and finds the minimum
By default, iterates over rows and finds the sum
in each column. This is equivalent to ``axis=None`` or ``axis='index'``.

>>> df.cumsum()
Expand All @@ -8915,7 +8916,7 @@ def _doc_parms(cls):
1 5.0 NaN
2 6.0 1.0

To iterate over columns and find the minimum in each row,
To iterate over columns and find the sum in each row,
use ``axis=1``

>>> df.cumsum(axis=1)
Expand Down Expand Up @@ -8971,7 +8972,7 @@ def _doc_parms(cls):
1 3.0 NaN
2 1.0 0.0

By default, iterates over rows and finds the minimum
By default, iterates over rows and finds the product
in each column. This is equivalent to ``axis=None`` or ``axis='index'``.

>>> df.cumprod()
Expand All @@ -8980,7 +8981,7 @@ def _doc_parms(cls):
1 6.0 NaN
2 6.0 0.0

To iterate over columns and find the minimum in each row,
To iterate over columns and find the product in each row,
use ``axis=1``

>>> df.cumprod(axis=1)
Expand Down Expand Up @@ -9036,7 +9037,7 @@ def _doc_parms(cls):
1 3.0 NaN
2 1.0 0.0

By default, iterates over rows and finds the minimum
By default, iterates over rows and finds the maximum
in each column. This is equivalent to ``axis=None`` or ``axis='index'``.

>>> df.cummax()
Expand All @@ -9045,7 +9046,7 @@ def _doc_parms(cls):
1 3.0 NaN
2 3.0 1.0

To iterate over columns and find the minimum in each row,
To iterate over columns and find the maximum in each row,
use ``axis=1``

>>> df.cummax(axis=1)
Expand Down