Skip to content

Commit 699a48b

Browse files
arminvjorisvandenbossche
arminv
authored and
jorisvandenbossche
committed
DOC: update the pandas.DataFrame.cummax docstring (#20336)
1 parent ad50b1d commit 699a48b

File tree

1 file changed

+293
-19
lines changed

1 file changed

+293
-19
lines changed

‎pandas/core/generic.py

+293-19
Original file line numberDiff line numberDiff line change
@@ -8487,19 +8487,21 @@ def compound(self, axis=None, skipna=None, level=None):
84878487
cls.compound = compound
84888488

84898489
cls.cummin = _make_cum_function(
8490-
cls, 'cummin', name, name2, axis_descr, "cumulative minimum",
8490+
cls, 'cummin', name, name2, axis_descr, "minimum",
84918491
lambda y, axis: np.minimum.accumulate(y, axis), "min",
8492-
np.inf, np.nan)
8492+
np.inf, np.nan, _cummin_examples)
84938493
cls.cumsum = _make_cum_function(
8494-
cls, 'cumsum', name, name2, axis_descr, "cumulative sum",
8495-
lambda y, axis: y.cumsum(axis), "sum", 0., np.nan)
8494+
cls, 'cumsum', name, name2, axis_descr, "sum",
8495+
lambda y, axis: y.cumsum(axis), "sum", 0.,
8496+
np.nan, _cumsum_examples)
84968497
cls.cumprod = _make_cum_function(
8497-
cls, 'cumprod', name, name2, axis_descr, "cumulative product",
8498-
lambda y, axis: y.cumprod(axis), "prod", 1., np.nan)
8498+
cls, 'cumprod', name, name2, axis_descr, "product",
8499+
lambda y, axis: y.cumprod(axis), "prod", 1.,
8500+
np.nan, _cumprod_examples)
84998501
cls.cummax = _make_cum_function(
8500-
cls, 'cummax', name, name2, axis_descr, "cumulative max",
8502+
cls, 'cummax', name, name2, axis_descr, "maximum",
85018503
lambda y, axis: np.maximum.accumulate(y, axis), "max",
8502-
-np.inf, np.nan)
8504+
-np.inf, np.nan, _cummax_examples)
85038505

85048506
cls.sum = _make_min_count_stat_function(
85058507
cls, 'sum', name, name2, axis_descr,
@@ -8702,8 +8704,8 @@ def _doc_parms(cls):
87028704
Include only boolean columns. If None, will attempt to use everything,
87038705
then use only boolean data. Not implemented for Series.
87048706
**kwargs : any, default None
8705-
Additional keywords have no affect but might be accepted for
8706-
compatibility with numpy.
8707+
Additional keywords have no effect but might be accepted for
8708+
compatibility with NumPy.
87078709
87088710
Returns
87098711
-------
@@ -8761,24 +8763,296 @@ def _doc_parms(cls):
87618763
"""
87628764

87638765
_cnum_doc = """
8766+
Return cumulative %(desc)s over a DataFrame or Series axis.
8767+
8768+
Returns a DataFrame or Series of the same size containing the cumulative
8769+
%(desc)s.
87648770
87658771
Parameters
87668772
----------
8767-
axis : %(axis_descr)s
8773+
axis : {0 or 'index', 1 or 'columns'}, default 0
8774+
The index or the name of the axis. 0 is equivalent to None or 'index'.
87688775
skipna : boolean, default True
87698776
Exclude NA/null values. If an entire row/column is NA, the result
8770-
will be NA
8777+
will be NA.
8778+
*args, **kwargs :
8779+
Additional keywords have no effect but might be accepted for
8780+
compatibility with NumPy.
87718781
87728782
Returns
87738783
-------
8774-
%(outname)s : %(name1)s\n
8775-
8776-
8784+
%(outname)s : %(name1)s or %(name2)s\n
8785+
%(examples)s
87778786
See also
87788787
--------
87798788
pandas.core.window.Expanding.%(accum_func_name)s : Similar functionality
87808789
but ignores ``NaN`` values.
8790+
%(name2)s.%(accum_func_name)s : Return the %(desc)s over
8791+
%(name2)s axis.
8792+
%(name2)s.cummax : Return cumulative maximum over %(name2)s axis.
8793+
%(name2)s.cummin : Return cumulative minimum over %(name2)s axis.
8794+
%(name2)s.cumsum : Return cumulative sum over %(name2)s axis.
8795+
%(name2)s.cumprod : Return cumulative product over %(name2)s axis.
8796+
"""
8797+
8798+
_cummin_examples = """\
8799+
Examples
8800+
--------
8801+
**Series**
8802+
8803+
>>> s = pd.Series([2, np.nan, 5, -1, 0])
8804+
>>> s
8805+
0 2.0
8806+
1 NaN
8807+
2 5.0
8808+
3 -1.0
8809+
4 0.0
8810+
dtype: float64
8811+
8812+
By default, NA values are ignored.
8813+
8814+
>>> s.cummin()
8815+
0 2.0
8816+
1 NaN
8817+
2 2.0
8818+
3 -1.0
8819+
4 -1.0
8820+
dtype: float64
8821+
8822+
To include NA values in the operation, use ``skipna=False``
8823+
8824+
>>> s.cummin(skipna=False)
8825+
0 2.0
8826+
1 NaN
8827+
2 NaN
8828+
3 NaN
8829+
4 NaN
8830+
dtype: float64
8831+
8832+
**DataFrame**
8833+
8834+
>>> df = pd.DataFrame([[2.0, 1.0],
8835+
... [3.0, np.nan],
8836+
... [1.0, 0.0]],
8837+
... columns=list('AB'))
8838+
>>> df
8839+
A B
8840+
0 2.0 1.0
8841+
1 3.0 NaN
8842+
2 1.0 0.0
8843+
8844+
By default, iterates over rows and finds the minimum
8845+
in each column. This is equivalent to ``axis=None`` or ``axis='index'``.
8846+
8847+
>>> df.cummin()
8848+
A B
8849+
0 2.0 1.0
8850+
1 2.0 NaN
8851+
2 1.0 0.0
8852+
8853+
To iterate over columns and find the minimum in each row,
8854+
use ``axis=1``
8855+
8856+
>>> df.cummin(axis=1)
8857+
A B
8858+
0 2.0 1.0
8859+
1 3.0 NaN
8860+
2 1.0 0.0
8861+
"""
8862+
8863+
_cumsum_examples = """\
8864+
Examples
8865+
--------
8866+
**Series**
8867+
8868+
>>> s = pd.Series([2, np.nan, 5, -1, 0])
8869+
>>> s
8870+
0 2.0
8871+
1 NaN
8872+
2 5.0
8873+
3 -1.0
8874+
4 0.0
8875+
dtype: float64
8876+
8877+
By default, NA values are ignored.
8878+
8879+
>>> s.cumsum()
8880+
0 2.0
8881+
1 NaN
8882+
2 7.0
8883+
3 6.0
8884+
4 6.0
8885+
dtype: float64
8886+
8887+
To include NA values in the operation, use ``skipna=False``
8888+
8889+
>>> s.cumsum(skipna=False)
8890+
0 2.0
8891+
1 NaN
8892+
2 NaN
8893+
3 NaN
8894+
4 NaN
8895+
dtype: float64
8896+
8897+
**DataFrame**
8898+
8899+
>>> df = pd.DataFrame([[2.0, 1.0],
8900+
... [3.0, np.nan],
8901+
... [1.0, 0.0]],
8902+
... columns=list('AB'))
8903+
>>> df
8904+
A B
8905+
0 2.0 1.0
8906+
1 3.0 NaN
8907+
2 1.0 0.0
8908+
8909+
By default, iterates over rows and finds the sum
8910+
in each column. This is equivalent to ``axis=None`` or ``axis='index'``.
8911+
8912+
>>> df.cumsum()
8913+
A B
8914+
0 2.0 1.0
8915+
1 5.0 NaN
8916+
2 6.0 1.0
8917+
8918+
To iterate over columns and find the sum in each row,
8919+
use ``axis=1``
8920+
8921+
>>> df.cumsum(axis=1)
8922+
A B
8923+
0 2.0 3.0
8924+
1 3.0 NaN
8925+
2 1.0 1.0
8926+
"""
8927+
8928+
_cumprod_examples = """\
8929+
Examples
8930+
--------
8931+
**Series**
8932+
8933+
>>> s = pd.Series([2, np.nan, 5, -1, 0])
8934+
>>> s
8935+
0 2.0
8936+
1 NaN
8937+
2 5.0
8938+
3 -1.0
8939+
4 0.0
8940+
dtype: float64
8941+
8942+
By default, NA values are ignored.
8943+
8944+
>>> s.cumprod()
8945+
0 2.0
8946+
1 NaN
8947+
2 10.0
8948+
3 -10.0
8949+
4 -0.0
8950+
dtype: float64
8951+
8952+
To include NA values in the operation, use ``skipna=False``
8953+
8954+
>>> s.cumprod(skipna=False)
8955+
0 2.0
8956+
1 NaN
8957+
2 NaN
8958+
3 NaN
8959+
4 NaN
8960+
dtype: float64
87818961
8962+
**DataFrame**
8963+
8964+
>>> df = pd.DataFrame([[2.0, 1.0],
8965+
... [3.0, np.nan],
8966+
... [1.0, 0.0]],
8967+
... columns=list('AB'))
8968+
>>> df
8969+
A B
8970+
0 2.0 1.0
8971+
1 3.0 NaN
8972+
2 1.0 0.0
8973+
8974+
By default, iterates over rows and finds the product
8975+
in each column. This is equivalent to ``axis=None`` or ``axis='index'``.
8976+
8977+
>>> df.cumprod()
8978+
A B
8979+
0 2.0 1.0
8980+
1 6.0 NaN
8981+
2 6.0 0.0
8982+
8983+
To iterate over columns and find the product in each row,
8984+
use ``axis=1``
8985+
8986+
>>> df.cumprod(axis=1)
8987+
A B
8988+
0 2.0 2.0
8989+
1 3.0 NaN
8990+
2 1.0 0.0
8991+
"""
8992+
8993+
_cummax_examples = """\
8994+
Examples
8995+
--------
8996+
**Series**
8997+
8998+
>>> s = pd.Series([2, np.nan, 5, -1, 0])
8999+
>>> s
9000+
0 2.0
9001+
1 NaN
9002+
2 5.0
9003+
3 -1.0
9004+
4 0.0
9005+
dtype: float64
9006+
9007+
By default, NA values are ignored.
9008+
9009+
>>> s.cummax()
9010+
0 2.0
9011+
1 NaN
9012+
2 5.0
9013+
3 5.0
9014+
4 5.0
9015+
dtype: float64
9016+
9017+
To include NA values in the operation, use ``skipna=False``
9018+
9019+
>>> s.cummax(skipna=False)
9020+
0 2.0
9021+
1 NaN
9022+
2 NaN
9023+
3 NaN
9024+
4 NaN
9025+
dtype: float64
9026+
9027+
**DataFrame**
9028+
9029+
>>> df = pd.DataFrame([[2.0, 1.0],
9030+
... [3.0, np.nan],
9031+
... [1.0, 0.0]],
9032+
... columns=list('AB'))
9033+
>>> df
9034+
A B
9035+
0 2.0 1.0
9036+
1 3.0 NaN
9037+
2 1.0 0.0
9038+
9039+
By default, iterates over rows and finds the maximum
9040+
in each column. This is equivalent to ``axis=None`` or ``axis='index'``.
9041+
9042+
>>> df.cummax()
9043+
A B
9044+
0 2.0 1.0
9045+
1 3.0 NaN
9046+
2 3.0 1.0
9047+
9048+
To iterate over columns and find the maximum in each row,
9049+
use ``axis=1``
9050+
9051+
>>> df.cummax(axis=1)
9052+
A B
9053+
0 2.0 2.0
9054+
1 3.0 NaN
9055+
2 1.0 1.0
87829056
"""
87839057

87849058
_any_see_also = """\
@@ -8975,11 +9249,11 @@ def stat_func(self, axis=None, skipna=None, level=None, ddof=1,
89759249

89769250

89779251
def _make_cum_function(cls, name, name1, name2, axis_descr, desc,
8978-
accum_func, accum_func_name, mask_a, mask_b):
9252+
accum_func, accum_func_name, mask_a, mask_b, examples):
89799253
@Substitution(outname=name, desc=desc, name1=name1, name2=name2,
8980-
axis_descr=axis_descr, accum_func_name=accum_func_name)
8981-
@Appender("Return {0} over requested axis.".format(desc) +
8982-
_cnum_doc)
9254+
axis_descr=axis_descr, accum_func_name=accum_func_name,
9255+
examples=examples)
9256+
@Appender(_cnum_doc)
89839257
def cum_func(self, axis=None, skipna=True, *args, **kwargs):
89849258
skipna = nv.validate_cum_func_with_skipna(skipna, args, kwargs, name)
89859259
if axis is None:

0 commit comments

Comments
 (0)