U Kv f]H@sfddlmZmZddlZddlmZmZmZm Z ddl Z ddl Z ddlmZddlmZmZddlmZmZmZddlmZddlmZmZdd lmZmZdd lm Z e e!e"eje j#e j$fZ%eej&Z'e'(d ed d dge'(d edddge')d d ddddddddddddgZ*eej+j&Z'e')ddgZ,eee*dd Gd!d"d"Z-Gd#d$d$Z.dS)%) Substitution is_int_indexN)AnyDictOptionalUnion) PandasData) SimpleTableSummary) Docstring Parameterindent)PredictionResults) get_index_locget_prediction_index)STLDecomposeResult)_check_dynamicendogmodelZModelzQThe 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.periodseasonaltrendlow_pass seasonal_deg trend_deg low_pass_degrobust seasonal_jump trend_jump low_pass_jump inner_iter outer_iterz )Zstl_forecast_paramsc @sVeZdZdZddddddddddddd ddZeeed d dddd d 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) rrrrrrrrrrr r!c  CsT||_t|||||| | | | | |d |_||_|dkr8in||_t|dsPtddS)N) rrrrrrrrrr r!fitz$model must expose a ``fit`` method.)_endogdict _stl_kwargs_model _model_kwargshasattrAttributeError)selfrrrrrrrrrrrrr r!r0C/tmp/pip-unpacked-wheel-2v6byqio/statsmodels/tsa/forecasting/stl.py__init__s$  zSTLForecast.__init__z )Z fit_params)r"r# fit_kwargsc Csz|dkr in|}t|jf|j}|j||d}|j|j}|j|f|j}|jf|}t|dsht dt |||||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'rZresidr+r,r-r.STLForecastResults) r/r"r#r3stlZstl_fitZ model_endogmodresr0r0r1r's   zSTLForecast.fit) __name__ __module__ __qualname____doc__r2rr _fit_paramsr'r0r0r0r1r$As Z %r$c@s,eZdZdZeeddddZeedddZ eedd d Z eedd d Z ee dd dZ ee dddZedddZeeeeeeefejdddZd!eeejeejejfdddZd"eeee feejejfdddZd#eeeeeeefeee fddd ZdS)$r5a 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``. N)r6resultreturncCs||_||_||_||_t||_|jjd|_t |dt |j|_ t |j t jt jfst|j szt |j |_ Wn"tk rt |j|_ YnXdS)Nrindex)_stl_resultr+ _model_resultnpasarrayr(shape_nobsgetattrpdZ RangeIndex_index isinstanceZ DatetimeIndexZ PeriodIndexrZ to_datetime ValueError)r/r6r>r model_resultrr0r0r1r2s zSTLForecastResults.__init__)r?cCs|jjS)z$The period of the seasonal component)rArr/r0r0r1rszSTLForecastResults.periodcCs|jS)z2The STL instance used to decompose the time series)rArNr0r0r1r6szSTLForecastResults.stlcCs|jS)z&The result of applying STL to the data)rBrNr0r0r1r> szSTLForecastResults.resultcCs|jS)z3The model fit to the additively deseasonalized data)r+rNr0r0r1rszSTLForecastResults.modelcCs|jS)z)The result class from the estimated model)rCrNr0r0r1rMszSTLForecastResults.model_resultc s2t|jdstd|j}t|ts0tdd|jdj|jd_|j j }d}g}g}g}g}|D] }| dd}|d kr|d 7}t fd d |D} |d 7}|d} t|d} | r|| || gqh|d| || gqht|t|dd} | t||d|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_ )ZTrendzLow Passz Lengthc3s|]}|VqdS)N) startswith).0valkeyr0r1 =sz-STLForecastResults.summary..:z<23sz>13sz zSTL Configuration)stubstitle)rY)r-rCr.rOrKr TypeErrorZtablesrZrAconfig capitalizereplaceanystrappendr tupleZ extend_right) r/rOr\Z left_keysZ left_dataZ left_stubsZ right_dataZ right_stubsnewZis_leftZstubrTtabr0rUr1rOsN       zSTLForecastResults.summary)startenddynamicr?cCsDtt|j|jd}|dkr"d}t|||j|j|d\}}}}t|tt j tj frpt ||j\}}}||}n|dkr~d}n |dkrd}|j}t ||||\}}|dkr|dn|} t|jj} | || } td} |dk r||d|} |j| d|d } n,|r2||d} t||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. r@Nr)dataTFr&)r)offset)rrISeriesr(rJrrGrKr`dtdatetime TimestamprrrDrErBrempty_seasonal_forecastmaxZr_)r/rerfrgriZ out_of_sampleZprediction_indexrPZnobsZ in_sample_endrZ predictionsZoosnumZ oos_startr0r0r1_get_seasonal_predictionNs@$      z+STLForecastResults._get_seasonal_prediction)stepsr@r?cCsx|j}t|jj}|dkr"|jn|}||||}t|||||dk}|d|}|dk rttj||d}|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. Nrrh) rrDrErBrrGZtilerIrk)r/rtr@rjrrr0r0r1rps z%STLForecastResults._seasonal_forecastr&)rtkwargsr?cKs<|jjfd|i|}t|tjr(|jnd}||||S)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 rtN)rCr4rKrIrkr@rp)r/rtrur4r@r0r0r1r4szSTLForecastResults.forecastF)rerfrgruc Ks|jjf|||d|}||||}|j|}z |j}WnLttfk rddl} | jd|j j j dt ddt j|}YnXt||d|jd 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. )rerfrgrNz>The variance of the predicted mean is not available using the z model class.) stacklevelZnorm)dist row_labels)rCget_predictionrsZpredicted_mean var_pred_meanr.NotImplementedErrorwarningswarnr __class__r9 UserWarningrDnancopyrry) r/rerfrgrupredZseasonal_predictionZmeanr{r}r0r0r1rzs:*  z!STLForecastResults.get_prediction)N)r&)NNF) r9r:r;r<rrr2propertyintrr6r>rrrMr rOrDateLikerboolrDZndarrayrsrIZIndexrkrprr`r4rzr0r0r0r1r5sT 8  D !    r5)/Zstatsmodels.compat.pandasrrrmrltypingrrrrZnumpyrDZpandasrIZstatsmodels.base.datarZstatsmodels.iolib.summaryr r Zstatsmodels.tools.docstringr r r Zstatsmodels.tsa.base.predictionrZstatsmodels.tsa.base.tsa_modelrrZstatsmodels.tsa.seasonalrrZ(statsmodels.tsa.statespace.kalman_filterrrr`rnZ datetime64rr<ZdsZinsert_parametersZextract_parametersZ_stl_forecast_paramsr'r=r$r5r0r0r0r1sl