M/PhWH|ddlmZmZddlZddlmZmZmZddl Z ddl Z ddl mZddlmZmZddlmZmZmZddlmZddlmZmZdd lmZmZdd lmZee e!eje j"e j#fZ$eej%Z&e&'d ed d dge&'d edddge&(gdZ)eej*j%Z&e&(ddgZ+eee)dGddZ,GddZ-dS)) 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 |eZdZdZddddddddddddd dZeeed dddd d ZdS) 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 |dst ddS)N) rrrrrrrrr r!r"fitz$model must expose a ``fit`` method.)_endogdict _stl_kwargs_model _model_kwargshasattrAttributeError)selfrrrrrrrrrrrr r!r"s _/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/statsmodels/tsa/forecasting/stl.py__init__zSTLForecast.__init__s$ %%'!'     #/#7RR\ue$$ I !GHH H I Iz ) fit_params)r#r$ fit_kwargsc6|in|}t|jfi|j}|||}|j|jz}|j|fi|j}|jdi|}t|dstdt|||||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. N)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 &-RR: $+22!122#&77!j$+$ $ mgm3 dk+<<);<<cg## ##sJ''  G "#wS$+FFFr6) __name__ __module__ __qualname____doc__r5rr _fit_paramsr+r;r6r4r'r'AsSSt!#I#I#I#I#IJ\VVK99::: $$GGGG;:GGGr6r'c eZdZdZdededdfdZedefdZ edefdZ edefd Z ede fd Z ede fd Zdefd Zd eedeedeeefdejfdZ ddedeejdeejejffdZ ddedeee fdeejejffdZ dd eedeedeeefdeee ffdZdS)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>resultreturnNc||_||_||_||_t j||_|jjd|_t|dtj |j|_ t|j tjtjfsdt!|j sR tj|j |_ dS#t$$r"tj |j|_ YdSwxYwdSdS)Nrindex)_stl_resultr/ _model_resultnpasarrayr,shape_nobsgetattrpd RangeIndex_index isinstance DatetimeIndex PeriodIndexr to_datetime ValueError)r3r>rIr model_resultrs r4r5zSTLForecastResults.__init__s   )j'' [&q) eWbmDJ.G.GHH t{R%5r~$F G G 8DK(( 8 8 nT[99  8 8 8 mDJ77  8  8 8 8 8s:C(DDc|jjS)z$The period of the seasonal component)rMrr3s r4rzSTLForecastResults.periodsyr6c|jS)z2The STL instance used to decompose the time series)rMr_s r4r>zSTLForecastResults.stls yr6c|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 !!r6c t|jdstd|j}t |t st dd|jdjz|jd_|j j }d}g}g}g}g}|D]̊ }| dd}|d vr|d z }t fd |D} |d z }|d } t| d} | r,|| || g|d| z|| gt!|t#|d} | t!|||j| |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 Lengthc3BK|]}|VdSN) startswith).0valkeys r4 z-STLForecastResults.summary..=s/CC##..--CCCCCCr6: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)955  E  -5577'7++ E  %w~a'8'> > q!4      ) )C..""C++c3''C+++y CCCCCCCCCG 3JC==D%%,,C )!!$'''  #''''""7T>222!!3%(((( U:..6I    Z{CCCDDDc"""r6startenddynamiccttj|j|j}|d}t |||j|j|\}}}}t|ttj tj frt||j\}}}||z }n |durd}n|durd}|j}t||||\}}||dzn|} tj|jj} | || } tjd} |$||zdz|z } || d| } n5|r3||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_predictionNsH")DK00 DDD =E8L 3 DKd9 9 9 5]$4 gR[",? @ @ )'4;??MGQoGG __GG   Gz#GUC>> #*?a :dl344u]23 htnn  #%)G3C))#tG)DDCC  "))->>CEDL!,,Iijj/CeK,- r6stepsrLc|j}tj|jj}||jn|}|||z |}tj|||z||zdkz}|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,:dl344%~6FVOf4578Uf_A8M%NOOFUF#  y777Hr6r)kwargsc |jjdd|i|}t|tjr|jnd}||||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.forecasts[./4%.EEUEfEE",Xry"A"AKt$11%????r6Fc |jjd |||d|}||||}|j|z} |j}nl#t t f$rXddl} | d|j j j dtdtj|z}YnwxYwt!||d|j S) 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!0 S'  5;  #;; 3  "%88 1 .MM 34 1 1 1 OOO MMDz+4DDD     FTYY[[0MMM 1! -f    sAA&B*)B*rj)r))NNF) rCrDrErFrrr5propertyintrr>rIrrr]r rerDateLikerboolrPndarrayrrUIndexrrr-ryr:rr;r6r4r=r=s  88 /8 8888&    X SXXsX"c"""X"44444lA!Ah AtX~& A  AAAAH=A!)"(!3 ry"*$ %B@@@(,S#X@ rz29$ %@@@@:%)"&). @ @ !@ 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@@@@@@@@'''''''''',,,,,,::::::::DDDDDDDDDD======NNNNNNNN99999999CCCCCC c2; bmC DYs{  I       I E    ,,&Ysw##\<$@AA &&)=v"F"FGGGWGWGWGWGWGWGWGHGWGtp p p p p p p p p p r6