U MZf\@sddlmZddlZddlmZddlmZddlmZddl Z ddl m Z ddl mmmZddlmZmZerddlmZmZdd lmZdd lmZdd lmZmZdd lm Z dd l!m"Z"ddl#m$Z$m%Z%m&Z&ddl'm(Z(m)Z)ddl*m+Z+ddl,m-Z-m.Z.m/Z/m0Z0m1Z1m2Z2m3Z3m4Z4ddl5m6Z6m7Z7ddl8m9Z9m:Z:ddl;mddddddZ?Gd d!d!e<Z@Gd"d#d#e=e@ZAGd$d%d%e@ZBdS)&) annotationsN)partial)dedent) TYPE_CHECKING) Timedelta)AxisTimedeltaConvertibleTypes) DataFrameSeries)NDFrame)doc)is_datetime64_ns_dtypeis_numeric_dtype)isna)common) BaseIndexerExponentialMovingWindowIndexerGroupbyIndexer)get_jit_argumentsmaybe_use_numba)zsqrt) _shared_docscreate_section_headerkwargs_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)rcount_not_none ValueErrornpexplogr&)r'r(r)r*Z valid_countZdecayr3:/tmp/pip-unpacked-wheel-nbcvw55c/pandas/core/window/ewm.pyget_center_of_mass@s* r5znp.ndarray | NDFrame(float | TimedeltaConvertibleTypes | None np.ndarray)timesr)r+cCs:tj|tjtjd}tt|dj}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 : np.ndarray, Series 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 dtypens) r0ZasarrayviewZint64float64r&rZas_unit_valueZdiff)r8r)Z_timesZ _halflifer3r3r4_calculate_deltasasr?cseZdZdZdddddddd d d g Zd^d dddddddddddddd fddZddddd d!d"Zd#d$d%d&Zd_dd(d)d*d+Ze e d,e d-e d.d/d0d1fd2d3Z e Z e eed4eeed5eed6eed7ed8d0d9d:d;dd?d@Ze eed4eeed5eed6eed7ed8d0d9d:dAdBd= dadd>dCdDZe eed4e dEd8d0d9eed5eed6ed dFd:dGdHd= dbdddIdJdKZe eed4e dEd8d0d9eed5eed6ed dFd:dLdMd= dcdddIdNdOZe eed4e dPd8d0d9eed5eed6ed dFd:dQdRd= dddSdTdddUdVdWZe eed4e dXd8d0d9eed5eed6ed dFd:dYdZd= dedSdTdd[d\d]ZZS)fExponentialMovingWindowa& 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 : 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. 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_naaxisr8methodNrTFsingle selectionr r%r6 int | Noneboolrnp.ndarray | NDFrame | NonestrNone) objrAr(r)r*rBrCrDrEr8rFr+c  stj||dkrdn tt|dddd| | | d||_||_||_||_||_||_ | |_ |j dk r |jsvt dt |j st dt|j t|krt dt|jttjtjfst dt|j rt dt|j |j|_t|j|j|jd krt|j|jd|j|_nd |_nj|jdk rLt|jttjtjfrLt d tjt|jj|j dd tj!d |_t|j|j|j|j|_dS) Nr,F)rOrBoncenterclosedrFrErIz)times is not supported with adjust=False.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.r9)"super__init__maxintrAr(r)r*rCrDr8NotImplementedErrorr r/len isinstancerMdatetime timedeltar0Z timedelta64ranyr?_deltasrr.r5_comonesrOshaperEr=) selfrOrAr(r)r*rBrCrDrEr8rFrI __class__r3r4rTKsb    z ExponentialMovingWindow.__init__r7rV)startendnum_valsr+cCsdSNr3)rardrerfr3r3r4_check_window_boundssz,ExponentialMovingWindow._check_window_boundsrr+cCstS)z[ Return an indexer class that will compute the window start and end bounds )rrar3r3r4_get_window_indexersz+ExponentialMovingWindow._get_window_indexernumbaOnlineExponentialMovingWindow)enginer+cCs8t|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 ) rOrAr(r)r*rBrCrDrEr8rn engine_kwargsrI) rmrOrAr(r)r*rBrCrDrEr8Z _selection)rarnror3r3r4onlineszExponentialMovingWindow.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_alsoZexamplesklassrEcstj|f||Srg)rSrqrafuncargskwargsrbr3r4rqsz!ExponentialMovingWindow.aggregateZ ParametersZReturnszSee AlsoZNotes r,ewmz"(exponential weighted moment) meanmean)Z window_methodZaggregation_descriptionZ agg_method) numeric_onlyc Cst|rT|jdkrt}nt}|ft||j|j|jt|j dd}|j |ddS|dkr|dk rlt d|j dkrzdn|j }t tj|j|j|j|dd}|j |d|dSt d dS) NrGTrArCrDdeltas normalizerznameZcythonN+cython engine does not accept engine_kwargsrr{)engine must be either 'numba' or 'cython')rrFrr rr^rCrDtupler]_applyr/r8rwindow_aggregationsryrar{rnroruZewm_funcr} window_funcr3r3r4rzs6  zExponentialMovingWindow.meanz!(exponential weighted moment) sumsumc Cs|jstdt|rb|jdkr&t}nt}|ft||j|j|jt |j dd}|j |ddS|dkr|dk rzt d|j dkrdn|j }ttj|j|j|j|dd}|j |d|d St d dS) Nz(sum is not implemented with adjust=FalserGFr|rrrrrr)rCrWrrFrr rr^rDrr]rr/r8rrryrr3r3r4r$s:  zExponentialMovingWindow.sumzc bias : bool, default False Use a standard estimation bias correction. z0(exponential weighted moment) standard deviationstdbiasr{cCsB|r0|jjdkr0t|jjs0tt|jdt|j||dS)Nr,z$.std does not implement numeric_onlyr) _selected_objndimrr:rWtype__name__rvarrarr{r3r3r4rZs  zExponentialMovingWindow.stdz&(exponential weighted moment) variancercs:tj}t||j|j|j|dfdd}|j|d|dS)N)rArCrDrcs|||||Srgr3)valuesbeginrerBZwfuncr3r4var_funcsz-ExponentialMovingWindow.var..var_funcrr)rewmcovrr^rCrDr)rarr{rrr3rr4rxs 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 | Noneotherpairwiserr{cs<ddlmd|fdd}j||||S)Nrr rc s|}|}}jdk r,jn|j}|jt||jjjd\}}t |||j|j j j  }||j|jddS)NZ num_valuesrBrQrRstepFindexrcopy) _prep_valuesrkrB window_sizeget_window_boundsrXrQrRrrrr^rCrDrr) xyx_arrayy_arraywindow_indexerrBrdreresultr rrar3r4cov_funcs4    z-ExponentialMovingWindow.cov..cov_funcpandasr Z_validate_numeric_onlyZ_apply_pairwiser)rarrrr{rr3rr4rs#  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 correlationcorrrrr{cs:ddlmd|fdd}j||||S)Nrrrc s|}|}}jdk r,jn|j|jt|jjjd\fdd}t j dd4|||}|||}|||}|t ||} W5QRX| |j |j ddS)Nrc s t||jjjd S)NT)rrr^rCrD)XY)rerBrardr3r4_covsz.cov_func.._covignore)allFr)rrkrBrrrXrQrRrr0Zerrstaterrr) rrrrrrrZx_varZy_varrr ra)rerBrdr4rs*       z.ExponentialMovingWindow.corr..cov_funcr)rarrr{rr3rr4rs  %zExponentialMovingWindow.corr) NNNNrTFrNrG)rlN)FNN)FNN)FF)FF)NNFF)NNF)r __module__ __qualname____doc__ _attributesrTrhrkrpr rrrqZaggrrrrrrrreplacerzrrrrr __classcell__r3r3rbr4r@|sRC,I, % '    .  r@csFeZdZdZejejZddddfddZddd d ZZ S) ExponentialMovingWindowGroupbyzF Provide an exponential moving window groupby implementation. N)_grouperrNrics\tj|f|d|i||jsX|jdk rXtt|jj }t |j ||j |_ dS)Nr)rSrTemptyr8r0 concatenatelistrindicesrr?Ztaker)r])rarOrrvrwZ groupby_orderrbr3r4rT8s 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)rarr3r3r4rkCs z2ExponentialMovingWindowGroupby._get_window_indexer) rrrrr@rr$rTrkrr3r3rbr4r1s  rcseZdZd*dddddd dd d d d d dddd fddZddddZddZd+d dddZd,ddd ddd Zd-ddd d d!d"d#Zd.d d d$d%d&Z ddd'd(d)Z Z S)/rmNrTFrlrHr r%r6rJrKrrLrMzdict[str, bool] | NonerN) rOrAr(r)r*rBrCrDrEr8rnror+c  sp| dk rtdtj||||||||| | | d t|j|j|j|j|j|_ t | rd| |_ | |_ nt ddS)Nz0times is not implemented with online operations.) rOrAr(r)r*rBrCrDrEr8rIz$'numba' is the only supported engine)rWrSrTr!r^rCrDrEr`_meanrrnror/)rarOrAr(r)r*rBrCrDrEr8rnrorIrbr3r4rTSs8 z&OnlineExponentialMovingWindow.__init__ricCs|jdS)z= Reset the state captured by `update` calls. N)rresetrjr3r3r4r~sz#OnlineExponentialMovingWindow.resetcOs tddS)Nzaggregate is not implemented.rWrtr3r3r4rqsz'OnlineExponentialMovingWindow.aggregate)rcOs tddS)Nzstd is not implemented.r)rarrvrwr3r3r4rsz!OnlineExponentialMovingWindow.stdrrrcCs tddS)Nzcorr is not implemented.r)rarrr{r3r3r4rsz"OnlineExponentialMovingWindow.corrrcCs tddS)Nzcov is not implemented.r)rarrrr{r3r3r4rsz!OnlineExponentialMovingWindow.covrcCs tddS)Nzvar is not implemented.rrr3r3r4rsz!OnlineExponentialMovingWindow.var)update update_timesc Oshi}|jjdk}|dk r tdtjt|jj|jdddtjd}|dk r|j j dkrdt dd}|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| } |sH| } | |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 r-Nz update_times is not implemented.r,rr9z;Must call mean with update=None first before passing updatercolumnsr)rrrWr0r_rUr`rEr=rZlast_ewmr/rZnewaxisrrrZto_numpyZastyper"rroZrun_ewmrBZsqueezeZ _constructor) rarrrvrwZ result_kwargsZis_frameZ update_deltasZ result_from last_valueZnp_arrayZ ewma_funcrr3r3r4rzsR,        z"OnlineExponentialMovingWindow.mean) NNNNrTFrNrlN)F)NNF)NNFF)FF) rrrrTrrqrrrrrzrr3r3rbr4rmRs8.+  rm)C __future__rrZ functoolsrtextwraprtypingrZnumpyr0Zpandas._libs.tslibsrZ pandas._libs.window.aggregationsZ_libsZwindowZ aggregationsrZpandas._typingrrrr r Zpandas.core.genericr Zpandas.util._decoratorsr Zpandas.core.dtypes.commonr rZpandas.core.dtypes.missingrZ pandas.corerZpandas.core.indexers.objectsrrrZpandas.core.util.numba_rrZpandas.core.window.commonrZpandas.core.window.docrrrrrrrrZpandas.core.window.numba_rr Zpandas.core.window.onliner!r"Zpandas.core.window.rollingr#r$r5r?r@rrmr3r3r3r4s@          ( !:!