U c͊@sddlmZddlZddlmZddlmZddlmZm Z ddl Z ddl Z ddl mZddlmmmZddlmZmZerddlmZmZdd lmZdd lmZdd lm Z dd l!m"Z"dd l#m$Z$m%Z%ddl&m'Z'ddl(m)m*Z*ddl+m,Z,m-Z-m.Z.ddl/m0Z0m1Z1ddl2m3Z3m4Z4ddl5m6Z6m7Z7m8Z8m9Z9m:Z:m;Z;mZ>m?Z?ddl@mAZAmBZBddlCmDZDmEZEddlFmGZGmHZHddddddddZIdddddd ZJGd!d"d"eGZKGd#d$d$eHeKZLGd%d&d&eKZMdS)') annotationsN)partial)dedent) TYPE_CHECKINGcast) Timedelta)AxisTimedeltaConvertibleTypes) DataFrameSeries)NDFrame)function)doc)find_stack_level)is_datetime64_ns_dtypeis_numeric_dtype)isna) BaseIndexerExponentialMovingWindowIndexerGroupbyIndexer)get_jit_argumentsmaybe_use_numba)maybe_warn_args_and_kwargszsqrt) _shared_docs args_compatcreate_section_header kwargs_compatkwargs_numeric_only numba_notestemplate_headertemplate_returnstemplate_see_alsowindow_agg_numba_parameters)generate_numba_ewm_funcgenerate_numba_ewm_table_func) EWMMeanStategenerate_online_numba_ewma_func) BaseWindowBaseWindowGroupby float | Nonefloat)comassspanhalflifealphareturncCst||||}|dkr td|dk r:|dkrtdn|dk r`|dkrRtd|dd}nt|dk r|dkrxtddttd|}d|d}n6|dk r|dks|dkrtd d||}ntd t|S) Nz8comass, span, halflife, and alpha are mutually exclusiverz comass must satisfy: comass >= 0zspan must satisfy: span >= 1z#halflife must satisfy: halflife > 0g?z"alpha must satisfy: 0 < alpha <= 1z1Must pass one of comass, span, halflife, or alpha)commoncount_not_none ValueErrornpexplogr+)r,r-r.r/Z valid_countZdecayr9:/tmp/pip-unpacked-wheel-g7fro6k3/pandas/core/window/ewm.pyget_center_of_massKs* r;!str | np.ndarray | NDFrame | None(float | TimedeltaConvertibleTypes | None np.ndarray)timesr.r0cCs4tj|tjtjd}tt|j}t||S)a Return the diff of the times divided by the half-life. These values are used in the calculation of the ewm mean. Parameters ---------- times : str, np.ndarray, Series, default None Times corresponding to the observations. Must be monotonically increasing and ``datetime64[ns]`` dtype. halflife : float, str, timedelta, optional Half-life specifying the decay Returns ------- np.ndarray Diff of the times divided by the half-life dtype) r6ZasarrayviewZint64float64r+rvalueZdiff)r?r.Z_timesZ _halflifer9r9r:_calculate_deltasls  rEcseZdZdZdddddddd d d g Zdad dddddddddddddd fddZddddd d!d"Zd#d$d%d&Zdbd(d$d)d*Ze e d+e d,e d-d.d/d0fd1d2Z e Z e eed3eeeeed4eed5eed6ed7d/d8d9d:d;d<dcd d d=dd>d?d@Ze eed3eeeeed4eed5eed6ed7d/d8d9dAdBd<ddd d d=dd>dCdDZe eed3e dEd7d/d8eeeed4eed5ed dFd9dGdHd< dedddIdJdKZdfddLdMdNZe eed3e dEd7d/d8eeeed4eed5ed dFd9dOdPd< dgdddIdQdRZe eed3e dSd7d/d8eeed4eed5ed dFd9dTdUd< dhdVdWdddXdYdZZe eed3e d[d7d/d8eeed4eed5ed dFd9d\d]d< didVdWdd^d_d`ZZS)jExponentialMovingWindowa 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, ``halflife`` and one of ``com``, ``span`` or ``alpha`` may be provided. Parameters ---------- com : float, optional Specify decay in terms of center of mass :math:`\alpha = 1 / (1 + com)`, for :math:`com \geq 0`. span : float, optional Specify decay in terms of span :math:`\alpha = 2 / (span + 1)`, for :math:`span \geq 1`. halflife : float, str, timedelta, optional Specify decay in terms of half-life :math:`\alpha = 1 - \exp\left(-\ln(2) / halflife\right)`, for :math:`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. .. versionadded:: 1.1.0 alpha : float, optional Specify smoothing factor :math:`\alpha` directly :math:`0 < \alpha \leq 1`. min_periods : int, default 0 Minimum number of observations in window required to have a value; otherwise, result is ``np.nan``. adjust : bool, 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 :math:`w_i = (1 - \alpha)^i`. For example, the EW moving average of the series [:math:`x_0, x_1, ..., x_t`] would be: .. math:: 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: .. math:: \begin{split} y_0 &= x_0\\ y_t &= (1 - \alpha) y_{t-1} + \alpha x_t, \end{split} ignore_na : bool, default False Ignore missing values when calculating weights. - When ``ignore_na=False`` (default), weights are based on absolute positions. For example, the weights of :math:`x_0` and :math:`x_2` used in calculating the final weighted average of [:math:`x_0`, None, :math:`x_2`] are :math:`(1-\alpha)^2` and :math:`1` if ``adjust=True``, and :math:`(1-\alpha)^2` and :math:`\alpha` if ``adjust=False``. - When ``ignore_na=True``, weights are based on relative positions. For example, the weights of :math:`x_0` and :math:`x_2` used in calculating the final weighted average of [:math:`x_0`, None, :math:`x_2`] are :math:`1-\alpha` and :math:`1` if ``adjust=True``, and :math:`1-\alpha` and :math:`\alpha` if ``adjust=False``. axis : {0, 1}, default 0 If ``0`` or ``'index'``, calculate across the rows. If ``1`` or ``'columns'``, calculate across the columns. For `Series` this parameter is unused and defaults to 0. times : str, np.ndarray, Series, default None .. versionadded:: 1.1.0 Only applicable to ``mean()``. Times corresponding to the observations. Must be monotonically increasing and ``datetime64[ns]`` dtype. If 1-D array like, a sequence with the same shape as the observations. .. deprecated:: 1.4.0 If str, the name of the column in the DataFrame representing the times. method : str {'single', 'table'}, default 'single' .. versionadded:: 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 ------- ``ExponentialMovingWindow`` subclass See Also -------- rolling : Provides rolling window calculations. expanding : Provides expanding transformations. Notes ----- See :ref:`Windowing Operations ` for further usage details and examples. Examples -------- >>> df = pd.DataFrame({'B': [0, 1, 2, np.nan, 4]}) >>> df B 0 0.0 1 1.0 2 2.0 3 NaN 4 4.0 >>> df.ewm(com=0.5).mean() B 0 0.000000 1 0.750000 2 1.615385 3 1.615385 4 3.670213 >>> df.ewm(alpha=2 / 3).mean() B 0 0.000000 1 0.750000 2 1.615385 3 1.615385 4 3.670213 **adjust** >>> df.ewm(com=0.5, adjust=True).mean() B 0 0.000000 1 0.750000 2 1.615385 3 1.615385 4 3.670213 >>> df.ewm(com=0.5, adjust=False).mean() B 0 0.000000 1 0.666667 2 1.555556 3 1.555556 4 3.650794 **ignore_na** >>> df.ewm(com=0.5, ignore_na=True).mean() B 0 0.000000 1 0.750000 2 1.615385 3 1.615385 4 3.225000 >>> df.ewm(com=0.5, ignore_na=False).mean() B 0 0.000000 1 0.750000 2 1.615385 3 1.615385 4 3.670213 **times** Exponentially weighted mean with weights calculated with a timedelta ``halflife`` relative to ``times``. >>> times = ['2020-01-01', '2020-01-03', '2020-01-10', '2020-01-15', '2020-01-17'] >>> df.ewm(halflife='4 days', times=pd.DatetimeIndex(times)).mean() B 0 0.000000 1 0.585786 2 1.523889 3 1.523889 4 3.233686 comr-r.r/ min_periodsadjust ignore_naaxisr?methodNrTFsingle selectionr r*r= int | Noneboolrr<strNone) objrGr-r.r/rHrIrJrKr?rLr0c  stj||dkrdn tt|dddd| | | d||_||_||_||_||_||_ | |_ |j dk rT|jsvt dt |j t rtjdttdtd|j|j |_ t|j stdt|j t|krtd t |jt tjtjfstd t|j r td t|j |j|_t |j|j|jd krLt!|j|jd|j|_"nd |_"nj|jdk rt |jt tjtjfrtdtj#t|j$j%|j&dd tj'd|_t!|j|j|j|j|_"dS)Nr1F)rTrHoncenterclosedrLrKrOz)times is not supported with adjust=False.zSpecifying times as a string column label is deprecated and will be removed in a future version. Pass the column into times instead. stacklevelr z#times must be datetime64[ns] dtype.z,times must be the same length as the object.z/halflife must be a timedelta convertible objectz$Cannot convert NaT values to integerrg?zKhalflife can only be a timedelta convertible argument if times is not None.r@)(super__init__maxintrGr-r.r/rIrJr?NotImplementedError isinstancerRwarningswarn FutureWarningrr _selected_objrr5lendatetime timedeltar6Z timedelta64ranyrE_deltasr3r4r;_comonesrTshaperKrC) selfrTrGr-r.r/rHrIrJrKr?rLrO __class__r9r:r[^sp      z ExponentialMovingWindow.__init__r>r])startendnum_valsr0cCsdSNr9)rlrorprqr9r9r:_check_window_boundssz,ExponentialMovingWindow._check_window_boundsrr0cCstS)z[ Return an indexer class that will compute the window start and end bounds )rrlr9r9r:_get_window_indexersz+ExponentialMovingWindow._get_window_indexernumbaOnlineExponentialMovingWindowcCs8t|j|j|j|j|j|j|j|j|j |j |||j d S)a Return an ``OnlineExponentialMovingWindow`` object to calculate exponentially moving window aggregations in an online method. .. versionadded:: 1.3.0 Parameters ---------- engine: str, default ``'numba'`` Execution engine to calculate online aggregations. Applies to all supported aggregation methods. engine_kwargs : dict, default None Applies to all supported aggregation methods. * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil`` and ``parallel`` dictionary keys. The values must either be ``True`` or ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is ``{{'nopython': True, 'nogil': False, 'parallel': False}}`` and will be applied to the function Returns ------- OnlineExponentialMovingWindow ) rTrGr-r.r/rHrIrJrKr?engine engine_kwargsrO) rxrTrGr-r.r/rHrIrJrKr?Z _selection)rlryrzr9r9r:onlineszExponentialMovingWindow.online aggregatezV See Also -------- pandas.DataFrame.rolling.aggregate a Examples -------- >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}) >>> df A B C 0 1 4 7 1 2 5 8 2 3 6 9 >>> df.ewm(alpha=0.5).mean() A B C 0 1.000000 4.000000 7.000000 1 1.666667 4.666667 7.666667 2 2.428571 5.428571 8.428571 zSeries/Dataframe)Zsee_alsoZexamplesklassrKcstj|f||Srr)rZr|rlfuncargskwargsrmr9r:r|sz!ExponentialMovingWindow.aggregateZ ParametersZReturnszSee AlsoZNotes r1ewmz"(exponential weighted moment) meanmean)Z window_methodZaggregation_descriptionZ agg_method)ryrz) numeric_onlyc Ostt|d||t|rf|jdkr*t}nt}|ft||j|j|j t |j dd}|j |ddS|dkr|dk r~t dtd|||jdkrdn|j }ttj|j|j|j |dd} |j | d|dSt d dS) NrrMTrGrIrJdeltas normalizenameZcythonN+cython engine does not accept engine_kwargsrr)engine must be either 'numba' or 'cython')rtyperrLr$r%rrirIrJtuplerh_applyr5nvvalidate_window_funcr?rwindow_aggregationsr rlrryrzrrrZewm_funcr window_funcr9r9r:rs:  zExponentialMovingWindow.meanz!(exponential weighted moment) sumsumc Ostt|d|||js tdt|rt|jdkr8t}nt}|ft||j |j|j t |j dd}|j |ddS|dkr|dk rtdtd|||jdkrdn|j }ttj|j |j|j |dd} |j | d|d Std dS) Nrz(sum is not implemented with adjust=FalserMFrrrrrr)rrrIr^rrLr$r%rrirJrrhrr5rrr?rrrrr9r9r:rIs>  zExponentialMovingWindow.sumzc bias : bool, default False Use a standard estimation bias correction. z0(exponential weighted moment) standard deviationstdbiasrcOsjtt|d||td|||rP|jjdkrPt|jjsPtt|j dt |j f||d|S)Nrr1z$.std does not implement numeric_onlyr) rrrrrcndimrrAr^__name__rvar)rlrrrrr9r9r:rs  zExponentialMovingWindow.stdrcOs$tjdttd|j|f||S)NzGvol is deprecated will be removed in a future version. Use std instead.rX)r`rarbrrrlrrrr9r9r:vols zExponentialMovingWindow.volz&(exponential weighted moment) variancercsZtt|d||td||tj}t||j|j|j |dfdd}|j |d|dS)Nr)rGrIrJrcs|||||Srrr9)valuesbeginrprHZwfuncr9r:var_funcsz-ExponentialMovingWindow.var..var_funcr) rrrrrewmcovrrirIrJr)rlrrrrrrr9rr:rs zExponentialMovingWindow.vara other : Series or DataFrame , optional If not supplied then will default to self and produce pairwise output. pairwise : bool, default None If False then only matching columns between self and other will be used and the output will be a DataFrame. If True then all pairwise combinations will be calculated and the output will be a MultiIndex DataFrame in the case of DataFrame inputs. In the case of missing elements, only complete pairwise observations will be used. bias : bool, default False Use a standard estimation bias correction. z/(exponential weighted moment) sample covariancecovDataFrame | Series | None bool | Noneotherpairwiserrc sNddlmttdd|d|fdd}j||||S)Nrr rc s|}|}}jdk r,jn|j}|jt||jjjd\}}t |||j|j j j  }||j|jdS)NZ num_valuesrHrVrWstepindexr) _prep_valuesrvrH window_sizeget_window_boundsrdrVrWrrrrirIrJrr) xyx_arrayy_arraywindow_indexerrHrorpresultr rrlr9r:cov_funcs4    z-ExponentialMovingWindow.cov..cov_funcpandasr rrZ_validate_numeric_onlyZ_apply_pairwiserc)rlrrrrrrr9rr:rs%  zExponentialMovingWindow.covaL other : Series or DataFrame, optional If not supplied then will default to self and produce pairwise output. pairwise : bool, default None If False then only matching columns between self and other will be used and the output will be a DataFrame. If True then all pairwise combinations will be calculated and the output will be a MultiIndex DataFrame in the case of DataFrame inputs. In the case of missing elements, only complete pairwise observations will be used. z0(exponential weighted moment) sample correlationcorrrrrc sLddlmttdd|d|fdd}j||||S)Nrrrc s|}|}}jdk r,jn|j|jt|jjjd\fdd}t j dd4|||}|||}|||}|t ||} W5QRX| |j |j dS)Nrc s t||jjjd S)NT)rrrirIrJ)XY)rprHrlror9r:_cov\sz.cov_func.._covignore)allr)rrvrHrrrdrVrWrr6Zerrstaterrr) rrrrrrrZx_varZy_varrr rl)rprHror:rKs*       z.ExponentialMovingWindow.corr..cov_funcr)rlrrrrrr9rr:r$s"  %zExponentialMovingWindow.corr) NNNNrTFrNrM)rwN)F)F)FF)F)FF)NNFF)NNF) r __module__ __qualname____doc__ _attributesr[rsrvr{rrrr|Zaggr rrrr#rr!r"rreplacerrrrrrr __classcell__r9r9rmr:rFslF,U, ) +    0  rFcsFeZdZdZejejZddddfddZddd d ZZ S) ExponentialMovingWindowGroupbyzF Provide an exponential moving window groupby implementation. N)_grouperrSrtcs\tj|f|d|i||jsX|jdk rXtt|jj }t |j ||j |_ dS)Nr)rZr[emptyr?r6 concatenatelistrindicesrrEZtaker.rh)rlrTrrrZ groupby_orderrmr9r:r[|s z'ExponentialMovingWindowGroupby.__init__rcCst|jjtd}|S)z Return an indexer class that will compute the window start and end bounds Returns ------- GroupbyIndexer )Zgroupby_indicesr)rrrr)rlrr9r9r:rvs z2ExponentialMovingWindowGroupby._get_window_indexer) rrrrrFrr)r[rvrr9r9rmr:rus  rcseZdZd)dddddd dd d d d d dddd fddZddddZddZd*d dddZd+ddd ddd Zd,ddd d d!d"d#Zd-d dd$d%Z ddd&d'd(Z Z S).rxNrTFrwrNr r*r=rPrQrr<rRzdict[str, bool] | NonerS) rTrGr-r.r/rHrIrJrKr?ryrzr0c  sp| dk rtdtj||||||||| | | d t|j|j|j|j|j|_ t | rd| |_ | |_ nt ddS)Nz0times is not implemented with online operations.) rTrGr-r.r/rHrIrJrKr?rOz$'numba' is the only supported engine)r^rZr[r&rirIrJrKrk_meanrryrzr5)rlrTrGr-r.r/rHrIrJrKr?ryrzrOrmr9r:r[s8 z&OnlineExponentialMovingWindow.__init__rtcCs|jdS)z= Reset the state captured by `update` calls. N)rresetrur9r9r:rsz#OnlineExponentialMovingWindow.resetcOstSrrr^rr9r9r:r|sz'OnlineExponentialMovingWindow.aggregatercOstSrrrrr9r9r:rsz!OnlineExponentialMovingWindow.stdrrrcKstSrrr)rlrrrrr9r9r:rsz"OnlineExponentialMovingWindow.corrrcKstSrrr)rlrrrrrr9r9r:rsz!OnlineExponentialMovingWindow.covcOstSrrrrr9r9r:rsz!OnlineExponentialMovingWindow.var)update update_timesc Osri}|jjdkrdnd}|dk r*tdn(tjt|jj|jdddtjd}|dk r|j j dkrnt d d}|j |d <|r|j j tj ddf} |j|d <n|j j } |j|d <t| |f} n@d}|jj |d <|r|jj|d <n |jj|d <|jtj} tft|j} |j |r(| n| ddtj f||j| } |sR| } | |d} |jj| f|} | S) a[ Calculate an online exponentially weighted mean. Parameters ---------- update: DataFrame or Series, default None New values to continue calculating the exponentially weighted mean from the last values and weights. Values should be float64 dtype. ``update`` needs to be ``None`` the first time the exponentially weighted mean is calculated. update_times: Series or 1-D np.ndarray, default None New times to continue calculating the exponentially weighted mean from the last values and weights. If ``None``, values are assumed to be evenly spaced in time. This feature is currently unsupported. Returns ------- DataFrame or Series Examples -------- >>> df = pd.DataFrame({"a": range(5), "b": range(5, 10)}) >>> online_ewm = df.head(2).ewm(0.5).online() >>> online_ewm.mean() a b 0 0.00 5.00 1 0.75 5.75 >>> online_ewm.mean(update=df.tail(3)) a b 2 1.615385 6.615385 3 2.550000 7.550000 4 3.520661 8.520661 >>> online_ewm.reset() >>> online_ewm.mean() a b 0 0.00 5.00 1 0.75 5.75 r2TFNz update_times is not implemented.r1rr@z;Must call mean with update=None first before passing updatercolumnsr)rcrr^r6rjr\rkrKrCrZlast_ewmr5rZnewaxisrrrZto_numpyZastyper'rrzZrun_ewmrHZsqueezeZ _constructor) rlrrrrZ result_kwargsZis_frameZ update_deltasZ result_from last_valueZnp_arrayZ ewma_funcrr9r9r:rsR,        z"OnlineExponentialMovingWindow.mean) NNNNrTFrNrwN)F)NNF)NNFF)F) rrrr[rr|rrrrrrr9r9rmr:rxs8.+  rx)N __future__rre functoolsrtextwraprtypingrrr`Znumpyr6Zpandas._libs.tslibsrZ pandas._libs.window.aggregationsZ_libsZwindowZ aggregationsrZpandas._typingrr rr r Zpandas.core.genericr Zpandas.compat.numpyr rZpandas.util._decoratorsrZpandas.util._exceptionsrZpandas.core.dtypes.commonrrZpandas.core.dtypes.missingrZpandas.core.commoncorer3Zpandas.core.indexers.objectsrrrZpandas.core.util.numba_rrZpandas.core.window.commonrrZpandas.core.window.docrrrrrrr r!r"r#Zpandas.core.window.numba_r$r%Zpandas.core.window.onliner&r'Zpandas.core.window.rollingr(r)r;rErFrrxr9r9r9r:sF         0 ! n!