From 5ccedc29c38898ed61f7c4ec6707317594525ce4 Mon Sep 17 00:00:00 2001 From: arminv Date: Tue, 13 Mar 2018 15:19:10 -0400 Subject: [PATCH 01/11] DOC: Improve the docstring of DataFrame.cummax --- pandas/core/generic.py | 39 +++++++++++++++++++++++++++------------ 1 file changed, 27 insertions(+), 12 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 86ac1b031a6e2..1b7e318d5d428 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7971,17 +7971,17 @@ def compound(self, axis=None, skipna=None, level=None): cls.cummin = _make_cum_function( cls, 'cummin', name, name2, axis_descr, "cumulative minimum", lambda y, axis: np.minimum.accumulate(y, axis), "min", - np.inf, np.nan) + np.inf, np.nan, '') cls.cumsum = _make_cum_function( cls, 'cumsum', name, name2, axis_descr, "cumulative sum", - lambda y, axis: y.cumsum(axis), "sum", 0., np.nan) + lambda y, axis: y.cumsum(axis), "sum", 0., np.nan, '') cls.cumprod = _make_cum_function( cls, 'cumprod', name, name2, axis_descr, "cumulative product", - lambda y, axis: y.cumprod(axis), "prod", 1., np.nan) + lambda y, axis: y.cumprod(axis), "prod", 1., np.nan, '') cls.cummax = _make_cum_function( - cls, 'cummax', name, name2, axis_descr, "cumulative max", + cls, 'cummax', name, name2, axis_descr, "cumulative maximum", lambda y, axis: np.maximum.accumulate(y, axis), "max", - -np.inf, np.nan) + -np.inf, np.nan, _cummax_examples) cls.sum = _make_min_count_stat_function( cls, 'sum', name, name2, axis_descr, @@ -8243,24 +8243,39 @@ def _doc_parms(cls): """ _cnum_doc = """ +Return %(desc)s over requested axis. + +Return %(desc)s over a DataFrame or Series axis. +axis=0 iterates over rows. +axis=1 iterates over columns. Parameters ---------- axis : %(axis_descr)s skipna : boolean, default True Exclude NA/null values. If an entire row/column is NA, the result - will be NA + will be NA. +*args : any, default None +**kwargs : any, default None + Additional keywords have no effect but might be accepted for + compatibility with NumPy. Returns ------- %(outname)s : %(name1)s\n - - +%(examples)s See also -------- pandas.core.window.Expanding.%(accum_func_name)s : Similar functionality but ignores ``NaN`` values. +pandas.Series.%(outname)s : Return %(desc)s over Series axis. +pandas.DataFrame.cummax : Return cumulative maximum over DataFrame axis. +pandas.DataFrame.cummin : Return cumulative minimum over DataFrame axis. +pandas.DataFrame.cumsum : Return cumulative sum over DataFrame axis. +pandas.DataFrame.cumprod : Return cumulative product over DataFrame axis. +""" +_cummax_examples = """\ """ _any_see_also = """\ @@ -8457,11 +8472,11 @@ def stat_func(self, axis=None, skipna=None, level=None, ddof=1, def _make_cum_function(cls, name, name1, name2, axis_descr, desc, - accum_func, accum_func_name, mask_a, mask_b): + accum_func, accum_func_name, mask_a, mask_b, examples): @Substitution(outname=name, desc=desc, name1=name1, name2=name2, - axis_descr=axis_descr, accum_func_name=accum_func_name) - @Appender("Return {0} over requested axis.".format(desc) + - _cnum_doc) + axis_descr=axis_descr, accum_func_name=accum_func_name, + examples = examples) + @Appender(_cnum_doc) def cum_func(self, axis=None, skipna=True, *args, **kwargs): skipna = nv.validate_cum_func_with_skipna(skipna, args, kwargs, name) if axis is None: From 4acf753ce5bb8b5208bd18bd62cdbc6642fea2a6 Mon Sep 17 00:00:00 2001 From: arminv Date: Tue, 13 Mar 2018 16:13:14 -0400 Subject: [PATCH 02/11] DOC: Improve the docstring of DataFrame.cummax() --- pandas/core/generic.py | 64 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 60 insertions(+), 4 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 6fc0ca0c89637..695b741dd400b 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8327,11 +8327,9 @@ def _doc_parms(cls): """ _cnum_doc = """ -Return %(desc)s over requested axis. - Return %(desc)s over a DataFrame or Series axis. -axis=0 iterates over rows. -axis=1 iterates over columns. + +Returns a DataFrame or Series of the same size containing the %(desc)s. Parameters ---------- @@ -8360,6 +8358,64 @@ def _doc_parms(cls): """ _cummax_examples = """\ +Examples +-------- +**DataFrame** + +Create a DataFrame: + +>>> df = pd.DataFrame([[9, 7, 9, 7], +... [7, 5, 2, 7], +... [3, 5, 2, 2], +... [8, 0, 9, 0]], +... columns=list('ABCD')) +>>> df + A B C D +0 9 7 9 7 +1 7 5 2 7 +2 3 5 2 2 +3 8 0 9 0 + +axis=None : Iterates over rows and finds the maximum value in each column. +If value is larger than the previous maximum, updates it: + +>>> df.cummax(axis=None) + A B C D +0 9 7 9 7 +1 9 7 9 7 +2 9 7 9 7 +3 9 7 9 7 + +axis=1 : Iterates over columns and finds the maximum value in each row. +If value is larger than the previous maximum, updates it: + +>>> df.cummax(axis=1) + A B C D +0 9 9 9 9 +1 7 7 7 7 +2 3 5 5 5 +3 8 8 9 9 + +**Series** + +Create a Series: + +>>> s = pd.Series([5,0,-5,10,-10]) +>>> s +0 5 +1 0 +2 -5 +3 10 +4 -10 +dtype: int64 + +>>> s.cummax() +0 5 +1 5 +2 5 +3 10 +4 10 +dtype: int64 """ _any_see_also = """\ From 1214c93174959fe1630c3e2260770c616e4aae0d Mon Sep 17 00:00:00 2001 From: arminv Date: Tue, 13 Mar 2018 16:22:17 -0400 Subject: [PATCH 03/11] DOC: Improve the docstring of pandas.DataFrame.cummax --- pandas/core/generic.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 695b741dd400b..bfb7240df8206 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8339,8 +8339,8 @@ def _doc_parms(cls): will be NA. *args : any, default None **kwargs : any, default None - Additional keywords have no effect but might be accepted for - compatibility with NumPy. + Additional keywords have no effect but might be accepted for + compatibility with NumPy. Returns ------- @@ -8615,7 +8615,7 @@ def _make_cum_function(cls, name, name1, name2, axis_descr, desc, accum_func, accum_func_name, mask_a, mask_b, examples): @Substitution(outname=name, desc=desc, name1=name1, name2=name2, axis_descr=axis_descr, accum_func_name=accum_func_name, - examples = examples) + examples=examples) @Appender(_cnum_doc) def cum_func(self, axis=None, skipna=True, *args, **kwargs): skipna = nv.validate_cum_func_with_skipna(skipna, args, kwargs, name) From fe94dad6e92f5e06271d3bd00362a66b2e76fae1 Mon Sep 17 00:00:00 2001 From: arminv Date: Wed, 14 Mar 2018 06:18:41 -0400 Subject: [PATCH 04/11] DOC: Improve the docstring of DataFrame.cummax --- pandas/core/generic.py | 207 ++++++++++++++++++++++++++++++----------- 1 file changed, 155 insertions(+), 52 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 7a2a3e041e4c3..0711c4c13e4f2 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8524,28 +8524,28 @@ def _doc_parms(cls): Parameters ---------- -axis : %(axis_descr)s +axis : {0 or 'index', 1 or 'columns'}, default 0 skipna : boolean, default True Exclude NA/null values. If an entire row/column is NA, the result will be NA. -*args : any, default None -**kwargs : any, default None +*args : default None +**kwargs : default None Additional keywords have no effect but might be accepted for compatibility with NumPy. Returns ------- -%(outname)s : %(name1)s\n +%(outname)s : %(name1)s or %(name2)s\n %(examples)s See also -------- -pandas.core.window.Expanding.%(accum_func_name)s : Similar functionality +core.window.Expanding.%(accum_func_name)s : Similar functionality but ignores ``NaN`` values. -pandas.Series.%(outname)s : Return %(desc)s over Series axis. -pandas.DataFrame.cummax : Return cumulative maximum over DataFrame axis. -pandas.DataFrame.cummin : Return cumulative minimum over DataFrame axis. -pandas.DataFrame.cumsum : Return cumulative sum over DataFrame axis. -pandas.DataFrame.cumprod : Return cumulative product over DataFrame axis. +Series.%(outname)s : Return %(desc)s over Series axis. +DataFrame.cummax : Return cumulative maximum over DataFrame axis. +DataFrame.cummin : Return cumulative minimum over DataFrame axis. +DataFrame.cumsum : Return cumulative sum over DataFrame axis. +DataFrame.cumprod : Return cumulative product over DataFrame axis. """ _cummax_examples = """\ @@ -8553,60 +8553,163 @@ def _doc_parms(cls): -------- **DataFrame** -Create a DataFrame: - ->>> df = pd.DataFrame([[9, 7, 9, 7], -... [7, 5, 2, 7], -... [3, 5, 2, 2], -... [8, 0, 9, 0]], -... columns=list('ABCD')) +>>> df = pd.DataFrame([[7, 1], +... [3, 4], +... [8, 0]], +... columns=list('AB')) >>> df - A B C D -0 9 7 9 7 -1 7 5 2 7 -2 3 5 2 2 -3 8 0 9 0 + A B +0 7 1 +1 3 4 +2 8 0 -axis=None : Iterates over rows and finds the maximum value in each column. -If value is larger than the previous maximum, updates it: +**axis** ->>> df.cummax(axis=None) - A B C D -0 9 7 9 7 -1 9 7 9 7 -2 9 7 9 7 -3 9 7 9 7 +axis=None : Iterates over rows and finds the cumulative value in each column. +If value is different from the previous one, updates it: -axis=1 : Iterates over columns and finds the maximum value in each row. -If value is larger than the previous maximum, updates it: +>>> df.cummax(axis=None) + A B +0 7 1 +1 7 4 +2 8 4 +>>> df.cummin(axis=None) + A B +0 7 1 +1 3 1 +2 3 0 +>>> df.cumsum(axis=None) + A B +0 7 1 +1 10 5 +2 18 5 +>>> df.cumprod(axis=None) + A B +0 7 1 +1 21 4 +2 168 0 + +axis=1 : Iterates over columns and finds the cumulative value in each row. +If value is different from the previous one, updates it: >>> df.cummax(axis=1) - A B C D -0 9 9 9 9 -1 7 7 7 7 -2 3 5 5 5 -3 8 8 9 9 + A B +0 7 7 +1 3 4 +2 8 8 +>>> df.cummin(axis=1) + A B +0 7 1 +1 3 3 +2 8 0 +>>> df.cumsum(axis=1) + A B +0 7 8 +1 3 7 +2 8 8 +>>> df.cumprod(axis=1) + A B +0 7 7 +1 3 12 +2 8 0 + +**skipna** + +skipna=True : Ignores NaN values during operation: + +>>> df = pd.DataFrame([[7, np.nan], +... [np.nan, 4], +... [8, 0]], +... columns=list('AB')) +>>> df + A B +0 7.0 NaN +1 NaN 4.0 +2 8.0 0.0 + +>>> df.cummax(skipna=True) + A B +0 7.0 NaN +1 NaN 4.0 +2 8.0 4.0 +>>> df.cummin(skipna=True) + A B +0 7.0 NaN +1 NaN 4.0 +2 7.0 0.0 +>>> df.cumsum(skipna=True) + A B +0 7.0 NaN +1 NaN 4.0 +2 15.0 4.0 +>>> df.cumprod(skipna=True) + A B +0 7.0 NaN +1 NaN 4.0 +2 56.0 0.0 + +skipna=False : Includes NaN values: + +>>> df.cummax(skipna=False) + A B +0 7.0 NaN +1 NaN NaN +2 NaN NaN +>>> df.cummin(skipna=False) + A B +0 7.0 NaN +1 NaN NaN +2 NaN NaN +>>> df.cumsum(skipna=False) + A B +0 7.0 NaN +1 NaN NaN +2 NaN NaN +>>> df.cumprod(skipna=False) + A B +0 7.0 NaN +1 NaN NaN +2 NaN NaN **Series** -Create a Series: - ->>> s = pd.Series([5,0,-5,10,-10]) +>>> s = pd.Series([2,np.nan,5,0,-1]) >>> s -0 5 -1 0 -2 -5 -3 10 -4 -10 -dtype: int64 +0 2.0 +1 NaN +2 5.0 +3 0.0 +4 -1.0 +dtype: float64 >>> s.cummax() -0 5 -1 5 -2 5 -3 10 -4 10 -dtype: int64 +0 2.0 +1 NaN +2 5.0 +3 5.0 +4 5.0 +dtype: float64 +>>> s.cummin() +0 2.0 +1 NaN +2 2.0 +3 0.0 +4 -1.0 +dtype: float64 +>>> s.cumsum() +0 2.0 +1 NaN +2 7.0 +3 7.0 +4 6.0 +dtype: float64 +>>> s.cumprod() +0 2.0 +1 NaN +2 10.0 +3 0.0 +4 -0.0 +dtype: float64 """ _any_see_also = """\ From 3c30d181618e2d3c4599afd44ee9f42a67373534 Mon Sep 17 00:00:00 2001 From: arminv Date: Fri, 16 Mar 2018 15:18:24 -0400 Subject: [PATCH 05/11] Improved examples --- pandas/core/generic.py | 365 ++++++++++++++++++++++++++--------------- 1 file changed, 234 insertions(+), 131 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index f48d4ec6469cc..b8d9046d1d629 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8283,13 +8283,13 @@ def compound(self, axis=None, skipna=None, level=None): cls.cummin = _make_cum_function( cls, 'cummin', name, name2, axis_descr, "cumulative minimum", lambda y, axis: np.minimum.accumulate(y, axis), "min", - np.inf, np.nan, '') + np.inf, np.nan, _cummin_examples) cls.cumsum = _make_cum_function( cls, 'cumsum', name, name2, axis_descr, "cumulative sum", - lambda y, axis: y.cumsum(axis), "sum", 0., np.nan, '') + 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", - lambda y, axis: y.cumprod(axis), "prod", 1., np.nan, '') + 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", lambda y, axis: np.maximum.accumulate(y, axis), "max", @@ -8562,13 +8562,11 @@ def _doc_parms(cls): Parameters ---------- axis : {0 or 'index', 1 or 'columns'}, default 0 + The index or the name of the axis. 0 is equivalent to None or 'index'. skipna : boolean, default True Exclude NA/null values. If an entire row/column is NA, the result will be NA. -*args : default None -**kwargs : default None - Additional keywords have no effect but might be accepted for - compatibility with NumPy. +*args, **kwargs Returns ------- @@ -8576,149 +8574,232 @@ def _doc_parms(cls): %(examples)s See also -------- -core.window.Expanding.%(accum_func_name)s : Similar functionality +pandas.core.window.Expanding.%(accum_func_name)s : Similar functionality but ignores ``NaN`` values. Series.%(outname)s : Return %(desc)s over Series axis. +DataFrame.%(accum_func_name)s : Return the %(accum_func_name)s of values over DataFrame axis. DataFrame.cummax : Return cumulative maximum over DataFrame axis. DataFrame.cummin : Return cumulative minimum over DataFrame axis. DataFrame.cumsum : Return cumulative sum over DataFrame axis. DataFrame.cumprod : Return cumulative product over DataFrame axis. """ -_cummax_examples = """\ +_cummin_examples = """\ Examples -------- +**Series** + +>>> s = pd.Series([2,np.nan,5,-1,0]) +>>> s +0 2.0 +1 NaN +2 5.0 +3 -1.0 +4 0.0 +dtype: float64 + +skipna=True : Default value, ignores NaN values during operation: + +>>> s.cummin() +0 2.0 +1 NaN +2 2.0 +3 -1.0 +4 -1.0 +dtype: float64 + +skipna=False : Includes NaN values: + +>>> s.cummin(skipna=False) +0 2.0 +1 NaN +2 NaN +3 NaN +4 NaN +dtype: float64 + **DataFrame** ->>> df = pd.DataFrame([[7, 1], -... [3, 4], -... [8, 0]], +>>> df = pd.DataFrame([[2.0, 1.0], +... [3.0, np.nan], +... [1.0, 0.0]], ... columns=list('AB')) >>> df - A B -0 7 1 -1 3 4 -2 8 0 - -**axis** - -axis=None : Iterates over rows and finds the cumulative value in each column. -If value is different from the previous one, updates it: - ->>> df.cummax(axis=None) - A B -0 7 1 -1 7 4 -2 8 4 ->>> df.cummin(axis=None) - A B -0 7 1 -1 3 1 -2 3 0 ->>> df.cumsum(axis=None) - A B -0 7 1 -1 10 5 -2 18 5 ->>> df.cumprod(axis=None) - A B -0 7 1 -1 21 4 -2 168 0 - -axis=1 : Iterates over columns and finds the cumulative value in each row. -If value is different from the previous one, updates it: + A B +0 2.0 1.0 +1 3.0 NaN +2 1.0 0.0 + +skipna : Works in the same way as for Series. + +axis=0 : Default value, equivalent to axis=None or axis='index'. +Iterates over rows and finds the minimum in each column. +If value is smaller than the previous one, updates it: + +>>> df.cummin() + A B +0 2.0 1.0 +1 2.0 NaN +2 1.0 0.0 + +axis=1 : Iterates over columns and finds the minimum in each row. +If value is smaller than the previous one, updates it: ->>> df.cummax(axis=1) - A B -0 7 7 -1 3 4 -2 8 8 >>> df.cummin(axis=1) - A B -0 7 1 -1 3 3 -2 8 0 ->>> df.cumsum(axis=1) - A B -0 7 8 -1 3 7 -2 8 8 ->>> df.cumprod(axis=1) - A B -0 7 7 -1 3 12 -2 8 0 + A B +0 2.0 1.0 +1 3.0 NaN +2 1.0 0.0 +""" -**skipna** +_cumsum_examples = """\ +Examples +-------- +**Series** + +>>> s = pd.Series([2,np.nan,5,-1,0]) +>>> s +0 2.0 +1 NaN +2 5.0 +3 -1.0 +4 0.0 +dtype: float64 + +skipna=True : Default value, ignores NaN values during operation: + +>>> s.cumsum() +0 2.0 +1 NaN +2 7.0 +3 6.0 +4 6.0 +dtype: float64 + +skipna=False : Includes NaN values: -skipna=True : Ignores NaN values during operation: +>>> s.cumsum(skipna=False) +0 2.0 +1 NaN +2 NaN +3 NaN +4 NaN +dtype: float64 ->>> df = pd.DataFrame([[7, np.nan], -... [np.nan, 4], -... [8, 0]], +**DataFrame** + +>>> df = pd.DataFrame([[2.0, 1.0], +... [3.0, np.nan], +... [1.0, 0.0]], ... columns=list('AB')) >>> df A B -0 7.0 NaN -1 NaN 4.0 -2 8.0 0.0 +0 2.0 1.0 +1 3.0 NaN +2 1.0 0.0 + +skipna : Works in the same way as for Series. ->>> df.cummax(skipna=True) +axis=0 : Default value, equivalent to axis=None or axis='index'. +Iterates over rows and finds the cumulative sum of values in each column. + +>>> df.cumsum() A B -0 7.0 NaN -1 NaN 4.0 -2 8.0 4.0 ->>> df.cummin(skipna=True) +0 2.0 1.0 +1 5.0 NaN +2 6.0 1.0 + +axis=1 : Iterates over columns and finds the cumulative sum of values in each row. + +>>> df.cumsum(axis=1) A B -0 7.0 NaN -1 NaN 4.0 -2 7.0 0.0 ->>> df.cumsum(skipna=True) - A B -0 7.0 NaN -1 NaN 4.0 -2 15.0 4.0 ->>> df.cumprod(skipna=True) - A B -0 7.0 NaN -1 NaN 4.0 -2 56.0 0.0 +0 2.0 3.0 +1 3.0 NaN +2 1.0 1.0 +""" + +_cumprod_examples = """\ +Examples +-------- +**Series** + +>>> s = pd.Series([2,np.nan,5,-1,0]) +>>> s +0 2.0 +1 NaN +2 5.0 +3 -1.0 +4 0.0 +dtype: float64 + +skipna=True : Default value, ignores NaN values during operation: + +>>> s.cumprod() +0 2.0 +1 NaN +2 10.0 +3 -10.0 +4 -0.0 +dtype: float64 skipna=False : Includes NaN values: ->>> df.cummax(skipna=False) - A B -0 7.0 NaN -1 NaN NaN -2 NaN NaN ->>> df.cummin(skipna=False) - A B -0 7.0 NaN -1 NaN NaN -2 NaN NaN ->>> df.cumsum(skipna=False) - A B -0 7.0 NaN -1 NaN NaN -2 NaN NaN ->>> df.cumprod(skipna=False) - A B -0 7.0 NaN -1 NaN NaN -2 NaN NaN +>>> s.cumprod(skipna=False) +0 2.0 +1 NaN +2 NaN +3 NaN +4 NaN +dtype: float64 + +**DataFrame** + +>>> df = pd.DataFrame([[2.0, 1.0], +... [3.0, np.nan], +... [1.0, 0.0]], +... columns=list('AB')) +>>> df + A B +0 2.0 1.0 +1 3.0 NaN +2 1.0 0.0 + +skipna : Works in the same way as for Series. + +axis=0 : Default value, equivalent to axis=None or axis='index'. +Iterates over rows and finds the cumulative product of values in each column. + +>>> df.cumprod() + A B +0 2.0 1.0 +1 6.0 NaN +2 6.0 0.0 +axis=1 : Iterates over columns and finds the cumulative product of values in each row. + +>>> df.cumprod(axis=1) + A B +0 2.0 2.0 +1 3.0 NaN +2 1.0 0.0 +""" + +_cummax_examples = """\ +Examples +-------- **Series** ->>> s = pd.Series([2,np.nan,5,0,-1]) +>>> s = pd.Series([2,np.nan,5,-1,0]) >>> s 0 2.0 1 NaN 2 5.0 -3 0.0 -4 -1.0 +3 -1.0 +4 0.0 dtype: float64 +skipna=True : Default value, ignores NaN values during operation: + >>> s.cummax() 0 2.0 1 NaN @@ -8726,27 +8807,49 @@ def _doc_parms(cls): 3 5.0 4 5.0 dtype: float64 ->>> s.cummin() -0 2.0 -1 NaN -2 2.0 -3 0.0 -4 -1.0 -dtype: float64 ->>> s.cumsum() + +skipna=False : Includes NaN values: + +>>> s.cummax(skipna=False) 0 2.0 1 NaN -2 7.0 -3 7.0 -4 6.0 -dtype: float64 ->>> s.cumprod() -0 2.0 -1 NaN -2 10.0 -3 0.0 -4 -0.0 +2 NaN +3 NaN +4 NaN dtype: float64 + +**DataFrame** + +>>> df = pd.DataFrame([[2.0, 1.0], +... [3.0, np.nan], +... [1.0, 0.0]], +... columns=list('AB')) +>>> df + A B +0 2.0 1.0 +1 3.0 NaN +2 1.0 0.0 + +skipna : Works in the same way as for Series. + +axis=0 : Default value, equivalent to axis=None or axis='index'. +Iterates over rows and finds the maximum in each column. +If value is larger than the previous one, updates it: + +>>> df.cummax() + A B +0 2.0 1.0 +1 3.0 NaN +2 3.0 1.0 + +axis=1 : Iterates over columns and finds the maximum in each row. +If value is larger than the previous one, updates it: + +>>> df.cummax(axis=1) + A B +0 2.0 2.0 +1 3.0 NaN +2 1.0 1.0 """ _any_see_also = """\ From 9d46623845595126906fc947edd136658419a79c Mon Sep 17 00:00:00 2001 From: arminv Date: Fri, 16 Mar 2018 15:33:19 -0400 Subject: [PATCH 06/11] Addressed PEP8 issues --- pandas/core/generic.py | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index f479de9e1b273..ad3c96a15b5b4 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8411,10 +8411,12 @@ def compound(self, axis=None, skipna=None, level=None): np.inf, np.nan, _cummin_examples) cls.cumsum = _make_cum_function( cls, 'cumsum', name, name2, axis_descr, "cumulative sum", - lambda y, axis: y.cumsum(axis), "sum", 0., np.nan, _cumsum_examples) + 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", - lambda y, axis: y.cumprod(axis), "prod", 1., np.nan, _cumprod_examples) + 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", lambda y, axis: np.maximum.accumulate(y, axis), "max", @@ -8702,7 +8704,7 @@ 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. -DataFrame.%(accum_func_name)s : Return the %(accum_func_name)s of values over DataFrame axis. +DataFrame.%(accum_func_name)s : Return the %(accum_func_name)s over DataFrame axis. DataFrame.cummax : Return cumulative maximum over DataFrame axis. DataFrame.cummin : Return cumulative minimum over DataFrame axis. DataFrame.cumsum : Return cumulative sum over DataFrame axis. @@ -8834,7 +8836,8 @@ def _doc_parms(cls): 1 5.0 NaN 2 6.0 1.0 -axis=1 : Iterates over columns and finds the cumulative sum of values in each row. +axis=1 : Iterates over columns and finds the cumulative sum of +values in each row. >>> df.cumsum(axis=1) A B @@ -8900,7 +8903,8 @@ def _doc_parms(cls): 1 6.0 NaN 2 6.0 0.0 -axis=1 : Iterates over columns and finds the cumulative product of values in each row. +axis=1 : Iterates over columns and finds the cumulative product +of values in each row. >>> df.cumprod(axis=1) A B From 5d502cbf035987a46d66f3397278ffa219f82168 Mon Sep 17 00:00:00 2001 From: arminv Date: Fri, 16 Mar 2018 15:42:51 -0400 Subject: [PATCH 07/11] Addressed PEP 8 issues --- pandas/core/generic.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index ad3c96a15b5b4..a46c0ea771281 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8411,11 +8411,11 @@ def compound(self, axis=None, skipna=None, level=None): np.inf, np.nan, _cummin_examples) cls.cumsum = _make_cum_function( cls, 'cumsum', name, name2, axis_descr, "cumulative sum", - lambda y, axis: y.cumsum(axis), "sum", 0., + 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", - lambda y, axis: y.cumprod(axis), "prod", 1., + 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", @@ -8704,7 +8704,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. -DataFrame.%(accum_func_name)s : Return the %(accum_func_name)s over DataFrame axis. +DataFrame.%(accum_func_name)s : Return the %(accum_func_name)s over + DataFrame axis. DataFrame.cummax : Return cumulative maximum over DataFrame axis. DataFrame.cummin : Return cumulative minimum over DataFrame axis. DataFrame.cumsum : Return cumulative sum over DataFrame axis. From aa34ea0ceca979c4201f4b634d22f2961463e47e Mon Sep 17 00:00:00 2001 From: arminv Date: Sat, 17 Mar 2018 02:27:35 -0400 Subject: [PATCH 08/11] Made See also of Series consistent --- pandas/core/generic.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index b83b0284b0d88..1ebfde432b0eb 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8785,12 +8785,12 @@ 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. -DataFrame.%(accum_func_name)s : Return the %(accum_func_name)s over - DataFrame axis. +%(name2)s.%(accum_func_name)s : Return the %(accum_func_name)s over + %(name2)s axis. DataFrame.cummax : Return cumulative maximum over DataFrame axis. -DataFrame.cummin : Return cumulative minimum over DataFrame axis. -DataFrame.cumsum : Return cumulative sum over DataFrame axis. -DataFrame.cumprod : Return cumulative product over DataFrame axis. +%(name2)s.cummin : Return cumulative minimum over %(name2)s axis. +%(name2)s.cumsum : Return cumulative sum over %(name2)s axis. +%(name2)s.cumprod : Return cumulative product over %(name2)s axis. """ _cummin_examples = """\ From 77789a83d5f7384af8c191470dfccc316ed65de2 Mon Sep 17 00:00:00 2001 From: arminv Date: Sat, 17 Mar 2018 07:53:55 -0400 Subject: [PATCH 09/11] Improved example wording. Addressed PEP8 --- pandas/core/generic.py | 74 +++++++++++++++++++----------------------- 1 file changed, 33 insertions(+), 41 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 1ebfde432b0eb..abc6c2b9d750b 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8704,8 +8704,8 @@ def _doc_parms(cls): Include only boolean columns. If None, will attempt to use everything, then use only boolean data. Not implemented for Series. **kwargs : any, default None - Additional keywords have no affect but might be accepted for - compatibility with numpy. + Additional keywords have no effect but might be accepted for + compatibility with NumPy. Returns ------- @@ -8774,7 +8774,9 @@ def _doc_parms(cls): skipna : boolean, default True Exclude NA/null values. If an entire row/column is NA, the result will be NA. -*args, **kwargs +*args, **kwargs : + Additional keywords have no effect but might be accepted for + compatibility with NumPy. Returns ------- @@ -8798,7 +8800,7 @@ def _doc_parms(cls): -------- **Series** ->>> s = pd.Series([2,np.nan,5,-1,0]) +>>> s = pd.Series([2, np.nan, 5, -1, 0]) >>> s 0 2.0 1 NaN @@ -8807,7 +8809,7 @@ def _doc_parms(cls): 4 0.0 dtype: float64 -skipna=True : Default value, ignores NaN values during operation: +By default, NA values are ignored. >>> s.cummin() 0 2.0 @@ -8817,7 +8819,7 @@ def _doc_parms(cls): 4 -1.0 dtype: float64 -skipna=False : Includes NaN values: +To include NA values in the operation, use ``skipna=False`` >>> s.cummin(skipna=False) 0 2.0 @@ -8839,11 +8841,8 @@ def _doc_parms(cls): 1 3.0 NaN 2 1.0 0.0 -skipna : Works in the same way as for Series. - -axis=0 : Default value, equivalent to axis=None or axis='index'. -Iterates over rows and finds the minimum in each column. -If value is smaller than the previous one, updates it: +By default, iterates over rows and finds the minimum +in each column. This is equivalent to ``axis=None`` or ``axis='index'``. >>> df.cummin() A B @@ -8851,8 +8850,8 @@ def _doc_parms(cls): 1 2.0 NaN 2 1.0 0.0 -axis=1 : Iterates over columns and finds the minimum in each row. -If value is smaller than the previous one, updates it: +To iterate over columns and find the minimum in each row, +use ``axis=1`` >>> df.cummin(axis=1) A B @@ -8866,7 +8865,7 @@ def _doc_parms(cls): -------- **Series** ->>> s = pd.Series([2,np.nan,5,-1,0]) +>>> s = pd.Series([2, np.nan, 5, -1, 0]) >>> s 0 2.0 1 NaN @@ -8875,7 +8874,7 @@ def _doc_parms(cls): 4 0.0 dtype: float64 -skipna=True : Default value, ignores NaN values during operation: +By default, NA values are ignored. >>> s.cumsum() 0 2.0 @@ -8885,7 +8884,7 @@ def _doc_parms(cls): 4 6.0 dtype: float64 -skipna=False : Includes NaN values: +To include NA values in the operation, use ``skipna=False`` >>> s.cumsum(skipna=False) 0 2.0 @@ -8907,10 +8906,8 @@ def _doc_parms(cls): 1 3.0 NaN 2 1.0 0.0 -skipna : Works in the same way as for Series. - -axis=0 : Default value, equivalent to axis=None or axis='index'. -Iterates over rows and finds the cumulative sum of values in each column. +By default, iterates over rows and finds the minimum +in each column. This is equivalent to ``axis=None`` or ``axis='index'``. >>> df.cumsum() A B @@ -8918,8 +8915,8 @@ def _doc_parms(cls): 1 5.0 NaN 2 6.0 1.0 -axis=1 : Iterates over columns and finds the cumulative sum of -values in each row. +To iterate over columns and find the minimum in each row, +use ``axis=1`` >>> df.cumsum(axis=1) A B @@ -8933,7 +8930,7 @@ def _doc_parms(cls): -------- **Series** ->>> s = pd.Series([2,np.nan,5,-1,0]) +>>> s = pd.Series([2, np.nan, 5, -1, 0]) >>> s 0 2.0 1 NaN @@ -8942,7 +8939,7 @@ def _doc_parms(cls): 4 0.0 dtype: float64 -skipna=True : Default value, ignores NaN values during operation: +By default, NA values are ignored. >>> s.cumprod() 0 2.0 @@ -8952,7 +8949,7 @@ def _doc_parms(cls): 4 -0.0 dtype: float64 -skipna=False : Includes NaN values: +To include NA values in the operation, use ``skipna=False`` >>> s.cumprod(skipna=False) 0 2.0 @@ -8974,10 +8971,8 @@ def _doc_parms(cls): 1 3.0 NaN 2 1.0 0.0 -skipna : Works in the same way as for Series. - -axis=0 : Default value, equivalent to axis=None or axis='index'. -Iterates over rows and finds the cumulative product of values in each column. +By default, iterates over rows and finds the minimum +in each column. This is equivalent to ``axis=None`` or ``axis='index'``. >>> df.cumprod() A B @@ -8985,8 +8980,8 @@ def _doc_parms(cls): 1 6.0 NaN 2 6.0 0.0 -axis=1 : Iterates over columns and finds the cumulative product -of values in each row. +To iterate over columns and find the minimum in each row, +use ``axis=1`` >>> df.cumprod(axis=1) A B @@ -9000,7 +8995,7 @@ def _doc_parms(cls): -------- **Series** ->>> s = pd.Series([2,np.nan,5,-1,0]) +>>> s = pd.Series([2, np.nan, 5, -1, 0]) >>> s 0 2.0 1 NaN @@ -9009,7 +9004,7 @@ def _doc_parms(cls): 4 0.0 dtype: float64 -skipna=True : Default value, ignores NaN values during operation: +By default, NA values are ignored. >>> s.cummax() 0 2.0 @@ -9019,7 +9014,7 @@ def _doc_parms(cls): 4 5.0 dtype: float64 -skipna=False : Includes NaN values: +To include NA values in the operation, use ``skipna=False`` >>> s.cummax(skipna=False) 0 2.0 @@ -9041,11 +9036,8 @@ def _doc_parms(cls): 1 3.0 NaN 2 1.0 0.0 -skipna : Works in the same way as for Series. - -axis=0 : Default value, equivalent to axis=None or axis='index'. -Iterates over rows and finds the maximum in each column. -If value is larger than the previous one, updates it: +By default, iterates over rows and finds the minimum +in each column. This is equivalent to ``axis=None`` or ``axis='index'``. >>> df.cummax() A B @@ -9053,8 +9045,8 @@ def _doc_parms(cls): 1 3.0 NaN 2 3.0 1.0 -axis=1 : Iterates over columns and finds the maximum in each row. -If value is larger than the previous one, updates it: +To iterate over columns and find the minimum in each row, +use ``axis=1`` >>> df.cummax(axis=1) A B From b03c32acce04a735d2d32bef123cc8542adf4683 Mon Sep 17 00:00:00 2001 From: arminv Date: Sat, 17 Mar 2018 08:14:28 -0400 Subject: [PATCH 10/11] More templating in See also.Fixed typos --- pandas/core/generic.py | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index abc6c2b9d750b..7a684af6342ab 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -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) @@ -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 ---------- @@ -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. +%(name2)s.%(accum_func_name)s : Return the %(desc)s over %(name2)s axis. DataFrame.cummax : Return cumulative maximum over DataFrame axis. %(name2)s.cummin : Return cumulative minimum over %(name2)s axis. @@ -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() @@ -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) @@ -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() @@ -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) @@ -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() @@ -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) From 1147a0dac297776632341fc80f0d364ad62b6699 Mon Sep 17 00:00:00 2001 From: arminv Date: Sat, 17 Mar 2018 12:18:52 -0400 Subject: [PATCH 11/11] Improved templating of See also section --- pandas/core/generic.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 7a684af6342ab..2adc289f98d94 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8787,10 +8787,9 @@ def _doc_parms(cls): -------- pandas.core.window.Expanding.%(accum_func_name)s : Similar functionality but ignores ``NaN`` values. -Series.%(outname)s : Return cumulative %(desc)s over Series axis. %(name2)s.%(accum_func_name)s : Return the %(desc)s over %(name2)s axis. -DataFrame.cummax : Return cumulative maximum over DataFrame axis. +%(name2)s.cummax : Return cumulative maximum over %(name2)s axis. %(name2)s.cummin : Return cumulative minimum over %(name2)s axis. %(name2)s.cumsum : Return cumulative sum over %(name2)s axis. %(name2)s.cumprod : Return cumulative product over %(name2)s axis.