diff --git a/doc/source/reference/groupby.rst b/doc/source/reference/groupby.rst index fc180c8161a7e..ce9aeeb358c19 100644 --- a/doc/source/reference/groupby.rst +++ b/doc/source/reference/groupby.rst @@ -79,6 +79,7 @@ Function application DataFrameGroupBy.cumsum DataFrameGroupBy.describe DataFrameGroupBy.diff + DataFrameGroupBy.ewm DataFrameGroupBy.ffill DataFrameGroupBy.first DataFrameGroupBy.head @@ -130,6 +131,7 @@ Function application SeriesGroupBy.cumsum SeriesGroupBy.describe SeriesGroupBy.diff + SeriesGroupBy.ewm SeriesGroupBy.ffill SeriesGroupBy.first SeriesGroupBy.head diff --git a/pandas/core/groupby/groupby.py b/pandas/core/groupby/groupby.py index 9cfeb53821fbc..2cb523d2f2f55 100644 --- a/pandas/core/groupby/groupby.py +++ b/pandas/core/groupby/groupby.py @@ -3824,15 +3824,79 @@ def expanding(self, *args, **kwargs) -> ExpandingGroupby: ) @final - @Substitution(name="groupby") - @Appender(_common_see_also) def ewm(self, *args, **kwargs) -> ExponentialMovingWindowGroupby: """ Return an ewm grouper, providing ewm functionality per group. + Parameters + ---------- + *args : tuple + Positional arguments passed to the EWM window constructor. + **kwargs : dict + Keyword arguments passed to the EWM window constructor, such as: + + com : float, optional + Specify decay in terms of center of mass. + ``span``, ``halflife``, and ``alpha`` are alternative ways to specify + decay. + span : float, optional + Specify decay in terms of span. + halflife : float, optional + Specify decay in terms of half-life. + alpha : float, optional + Specify smoothing factor directly. + min_periods : int, default 0 + Minimum number of observations in the window required to have a value; + otherwise, result is ``np.nan``. + adjust : bool, default True + Divide by decaying adjustment factor to account for imbalance in + relative weights. + ignore_na : bool, default False + Ignore missing values when calculating weights. + times : str or array-like of datetime64, optional + Times corresponding to the observations. + axis : {0 or 'index', 1 or 'columns'}, default 0 + Axis along which the EWM function is applied. + Returns ------- pandas.api.typing.ExponentialMovingWindowGroupby + An object that supports exponentially weighted moving transformations over + each group. + + See Also + -------- + Series.ewm : EWM transformations for Series. + DataFrame.ewm : EWM transformations for DataFrames. + Series.groupby : Apply a function groupby to a Series. + DataFrame.groupby : Apply a function groupby. + + Examples + -------- + >>> df = pd.DataFrame( + ... { + ... "Class": ["A", "A", "A", "B", "B", "B"], + ... "Value": [10, 20, 30, 40, 50, 60], + ... } + ... ) + >>> df + Class Value + 0 A 10 + 1 A 20 + 2 A 30 + 3 B 40 + 4 B 50 + 5 B 60 + + >>> df.groupby("Class").ewm(com=0.5).mean() + Value + Class + A 0 10.000000 + 1 17.500000 + 2 26.153846 + B 3 40.000000 + 4 47.500000 + 5 56.153846 """ from pandas.core.window import ExponentialMovingWindowGroupby