Skip to content

Commit

Permalink
Improve docstring of ewm functions (#4356)
Browse files Browse the repository at this point in the history 
Co-authored-by: Matteo Santamaria <msantama@gmail.com>
  • Loading branch information
@matteosantama
matteosantama and Matteo Santamaria committed Aug 11, 2022
1 parent 0cbbf48 commit 9ccfaf3
Show file tree
Hide file tree
Showing 2 changed files with 144 additions and 74 deletions.
108 changes: 72 additions & 36 deletions py-polars/polars/internals/expr.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4701,31 +4701,43 @@ def ewm_mean(
min_periods: int = 1,
) -> Expr:
r"""
Exponential moving average.
Exponentially-weighted moving average.
Parameters
----------
com
Specify decay in terms of center of mass,
:math:`alpha = 1/(1 + com) \;for\; com >= 0`.
Specify decay in terms of center of mass, :math:`\gamma`, with
.. math::
\alpha = \frac{1}{1 + \gamma} \; \forall \; \gamma \geq 0
span
Specify decay in terms of span,
:math:`alpha = 2/(span + 1) \;for\; span >= 1`
Specify decay in terms of span, :math:`\theta`, with
.. math::
\alpha = \frac{2}{\theta + 1} \; \forall \; \theta \geq 1
half_life
Specify decay in terms of half-life,
:math:`alpha = 1 - exp(-ln(2) / halflife) \;for\; halflife > 0`
Specify decay in terms of half-life, :math:`\lambda`, with
.. math::
\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \lambda } \right\} \;
\forall \; \lambda > 0
alpha
Specify smoothing factor alpha directly, :math:`0 < alpha < 1`.
Specify smoothing factor alpha directly, :math:`0 < \alpha < 1`.
adjust
Divide by decaying adjustment factor in beginning periods to account for
imbalance in relative weightings
- When adjust = True the EW function is calculated using weights
:math:`w_i = (1 - alpha)^i`
- When adjust = False the EW function is calculated recursively.
- When ``adjust=True`` the EW function is calculated
using weights :math:`w_i = (1 - \alpha)^i`
- When ``adjust=False`` the EW function is calculated
recursively by
.. math::
y_0 &= x_0 \\
y_t &= (1 - \alpha)y_{t - 1} + \alpha x_t
min_periods
Minimum number of observations in window required to have a value
(otherwise result is Null).
(otherwise result is null).
"""
alpha = _prepare_alpha(com, span, half_life, alpha)
Expand All @@ -4741,31 +4753,43 @@ def ewm_std(
min_periods: int = 1,
) -> Expr:
r"""
Exponential moving standard deviation.
Exponentially-weighted moving standard deviation.
Parameters
----------
com
Specify decay in terms of center of mass,
:math:`alpha = 1/(1 + com) \;for\; com >= 0`.
Specify decay in terms of center of mass, :math:`\gamma`, with
.. math::
\alpha = \frac{1}{1 + \gamma} \; \forall \; \gamma \geq 0
span
Specify decay in terms of span,
:math:`alpha = 2/(span + 1) \;for\; span >= 1`
Specify decay in terms of span, :math:`\theta`, with
.. math::
\alpha = \frac{2}{\theta + 1} \; \forall \; \theta \geq 1
half_life
Specify decay in terms of half-life,
:math:`alpha = 1 - exp(-ln(2) / halflife) \;for\; halflife > 0`
Specify decay in terms of half-life, :math:`\lambda`, with
.. math::
\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \lambda } \right\} \;
\forall \; \lambda > 0
alpha
Specify smoothing factor alpha directly, :math:`0 < alpha < 1`.
Specify smoothing factor alpha directly, :math:`0 < \alpha < 1`.
adjust
Divide by decaying adjustment factor in beginning periods to account for
imbalance in relative weightings
- When adjust = True the EW function is calculated using weights
:math:`w_i = (1 - alpha)^i`
- When adjust = False the EW function is calculated recursively.
- When ``adjust=True`` the EW function is calculated
using weights :math:`w_i = (1 - \alpha)^i`
- When ``adjust=False`` the EW function is calculated
recursively by
.. math::
y_0 &= x_0 \\
y_t &= (1 - \alpha)y_{t - 1} + \alpha x_t
min_periods
Minimum number of observations in window required to have a value
(otherwise result is Null).
(otherwise result is null).
"""
alpha = _prepare_alpha(com, span, half_life, alpha)
Expand All @@ -4781,31 +4805,43 @@ def ewm_var(
min_periods: int = 1,
) -> Expr:
r"""
Exponential moving standard deviation.
Exponentially-weighted moving variance.
Parameters
----------
com
Specify decay in terms of center of mass,
:math:`alpha = 1/(1 + com) \;for\; com >= 0`.
Specify decay in terms of center of mass, :math:`\gamma`, with
.. math::
\alpha = \frac{1}{1 + \gamma} \; \forall \; \gamma \geq 0
span
Specify decay in terms of span,
:math:`alpha = 2/(span + 1) \;for\; span >= 1`
Specify decay in terms of span, :math:`\theta`, with
.. math::
\alpha = \frac{2}{\theta + 1} \; \forall \; \theta \geq 1
half_life
Specify decay in terms of half-life,
:math:`alpha = 1 - exp(-ln(2) / halflife) \;for\; halflife > 0`
Specify decay in terms of half-life, :math:`\lambda`, with
.. math::
\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \lambda } \right\} \;
\forall \; \lambda > 0
alpha
Specify smoothing factor alpha directly, :math:`0 < alpha < 1`.
Specify smoothing factor alpha directly, :math:`0 < \alpha < 1`.
adjust
Divide by decaying adjustment factor in beginning periods to account for
imbalance in relative weightings
- When adjust = True the EW function is calculated using weights
:math:`w_i = (1 - alpha)^i`
- When adjust = False the EW function is calculated recursively.
- When ``adjust=True`` the EW function is calculated
using weights :math:`w_i = (1 - \alpha)^i`
- When ``adjust=False`` the EW function is calculated
recursively by
.. math::
y_0 &= x_0 \\
y_t &= (1 - \alpha)y_{t - 1} + \alpha x_t
min_periods
Minimum number of observations in window required to have a value
(otherwise result is Null).
(otherwise result is null).
"""
alpha = _prepare_alpha(com, span, half_life, alpha)
Expand Down
110 changes: 72 additions & 38 deletions py-polars/polars/internals/series.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4032,32 +4032,43 @@ def ewm_mean(
min_periods: int = 1,
) -> Series:
r"""
Exponential moving average.
Exponentially-weighted moving average.
Parameters
----------
com
Specify decay in terms of center of mass,
:math:`alpha = 1/(1 + com) \;for\; com >= 0`.
Specify decay in terms of center of mass, :math:`\gamma`, with
.. math::
\alpha = \frac{1}{1 + \gamma} \; \forall \; \gamma \geq 0
span
Specify decay in terms of span,
:math:`alpha = 2/(span + 1) \;for\; span >= 1`
Specify decay in terms of span, :math:`\theta`, with
.. math::
\alpha = \frac{2}{\theta + 1} \; \forall \; \theta \geq 1
half_life
Specify decay in terms of half-life,
:math:`alpha = 1 - exp(-ln(2) / halflife) \;for\; halflife > 0`
Specify decay in terms of half-life, :math:`\lambda`, with
.. math::
\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \lambda } \right\} \;
\forall \; \lambda > 0
alpha
Specify smoothing factor alpha directly,
:math:`0 < alpha < 1`.
Specify smoothing factor alpha directly, :math:`0 < \alpha < 1`.
adjust
Divide by decaying adjustment factor in beginning periods to account for
imbalance in relative weightings
- When adjust = True the EW function is calculated using weights
:math:`w_i = (1 - alpha)^i`
- When adjust = False the EW function is calculated recursively.
- When ``adjust=True`` the EW function is calculated
using weights :math:`w_i = (1 - \alpha)^i`
- When ``adjust=False`` the EW function is calculated
recursively by
.. math::
y_0 &= x_0 \\
y_t &= (1 - \alpha)y_{t - 1} + \alpha x_t
min_periods
Minimum number of observations in window required to have a value
(otherwise result is Null).
(otherwise result is null).
"""
return (
Expand All @@ -4080,32 +4091,43 @@ def ewm_std(
min_periods: int = 1,
) -> Series:
r"""
Exponential moving standard deviation.
Exponentially-weighted moving standard deviation.
Parameters
----------
com
Specify decay in terms of center of mass,
:math:`alpha = 1/(1 + com) \;for\; com >= 0`.
Specify decay in terms of center of mass, :math:`\gamma`, with
.. math::
\alpha = \frac{1}{1 + \gamma} \; \forall \; \gamma \geq 0
span
Specify decay in terms of span,
:math:`alpha = 2/(span + 1) \;for\; span >= 1`
Specify decay in terms of span, :math:`\theta`, with
.. math::
\alpha = \frac{2}{\theta + 1} \; \forall \; \theta \geq 1
half_life
Specify decay in terms of half-life,
:math:`alpha = 1 - exp(-ln(2) / halflife) \;for\; halflife > 0`
Specify decay in terms of half-life, :math:`\lambda`, with
.. math::
\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \lambda } \right\} \;
\forall \; \lambda > 0
alpha
Specify smoothing factor alpha directly,
:math:`0 < alpha < 1`.
Specify smoothing factor alpha directly, :math:`0 < \alpha < 1`.
adjust
Divide by decaying adjustment factor in beginning periods to account for
imbalance in relative weightings
- When adjust = True the EW function is calculated using weights
:math:`w_i = (1 - alpha)^i`
- When adjust = False the EW function is calculated recursively.
- When ``adjust=True`` the EW function is calculated
using weights :math:`w_i = (1 - \alpha)^i`
- When ``adjust=False`` the EW function is calculated
recursively by
.. math::
y_0 &= x_0 \\
y_t &= (1 - \alpha)y_{t - 1} + \alpha x_t
min_periods
Minimum number of observations in window required to have a value
(otherwise result is Null).
(otherwise result is null).
"""
return (
Expand All @@ -4128,31 +4150,43 @@ def ewm_var(
min_periods: int = 1,
) -> Series:
r"""
Exponential moving standard variation.
Exponentially-weighted moving variance.
Parameters
----------
com
Specify decay in terms of center of mass,
:math:`alpha = 1/(1 + com) \;for\; com >= 0`.
Specify decay in terms of center of mass, :math:`\gamma`, with
.. math::
\alpha = \frac{1}{1 + \gamma} \; \forall \; \gamma \geq 0
span
Specify decay in terms of span,
:math:`alpha = 2/(span + 1) \;for\; span >= 1`
Specify decay in terms of span, :math:`\theta`, with
.. math::
\alpha = \frac{2}{\theta + 1} \; \forall \; \theta \geq 1
half_life
Specify decay in terms of half-life,
:math:`alpha = 1 - exp(-ln(2) / halflife) \;for\; halflife > 0`
Specify decay in terms of half-life, :math:`\lambda`, with
.. math::
\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \lambda } \right\} \;
\forall \; \lambda > 0
alpha
Specify smoothing factor alpha directly, :math:`0 < alpha < 1`.
Specify smoothing factor alpha directly, :math:`0 < \alpha < 1`.
adjust
Divide by decaying adjustment factor in beginning periods to account for
imbalance in relative weightings
- When adjust = True the EW function is calculated using weights
:math:`w_i = (1 - alpha)^i`
- When adjust = False the EW function is calculated recursively.
- When ``adjust=True`` the EW function is calculated
using weights :math:`w_i = (1 - \alpha)^i`
- When ``adjust=False`` the EW function is calculated
recursively by
.. math::
y_0 &= x_0 \\
y_t &= (1 - \alpha)y_{t - 1} + \alpha x_t
min_periods
Minimum number of observations in window required to have a value
(otherwise result is Null).
(otherwise result is null).
"""
return (
Expand Down

0 comments on commit 9ccfaf3

Please sign in to comment.