!gWHZddlmZmZddlZddlmZmZmZddl Z ddl Z ddl mZddlmZmZddlmZmZmZddlmZddlmZmZdd lmZmZdd lmZee e!eje jDe jFfZ$eejJZ&e&jOd ed d dge&jOd edddge&jQgdZ)eejTjJZ&e&jQddgZ+eee)dGddZ,GddZ-y)) Substitution is_int_indexN)AnyOptionalUnion) PandasData) SimpleTableSummary) Docstring Parameterindent)PredictionResults) get_index_locget_prediction_index)STLDecomposeResult)_check_dynamicendogmodelModelzQThe model used to forecast endog after the seasonality has been removed using STL model_kwargszdict[str, Any]zuAny additional arguments needed to initialized the model using the residuals produced by subtracting the seasonality.)rrrperiodseasonaltrendlow_pass seasonal_deg trend_deg low_pass_degrobust seasonal_jump trend_jump low_pass_jump inner_iter outer_iterz )stl_forecast_paramsc heZdZdZddddddddddddd dZeeed dddd d Zy) STLForecasta Model-based forecasting using STL to remove seasonality Forecasts are produced by first subtracting the seasonality estimated using STL, then forecasting the deseasonalized data using a time-series model, for example, ARIMA. Parameters ---------- %(stl_forecast_params)s See Also -------- statsmodels.tsa.arima.model.ARIMA ARIMA modeling. statsmodels.tsa.ar_model.AutoReg Autoregressive modeling supporting complex deterministics. statsmodels.tsa.exponential_smoothing.ets.ETSModel Additive and multiplicative exponential smoothing with trend. statsmodels.tsa.statespace.exponential_smoothing.ExponentialSmoothing Additive exponential smoothing with trend. Notes ----- If :math:`\hat{S}_t` is the seasonal component, then the deseasonalize series is constructed as .. math:: Y_t - \hat{S}_t The trend component is not removed, and so the time series model should be capable of adequately fitting and forecasting the trend if present. The out-of-sample forecasts of the seasonal component are produced as .. math:: \hat{S}_{T + h} = \hat{S}_{T - k} where :math:`k = m - h + m \lfloor (h-1)/m \rfloor` tracks the period offset in the full cycle of 1, 2, ..., m where m is the period length. This class is mostly a convenience wrapper around ``STL`` and a user-specified model. The model is assumed to follow the standard statsmodels pattern: * ``fit`` is used to estimate parameters and returns a results instance, ``results``. * ``results`` must exposes a method ``forecast(steps, **kwargs)`` that produces out-of-sample forecasts. * ``results`` may also exposes a method ``get_prediction`` that produces both in- and out-of-sample predictions. See the notebook `Seasonal Decomposition <../examples/notebooks/generated/stl_decomposition.html>`__ for an overview. Examples -------- >>> import numpy as np >>> import pandas as pd >>> from statsmodels.tsa.api import STLForecast >>> from statsmodels.tsa.arima.model import ARIMA >>> from statsmodels.datasets import macrodata >>> ds = macrodata.load_pandas() >>> data = np.log(ds.data.m1) >>> base_date = f"{int(ds.data.year[0])}-{3*int(ds.data.quarter[0])+1}-1" >>> data.index = pd.date_range(base_date, periods=data.shape[0], freq="QS") Generate forecasts from an ARIMA >>> stlf = STLForecast(data, ARIMA, model_kwargs={"order": (2, 1, 0)}) >>> res = stlf.fit() >>> forecasts = res.forecast(12) Generate forecasts from an Exponential Smoothing model with trend >>> from statsmodels.tsa.statespace import exponential_smoothing >>> ES = exponential_smoothing.ExponentialSmoothing >>> config = {"trend": True} >>> stlf = STLForecast(data, ES, model_kwargs=config) >>> res = stlf.fit() >>> forecasts = res.forecast(12) NF) rrrrrrrrrr r!r"c ||_t|||||| | | | | | |_||_|in||_t |ds t dy)N) rrrrrrrrr r!r"fitz$model must expose a ``fit`` method.)_endogdict _stl_kwargs_model _model_kwargshasattrAttributeError)selfrrrrrrrrrrrr r!r"s \/var/www/dash_apps/app1/venv/lib/python3.12/site-packages/statsmodels/tsa/forecasting/stl.py__init__zSTLForecast.__init__sl$ %%'!'   #/#7R\ue$ !GH H%z ) fit_params)r#r$ fit_kwargscd|in|}t|jfi|j}|j||}|j|j z}|j |fi|j}|jdi|}t|ds tdt|||||jS)a Estimate STL and forecasting model parameters. Parameters ---------- %(fit_params)s fit_kwargs : dict[str, Any] Any additional keyword arguments to pass to ``model``'s ``fit`` method when estimating the model on the decomposed residuals. Returns ------- STLForecastResults Results with forecasting methods. )r#r$forecastz5The model's result must expose a ``forecast`` method.) rr,r.r+rresidr/r0r1r2STLForecastResults) r3r#r$r8stlstl_fit model_endogmodress r4r+zSTLForecast.fits &-R: $++2!1!12#&77!j$+$ mmgmm3 dkk+<););<cgg# #sJ' G "#wS$++FFr6) __name__ __module__ __qualname____doc__r5rr _fit_paramsr+r;r6r4r'r'As_St!#IJVK9: $$G;Gr6r'c eZdZdZdededdfdZedefdZ edefdZ edefd Z ede fd Z ede fd Zdefd Zd eedeedeeefdej,fdZ ddedeej2deej4ej,ffdZ ddedeee fdeej,ej4ffdZ dd eedeedeeefdeee ffdZy)r=a Results for forecasting using STL to remove seasonality Parameters ---------- stl : STL The STL instance used to decompose the data. result : DecomposeResult The result of applying STL to the data. model : Model The time series model used to model the non-seasonal dynamics. model_result : Results Model results instance supporting, at a minimum, ``forecast``. r>resultreturnNcP||_||_||_||_t j ||_|j jd|_t|dtj|j|_ t|jtjtjfsrIr model_resultrs r4r5zSTLForecastResults.__init__s   )jj' [[&&q) eWbmmDJJ.GH t{{R%5%5r~~$F GDKK( 8 nnT[[9 ) H  8 mmDJJ7  8s$C55-D%$D%c.|jjS)z$The period of the seasonal component)rMrr3s r4rzSTLForecastResults.periodsyyr6c|jS)z2The STL instance used to decompose the time series)rMr_s r4r>zSTLForecastResults.stlsyyr6c|jS)z&The result of applying STL to the data)rNr_s r4rIzSTLForecastResults.result s||r6c|jS)z3The model fit to the additively deseasonalized data)r/r_s r4rzSTLForecastResults.models{{r6c|jS)z)The result class from the estimated model)rOr_s r4r]zSTLForecastResults.model_results!!!r6cB t|jds td|jj}t |t s t dd|jdjz|jd_|jj}d}g}g}g}g}|D] j}|jdd}|d vr|d z }t fd |D} |d z }|d } t| d} | r$|j| |j| g|jd| z|j| gt!|t#|d} | j%t!|||jj| |S)aJ Summary of both the STL decomposition and the model fit. Returns ------- Summary The summary of the model fit and the STL decomposition. Notes ----- Requires that the model's result class supports ``summary`` and returns a ``Summary`` object. summaryz3The model result does not have a summary attribute.z3The model result's summary is not a Summary object.zSTL Decomposition and r)rrr_ )TrendzLow Passz Lengthc3@K|]}j|ywN) startswith).0valkeys r4 z-STLForecastResults.summary..=sC##..-Cs:z<23sz>13sz zSTL Configuration)stubstitle)rq)r1rOr2rerXr TypeErrortablesrrrMconfig capitalizereplaceanystrappendr tuple extend_right)r3reru left_keys left_data left_stubs right_data right_stubsnewis_leftstubrmtabrns @r4rezSTLForecastResults.summaryst))95 E  --557'7+E  %w~~a'8'>'> > q!!4      )C.."C++c3'C++y CCCG 3JC$ZD%d+C!!$'  #'""7T>2!!3%( ) U:.6I  Z{CDc"r6startenddynamiccttj|j|j}|d}t |||j |j|\}}}}t|ttjtjfr t||j\}}}||z }n |durd}n|durd}|j }t||||\}}||dzn|} tj|j j"} | || } tj$d} | ||zdz|z } |j'| d| } n(|r&|j'|d} t)||z d}| |d} tj*| | f} | S) a Get STLs seasonal in- and out-of-sample predictions Parameters ---------- start : int, str, or datetime, optional Zero-indexed observation number at which to start forecasting, i.e., the first forecast is start. Can also be a date string to parse or a datetime type. Default is the the zeroth observation. end : int, str, or datetime, optional Zero-indexed observation number at which to end forecasting, i.e., the last forecast is end. Can also be a date string to parse or a datetime type. However, if the dates index does not have a fixed frequency, end must be an integer index if you want out of sample prediction. Default is the last observation in the sample. dynamic : bool, int, str, or datetime, optional Integer offset relative to `start` at which to begin dynamic prediction. Can also be an absolute date string to parse or a datetime type (these are not interpreted as offsets). Prior to this observation, true endogenous values will be used for prediction; starting with this observation and continuing through the end of prediction, forecasted endogenous values will be used instead. Returns ------- ndarray Array containing the seasibak predictions. rLNr)dataTFr))r)offset)rrUSeriesr,rWrrSrXrydtdatetime TimestamprrrPrQrNrempty_seasonal_forecastmaxr_)r3rrrr out_of_sampleprediction_indexrfnobs in_sample_endr predictionsoosnum oos_starts r4_get_seasonal_predictionz+STLForecastResults._get_seasonal_predictionNs}H"))DKK0 D =E8L 3 DKKd9 5]$4 gR[[",,? @)'4;;?MGQoG _G  Gzz#GUC> #*?a ::dll334u]3 hhtn  #%)G3C))#tG)DC ))->CEDL!,Iij/CeeK,- r6stepsrLc |j}tj|jj}| |j n|}|||z |}tj |||z||zdk7z}|d|}|tj||}|S)a Get the seasonal component of the forecast Parameters ---------- steps : int The number of steps required. index : pd.Index A pandas index to use. If None, returns an ndarray. offset : int The index of the first out-of-sample observation. If None, uses nobs. Returns ------- seasonal : {ndarray, Series} The seasonal component. Nrr) rrPrQrNrrStilerUr)r3rrLrrrs r4rz%STLForecastResults._seasonal_forecasts,::dll334%~6FVOf5778Uf_A8M%NOFU#  yy7Hr6kwargsc |jjdd|i|}t|tjr |j nd}||j ||zS)a Out-of-sample forecasts Parameters ---------- steps : int, str, or datetime, optional If an integer, the number of steps to forecast from the end of the sample. Can also be a date string to parse or a datetime type. However, if the dates index does not have a fixed frequency, steps must be an integer. Default **kwargs Additional arguments may required for forecasting beyond the end of the sample. These arguments are passed into the time series model results' ``forecast`` method. Returns ------- forecast : {ndarray, Series} Out of sample forecasts rNr;)rOr:rXrUrrLr)r3rrr:rLs r4r:zSTLForecastResults.forecastsT./4%%..EUEfE",Xryy"At$11%???r6c |jjd |||d|}|j|||}|j|z} |j}t!||d|j" S#t t f$rbddl} | jd|jjjdtdtj|jz}YwxYw) a In-sample prediction and out-of-sample forecasting Parameters ---------- start : int, str, or datetime, optional Zero-indexed observation number at which to start forecasting, i.e., the first forecast is start. Can also be a date string to parse or a datetime type. Default is the the zeroth observation. end : int, str, or datetime, optional Zero-indexed observation number at which to end forecasting, i.e., the last forecast is end. Can also be a date string to parse or a datetime type. However, if the dates index does not have a fixed frequency, end must be an integer index if you want out of sample prediction. Default is the last observation in the sample. dynamic : bool, int, str, or datetime, optional Integer offset relative to `start` at which to begin dynamic prediction. Can also be an absolute date string to parse or a datetime type (these are not interpreted as offsets). Prior to this observation, true endogenous values will be used for prediction; starting with this observation and continuing through the end of prediction, forecasted endogenous values will be used instead. **kwargs Additional arguments may required for forecasting beyond the end of the sample. These arguments are passed into the time series model results' ``get_prediction`` method. Returns ------- PredictionResults PredictionResults instance containing in-sample predictions, out-of-sample forecasts, and prediction intervals. )rrrrNz>The variance of the predicted mean is not available using the z model class.) stacklevelnorm)dist row_labelsr;)rOget_predictionrpredicted_mean var_pred_meanr2NotImplementedErrorwarningswarnr __class__rC UserWarningrPnancopyrr) r3rrrrpredseasonal_predictionmeanrrs r4rz!STLForecastResults.get_predictionsT1t!!00 S' 5; #;; 3 ""%88 1 ..M! -f   34 1  MMzz++445]D   FFTYY[0M 1s A))A.CCrj)r))NNF) rCrDrErFrrr5propertyintrr>rIrrr]r rerDateLikerboolrPndarrayrrUIndexrrr-ryr:rr;r6r4r=r=s 88 /8 8&   Ss"c""44lA!Ah AtX~& A  AH=A!)"((!3 ryy"**$ %B@@(,S#X@ rzz299$ %@:%)"&). @ !@ h @ tX~& @ sCx. @ r6r=).statsmodels.compat.pandasrrrrtypingrrrnumpyrPpandasrUstatsmodels.base.datarstatsmodels.iolib.summaryr r statsmodels.tools.docstringr r r statsmodels.tsa.base.predictionrstatsmodels.tsa.base.tsa_modelrrstatsmodels.tsa.seasonalrr(statsmodels.tsa.statespace.kalman_filterrrryr datetime64rrFdsinsert_parametersextract_parameters_stl_forecast_paramsr+rGr'r=r;r6r4rs.@'',:DD=N9C c2;; bmmC Ds{{        E  ,,&sww##\<$@A &)=v"FGWGWGHWGtp p r6