diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 9e50b93e173c4..f2d6a2b222a3c 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -265,35 +265,27 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.api.indexers.VariableOffsetWindowIndexer \ pandas.core.groupby.DataFrameGroupBy.diff \ pandas.core.groupby.DataFrameGroupBy.ffill \ - pandas.core.groupby.DataFrameGroupBy.max \ pandas.core.groupby.DataFrameGroupBy.median \ - pandas.core.groupby.DataFrameGroupBy.min \ pandas.core.groupby.DataFrameGroupBy.ohlc \ pandas.core.groupby.DataFrameGroupBy.pct_change \ - pandas.core.groupby.DataFrameGroupBy.prod \ pandas.core.groupby.DataFrameGroupBy.sem \ pandas.core.groupby.DataFrameGroupBy.shift \ pandas.core.groupby.DataFrameGroupBy.size \ pandas.core.groupby.DataFrameGroupBy.skew \ pandas.core.groupby.DataFrameGroupBy.std \ - pandas.core.groupby.DataFrameGroupBy.sum \ pandas.core.groupby.DataFrameGroupBy.var \ pandas.core.groupby.SeriesGroupBy.diff \ pandas.core.groupby.SeriesGroupBy.fillna \ pandas.core.groupby.SeriesGroupBy.ffill \ - pandas.core.groupby.SeriesGroupBy.max \ pandas.core.groupby.SeriesGroupBy.median \ - pandas.core.groupby.SeriesGroupBy.min \ pandas.core.groupby.SeriesGroupBy.nunique \ pandas.core.groupby.SeriesGroupBy.ohlc \ pandas.core.groupby.SeriesGroupBy.pct_change \ - pandas.core.groupby.SeriesGroupBy.prod \ pandas.core.groupby.SeriesGroupBy.sem \ pandas.core.groupby.SeriesGroupBy.shift \ pandas.core.groupby.SeriesGroupBy.size \ pandas.core.groupby.SeriesGroupBy.skew \ pandas.core.groupby.SeriesGroupBy.std \ - pandas.core.groupby.SeriesGroupBy.sum \ pandas.core.groupby.SeriesGroupBy.var \ pandas.core.groupby.SeriesGroupBy.hist \ pandas.core.groupby.DataFrameGroupBy.plot \ diff --git a/pandas/core/groupby/groupby.py b/pandas/core/groupby/groupby.py index 341e177a4a9ad..c96310c51b2a2 100644 --- a/pandas/core/groupby/groupby.py +++ b/pandas/core/groupby/groupby.py @@ -341,6 +341,10 @@ class providing the base-class of operations. ------- Series or DataFrame Computed {fname} of values within each group. + +Examples +-------- +{example} """ _pipe_template = """ @@ -2550,7 +2554,46 @@ def size(self) -> DataFrame | Series: return result @final - @doc(_groupby_agg_method_template, fname="sum", no=False, mc=0) + @doc( + _groupby_agg_method_template, + fname="sum", + no=False, + mc=0, + example=dedent( + """\ + For SeriesGroupBy: + + >>> lst = ['a', 'a', 'b', 'b'] + >>> ser = pd.Series([1, 2, 3, 4], index=lst) + >>> ser + a 1 + a 2 + b 3 + b 4 + dtype: int64 + >>> ser.groupby(level=0).sum() + a 3 + b 7 + dtype: int64 + + For DataFrameGroupBy: + + >>> data = [[1, 8, 2], [1, 2, 5], [2, 5, 8], [2, 6, 9]] + >>> df = pd.DataFrame(data, columns=["a", "b", "c"], + ... index=["tiger", "leopard", "cheetah", "lion"]) + >>> df + a b c + tiger 1 8 2 + leopard 1 2 5 + cheetah 2 5 8 + lion 2 6 9 + >>> df.groupby("a").sum() + b c + a + 1 10 7 + 2 11 17""" + ), + ) def sum( self, numeric_only: bool = False, @@ -2580,14 +2623,92 @@ def sum( return self._reindex_output(result, fill_value=0) @final - @doc(_groupby_agg_method_template, fname="prod", no=False, mc=0) + @doc( + _groupby_agg_method_template, + fname="prod", + no=False, + mc=0, + example=dedent( + """\ + For SeriesGroupBy: + + >>> lst = ['a', 'a', 'b', 'b'] + >>> ser = pd.Series([1, 2, 3, 4], index=lst) + >>> ser + a 1 + a 2 + b 3 + b 4 + dtype: int64 + >>> ser.groupby(level=0).prod() + a 2 + b 12 + dtype: int64 + + For DataFrameGroupBy: + + >>> data = [[1, 8, 2], [1, 2, 5], [2, 5, 8], [2, 6, 9]] + >>> df = pd.DataFrame(data, columns=["a", "b", "c"], + ... index=["tiger", "leopard", "cheetah", "lion"]) + >>> df + a b c + tiger 1 8 2 + leopard 1 2 5 + cheetah 2 5 8 + lion 2 6 9 + >>> df.groupby("a").prod() + b c + a + 1 16 10 + 2 30 72""" + ), + ) def prod(self, numeric_only: bool = False, min_count: int = 0): return self._agg_general( numeric_only=numeric_only, min_count=min_count, alias="prod", npfunc=np.prod ) @final - @doc(_groupby_agg_method_template, fname="min", no=False, mc=-1) + @doc( + _groupby_agg_method_template, + fname="min", + no=False, + mc=-1, + example=dedent( + """\ + For SeriesGroupBy: + + >>> lst = ['a', 'a', 'b', 'b'] + >>> ser = pd.Series([1, 2, 3, 4], index=lst) + >>> ser + a 1 + a 2 + b 3 + b 4 + dtype: int64 + >>> ser.groupby(level=0).min() + a 1 + b 3 + dtype: int64 + + For DataFrameGroupBy: + + >>> data = [[1, 8, 2], [1, 2, 5], [2, 5, 8], [2, 6, 9]] + >>> df = pd.DataFrame(data, columns=["a", "b", "c"], + ... index=["tiger", "leopard", "cheetah", "lion"]) + >>> df + a b c + tiger 1 8 2 + leopard 1 2 5 + cheetah 2 5 8 + lion 2 6 9 + >>> df.groupby("a").min() + b c + a + 1 2 2 + 2 5 8""" + ), + ) def min( self, numeric_only: bool = False, @@ -2608,7 +2729,46 @@ def min( ) @final - @doc(_groupby_agg_method_template, fname="max", no=False, mc=-1) + @doc( + _groupby_agg_method_template, + fname="max", + no=False, + mc=-1, + example=dedent( + """\ + For SeriesGroupBy: + + >>> lst = ['a', 'a', 'b', 'b'] + >>> ser = pd.Series([1, 2, 3, 4], index=lst) + >>> ser + a 1 + a 2 + b 3 + b 4 + dtype: int64 + >>> ser.groupby(level=0).max() + a 2 + b 4 + dtype: int64 + + For DataFrameGroupBy: + + >>> data = [[1, 8, 2], [1, 2, 5], [2, 5, 8], [2, 6, 9]] + >>> df = pd.DataFrame(data, columns=["a", "b", "c"], + ... index=["tiger", "leopard", "cheetah", "lion"]) + >>> df + a b c + tiger 1 8 2 + leopard 1 2 5 + cheetah 2 5 8 + lion 2 6 9 + >>> df.groupby("a").max() + b c + a + 1 8 5 + 2 6 9""" + ), + ) def max( self, numeric_only: bool = False,