pandas.Series.ewm — pandas 3.0.0.dev0+2099.g3832e85779 documentation (original) (raw)

Series.ewm(com=None, span=None, halflife=None, alpha=None, min_periods=0, adjust=True, ignore_na=False, times=None, method='single')[source]#

Provide exponentially weighted (EW) calculations.

Exactly one of com, span, halflife, or alpha must be provided if times is not provided. If times is provided and adjust=True,halflife and one of com, span or alpha may be provided. If times is provided and adjust=False, halflife must be the only provided decay-specification parameter.

Parameters:

comfloat, optional

Specify decay in terms of center of mass

\(\alpha = 1 / (1 + com)\), for \(com \geq 0\).

spanfloat, optional

Specify decay in terms of span

\(\alpha = 2 / (span + 1)\), for \(span \geq 1\).

halflifefloat, str, timedelta, optional

Specify decay in terms of half-life

\(\alpha = 1 - \exp\left(-\ln(2) / halflife\right)\), for\(halflife > 0\).

If times is specified, a timedelta convertible unit over which an observation decays to half its value. Only applicable to mean(), and halflife value will not apply to the other functions.

alphafloat, optional

Specify smoothing factor \(\alpha\) directly

\(0 < \alpha \leq 1\).

min_periodsint, default 0

Minimum number of observations in window required to have a value; otherwise, result is np.nan.

adjustbool, default True

Divide by decaying adjustment factor in beginning periods to account for imbalance in relative weightings (viewing EWMA as a moving average).

When adjust=True (default), the EW function is calculated using weights\(w_i = (1 - \alpha)^i\). For example, the EW moving average of the series [\(x_0, x_1, ..., x_t\)] would be:

\[y_t = \frac{x_t + (1 - \alpha)x_{t-1} + (1 - \alpha)^2 x_{t-2} + ... + (1 - \alpha)^t x_0}{1 + (1 - \alpha) + (1 - \alpha)^2 + ... + (1 - \alpha)^t}\]

When adjust=False, the exponentially weighted function is calculated recursively:

\[\begin{split}\begin{split} y_0 &= x_0\\ y_t &= (1 - \alpha) y_{t-1} + \alpha x_t, \end{split}\end{split}\]

ignore_nabool, default False

Ignore missing values when calculating weights.

When ignore_na=False (default), weights are based on absolute positions. For example, the weights of \(x_0\) and \(x_2\) used in calculating the final weighted average of [\(x_0\), None, \(x_2\)] are\((1-\alpha)^2\) and \(1\) if adjust=True, and\((1-\alpha)^2\) and \(\alpha\) if adjust=False.
When ignore_na=True, weights are based on relative positions. For example, the weights of \(x_0\) and \(x_2\)used in calculating the final weighted average of [\(x_0\), None, \(x_2\)] are \(1-\alpha\) and \(1\) ifadjust=True, and \(1-\alpha\) and \(\alpha\) if adjust=False.

timesnp.ndarray, Series, default None

Only applicable to mean().

Times corresponding to the observations. Must be monotonically increasing anddatetime64[ns] dtype.

If 1-D array like, a sequence with the same shape as the observations.

methodstr {‘single’, ‘table’}, default ‘single’

Added in version 1.4.0.

Execute the rolling operation per single column or row ('single') or over the entire object ('table').

This argument is only implemented when specifying engine='numba'in the method call.

Only applicable to mean()

Returns:

pandas.api.typing.ExponentialMovingWindow

An instance of ExponentialMovingWindow for further exponentially weighted (EW) calculations, e.g. using the mean method.