M/Ph#ZdZddlmZmZddlZddlZddlm Z ddl m Z ddl m Z ddlmZmZmZmZmZddlmZdd lmZdd lmZdd lmZdd lmZdd lmZm Z erddl!Z"de#dej$dej$fdZ%GddZ&GddZ'dS)a Implementation of the Theta forecasting method of Assimakopoulos, V., & Nikolopoulos, K. (2000). The theta model: a decomposition approach to forecasting. International journal of forecasting, 16(4), 521-530. and updates in Hyndman, R. J., & Billah, B. (2003). Unmasking the Theta method. International Journal of Forecasting, 19(2), 287-290. Fioruci, J. A., Pellegrini, T. R., Louzada, F., & Petropoulos, F. (2015). The optimized theta method. arXiv preprint arXiv:1503.03529. ) TYPE_CHECKINGOptionalN)stats)Summary) SimpleTable) array_like bool_like float_likeint_like string_like)DeterministicTerm)seasonal_decompose)ExponentialSmoothing)SARIMAX)acf) add_trendfreq_to_periodstepsindexreturnc,tj||S)N)r _extend_index)rrs a/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/statsmodels/tsa/forecasting/theta.py extend_indexr+s  *5% 8 88c (eZdZdZdddddddeeded ed ed ed df d ZddZ d e e j e j ffdZ ddeded dfdZed efdZed efdZed efdZed efdZed efdZdS) ThetaModelaS The Theta forecasting model of Assimakopoulos and Nikolopoulos (2000) Parameters ---------- endog : array_like, 1d The data to forecast. period : int, default None The period of the data that is used in the seasonality test and adjustment. If None then the period is determined from y's index, if available. deseasonalize : bool, default True A flag indicating whether the deseasonalize the data. If True and use_test is True, the data is only deseasonalized if the null of no seasonal component is rejected. use_test : bool, default True A flag indicating whether test the period-th autocorrelation. If this test rejects using a size of 10%, then decomposition is used. Set to False to skip the test. method : {"auto", "additive", "multiplicative"}, default "auto" The model used for the seasonal decomposition. "auto" uses a multiplicative if y is non-negative and all estimated seasonal components are positive. If either of these conditions is False, then it uses an additive decomposition. difference : bool, default False A flag indicating to difference the data before testing for seasonality. See Also -------- statsmodels.tsa.statespace.exponential_smoothing.ExponentialSmoothing Exponential smoothing parameter estimation and forecasting statsmodels.tsa.statespace.sarimax.SARIMAX Seasonal ARIMA parameter estimation and forecasting Notes ----- The Theta model forecasts the future as a weighted combination of two Theta lines. This class supports combinations of models with two thetas: 0 and a user-specified choice (default 2). The forecasts are then .. math:: \hat{X}_{T+h|T} = \frac{\theta-1}{\theta} b_0 \left[h - 1 + \frac{1}{\alpha} - \frac{(1-\alpha)^T}{\alpha} \right] + \tilde{X}_{T+h|T} where :math:`\tilde{X}_{T+h|T}` is the SES forecast of the endogenous variable using the parameter :math:`\alpha`. :math:`b_0` is the slope of a time trend line fitted to X using the terms 0, 1, ..., T-1. The model is estimated in steps: 1. Test for seasonality 2. Deseasonalize if seasonality detected 3. Estimate :math:`\alpha` by fitting a SES model to the data and :math:`b_0` by OLS. 4. Forecast the series 5. Reseasonalize if the data was deseasonalized. The seasonality test examines where the autocorrelation at the seasonal period is different from zero. The seasonality is then removed using a seasonal decomposition with a multiplicative trend. If the seasonality estimate is non-positive then an additive trend is used instead. The default deseasonalizing method can be changed using the options. References ---------- .. [1] Assimakopoulos, V., & Nikolopoulos, K. (2000). The theta model: a decomposition approach to forecasting. International Journal of Forecasting, 16(4), 521-530. .. [2] Hyndman, R. J., & Billah, B. (2003). Unmasking the Theta method. International Journal of Forecasting, 19(2), 287-290. .. [3] Fioruci, J. A., Pellegrini, T. R., Louzada, F., & Petropoulos, F. (2015). The optimized theta method. arXiv preprint arXiv:1503.03529. NTautoF)period deseasonalizeuse_testmethod differencerr r!r"r#rct|dd|_t|tjr|jdddf|_n||_t|dd|_t|d|_ t|d o|j |_ t|d |_ t|d d |_|jdkr&|jdkrdnd|_|jf|j r_t!|dd}d}|$t!|dd}|t!|dd}|t#||_nt%d|j |_dS)Nendog)ndimrrT)optionalr r!r#model)radditivemultiplicativemuladd)optionsrr,r-rfreq inferred_freqzkYou must specify a period or endog must be a pandas object with a DatetimeIndex with a freq not set to None)r_y isinstancepd DataFrameiloc endog_origr _periodr _deseasonalize _use_test_diffr _methodmingetattrr ValueError_has_seasonality) selfr%rr r!r"r#idxpfreqs r__init__zThetaModel.__init__sUG!444 eR\ * * $#jA.DOO#DO4@@@ ' GG h + + C0C z<88 "  H    <6 ! !$(GKKMMA$5$5555DL < D$7 %$//CEVT22=#C$??E -e44  - !% 3rc|j}|jrtj|}t ||jd}|jd}||ddzztj|dddzz }|dk|_dS)NT)nlagsfftrgi@) r1r:npdiffrr7shapesumr?)r@yrhonobsstats r_test_seasonalityzThetaModel._test_seasonalitys G :  A!4 %  " " $ $ $..00 8  '!9C888C''t'$$CZ ++F1IMEqyy))7EAI*>??CJ//BBZF||A+HH1dD111!!!RaR%8B qqq!tHHHMHHHIOOBO66q9EAr&1Wctcnn JqMEF||AH vx7D   rc|jS)z!Whether to deseasonalize the data)r8r@s rr zThetaModel.deseasonalize s ""rc|jS)zThe period of the seasonality)r7rus rrzThetaModel.period |rc|jS)z(Whether to test the data for seasonality)r9rus rr!zThetaModel.use_tests ~rc|jS)z7Whether the data is differenced in the seasonality test)r:rus rr#zThetaModel.differences zrc|jS)z)The method used to deseasonalize the data)r;rus rr"zThetaModel.method rwr)rN)FF)__name__ __module__ __qualname____doc__rintboolstrrCrQtuplerIndarrayrVrgpropertyr rr!r#r"rrrr/sNNh!%" ,4,4,4 ,4  ,4  ,4,4,4 ,4,4,4,4\9999 BU2:rz+A%B B B B B38E E E +/E E E E E N#t###X#X$XDXXrrcveZdZdZdededeededejdede d d fd Z e d e j fd Ze d efd Ze d e fdZddeded e j fdZdded e jfdZd efdZ d dededed e jfdZ d!dededeedededdeeefd dfdZd S)"rYa6 Results class from estimated Theta Models. Parameters ---------- b0 : float The estimated trend slope. alpha : float The estimated SES parameter. sigma2 : float The estimated residual variance from the SES/IMA model. one_step : float The one-step forecast from the SES. seasonal : ndarray An array of estimated seasonal terms. use_mle : bool A flag indicating that the parameters were estimated using MLE. model : ThetaModel The model used to produce the results. rprorqrrrTrWr)rNc||_||_||_||_|jjd|_||_||_||_ dS)Nr) _b0_alpha_sigma2 _one_stepr6rK_nobs_model _seasonal_use_mle)r@rprorqrrrTrWr)s rrCzThetaModelResults.__init__<sK  !%+A.  ! rcJtj|j|jgddgS)z The forecasting model parametersrpror)r3Seriesrrrus rrizThetaModelResults.paramsOs&y$(DK0wHHHHrc|jVt|jjdd}|d}t j|jd|_|jJ|jS)zThe estimated residual varianceNr[r\r]Fr`rG)rrr)r1rgrIrhri)r@rnrUs rrqzThetaModelResults.sigma2Tse < $*-yDDDC''u'%%C:cj11"5DL|'''|rc|jS)z%The model used to produce the results)rrus rr)zThetaModelResults.model^s {rr&rHrthetac&t|d}|dkrtdt|d}|dkrtddtjtjjz }||kr|dz |z nd}||}||jztj |j z}|j j rCtj |j }|j jd r||z}n||z }d |_|S) a Forecast the model for a given theta Parameters ---------- steps : int The number of steps ahead to compute the forecast components. theta : float The theta value to use when computing the weight to combine the trend and the SES forecasts. Returns ------- Series A Series containing the forecasts Notes ----- The forecast is computed as .. math:: \hat{X}_{T+h|T} = \frac{\theta-1}{\theta} b_0 \left[h - 1 + \frac{1}{\alpha} - \frac{(1-\alpha)^T}{\alpha} \right] + \tilde{X}_{T+h|T} where :math:`\tilde{X}_{T+h|T}` is the SES forecast of the endogenous variable using the parameter :math:`\alpha`. :math:`b_0` is the slope of a time trend line fitted to X using the terms 0, 1, ..., T-1. This expression follows from [1]_ and [2]_ when the combination weights are restricted to be (theta-1)/theta and 1/theta. This nests the original implementation when theta=2 and the two weights are both 1/2. References ---------- .. [1] Hyndman, R. J., & Billah, B. (2003). Unmasking the Theta method. International Journal of Forecasting, 19(2), 287-290. .. [2] Fioruci, J. A., Pellegrini, T. R., Louzada, F., & Petropoulos, F. (2015). The optimized theta method. arXiv preprint arXiv:1503.03529. rr& steps must be a positive integerrztheta must be a float >= 1g@?)rr,rk)r r>r rIfinfodoubleepsforecast_componentsr_rhsesr)r rTr" startswithname)r@rrthresh trend_weightcompfcastrTs rrkzThetaModelResults.forecastcs\(( 199?@@ @5'** 1999:: :rx **...3fnn U**# ''e'44tz)BJtx,@,@@ : # "z$-00Hz ++E22 "!!  rcZt|d}|dkrtd|j}|j}|j}t jd|dzt jdz }|dkr|d|z d|z |z|z z z }||z}|jt j |z}|j j drt j |}nt j |}|j jrI|j} |j j} |t j|z} | | z} | jdr | | |dd<t%|j jdd} | *t)jd|j jjd} t-|| } t)j|||d | }|S) a Compute the three components of the Theta model forecast Parameters ---------- steps : int The number of steps ahead to compute the forecast components. Returns ------- DataFrame A DataFrame with three columns: trend, ses and seasonal containing the forecast values of each of the three components. Notes ----- For a given value of :math:`\theta`, the deseasonalized forecast is `fcast = w * trend + ses` where :math:`w = \frac{theta - 1}{theta}`. The reseasonalized forecasts are then `seasonal * fcast` if the seasonality is multiplicative or `seasonal + fcast` if the seasonality is additive. rr&r)dtyperr-Nr)r_rrTr)r r>rrrrIarangefloat64ronesr)r"rzerosr rrrKr=r6r3 RangeIndexrr4)r@rrorprOhr_rseasonrTroos_idx seasonal_locsrdfs rrz%ThetaModelResults.forecast_componentss.(( 199?@@ @  Xz Ia"* 5 5 5 9 199 Uq5yT1E9: :AQnrwu~~- :  ' ' . . $Xe__FFWU^^F : # 4~HZ&FRYu---G#f,M~a  4$]3qqq  -w== =M!TZ%:%@%CDDEUE** \CV < EB,Ah'' 334F teBi00<<<= =FF!ffc%"2"8";<<=F5+VW==H z *  !    $ &)   !& 7 7 > > N  J !3tz??"3 4 U%8!9!9 : ;   /   &1U\!2!2 34"J"J        rB4j\A- . . .  %    $("23GG z$+&&qqq$w/   : & " # #'     2 r皙?c\|jjd}dtj|d|dz dzzzz|jz}tj|}t j|dz }| ||}tj |||zz||| zzdS)a/ Parameters ---------- steps : int, default 1 The number of steps ahead to compute the forecast components. theta : float, default 2 The theta value to use when computing the weight to combine the trend and the SES forecasts. alpha : float, default 0.05 Significance level for the confidence intervals. Returns ------- DataFrame DataFrame with columns lower and upper Notes ----- The variance of the h-step forecast is assumed to follow from the integrated Moving Average structure of the Theta model, and so is :math:`\sigma^2(1 + (h-1)(1 + (\alpha-1)^2)`. The prediction interval assumes that innovations are normally distributed. r&rH)lowerupper) rir5rIrrqsqrtrnormppfrkr3r4) r@rrro model_alphasigma2_hsigma_hquantile predictionss rprediction_intervalsz&ThetaModelResults.prediction_intervals)s4k&q)  %  AqQ(>$>? ? K'(##:>>%!),,mmE511 |$w'99$w('::     rF in_samplefigzmatplotlib.figure.Figurefigsizecddlm}m}||||}|J|||} | j} |d} |jjjd} tj tj | } |rUt|jjtjr|jjj} | | |jj| | | |G||||}d|z dd}| | |d|d d d | | d d|d|S)a Plot forecasts, prediction intervals and in-sample values Parameters ---------- steps : int, default 1 The number of steps ahead to compute the forecast components. theta : float, default 2 The theta value to use when computing the weight to combine the trend and the SES forecasts. alpha : {float, None}, default 0.05 The tail probability not covered by the confidence interval. Must be in (0, 1). Confidence interval is constructed assuming normally distributed shocks. If None, figure will not show the confidence interval. in_sample : bool, default False Flag indicating whether to include the in-sample period in the plot. fig : Figure, default None An existing figure handle. If not provided, a new figure is created. figsize: tuple[float, float], default None Tuple containing the figure size. Returns ------- Figure Figure handle containing the plot. Notes ----- The variance of the h-step forecast is assumed to follow from the integrated Moving Average structure of the Theta model, and so is :math:`\sigma^2(\alpha^2 + (h-1))`. The prediction interval assumes that innovations are normally distributed. r) _import_mplcreate_mpl_figNor&z.0%z confidence intervalrrgrayg?)colorrolabelbestF)locframeonr)pad)statsmodels.graphics.utilsrrrkr add_subplotr)r6rKr3IndexrIrr2rplotr fill_betweenlegend tight_layout)r@rrrorrrrrr pred_indexaxrOrpirs r plot_predictzThetaModelResults.plot_predictQsZ KJJJJJJJ nS'**mmE511  & __S ! !z$*1-4))  2$*/;; 4 -3 GGE4:0 1 1 1  K(((  **5%??B5y::::E OO7 7      fe ,,, S!!! r)r&rH)r&)r&rHr)r&rHrFNN)r{r|r}r~floatrrIrrrrCrr3rrirqr)rrkr4rrrrrrrrrrYrY&s[*       *         &I IIIXIXzXAAcAeABIAAAAF666R\6666pIIIIIX@D& & & %*& 7<& & & & & T!%48'+LLLL L  L 0 1 Lue|$L $LLLLLLrrY)(r~typingrrnumpyrIpandasr3scipyrstatsmodels.iolib.summaryrstatsmodels.iolib.tablerstatsmodels.tools.validationrr r r r statsmodels.tsa.deterministicr statsmodels.tsa.seasonalr0statsmodels.tsa.statespace.exponential_smoothingr"statsmodels.tsa.statespace.sarimaxrstatsmodels.tsa.stattoolsrstatsmodels.tsa.tsatoolsrrmatplotlib.figure matplotlibrrrrrYrrrr s  +*******------//////<;;;;;777777766666))))))>>>>>>>>99BH99999ttttttttnwwwwwwwwwwr