M/Ph\ZdZddlmZddlZddlZddlZddlZ ddl m Z m Z m Z ddlmZddlmZddlmcmZddlmZddlmZdd lmZdd lmZdd lmZdd l m!Z!m"Z"m#Z#m$Z$ddl%m&cmcm'Z(dd l)mZddl*m&cm+cm,Z-ddl.m/Z/m0Z0ddl1m2Z2Gddej3Z4Gddej5Z6Gddej7Z8ej9e8e6GddZ:Gddej7Z;ej9e;e:dS)a ETS models for time series analysis. The ETS models are a family of time series models. They can be seen as a generalization of simple exponential smoothing to time series that contain trends and seasonalities. Additionally, they have an underlying state space model. An ETS model is specified by an error type (E; additive or multiplicative), a trend type (T; additive or multiplicative, both damped or undamped, or none), and a seasonality type (S; additive or multiplicative or none). The following gives a very short summary, a more thorough introduction can be found in [1]_. Denote with :math:`\circ_b` the trend operation (addition or multiplication), with :math:`\circ_d` the operation linking trend and dampening factor :math:`\phi` (multiplication if trend is additive, power if trend is multiplicative), and with :math:`\circ_s` the seasonality operation (addition or multiplication). Furthermore, let :math:`\ominus` be the respective inverse operation (subtraction or division). With this, it is possible to formulate the ETS models as a forecast equation and 3 smoothing equations. The former is used to forecast observations, the latter are used to update the internal state. .. math:: \hat{y}_{t|t-1} &= (l_{t-1} \circ_b (b_{t-1}\circ_d \phi))\circ_s s_{t-m}\\ l_{t} &= \alpha (y_{t} \ominus_s s_{t-m}) + (1 - \alpha) (l_{t-1} \circ_b (b_{t-1} \circ_d \phi))\\ b_{t} &= \beta/\alpha (l_{t} \ominus_b l_{t-1}) + (1 - \beta/\alpha) b_{t-1}\\ s_{t} &= \gamma (y_t \ominus_s (l_{t-1} \circ_b (b_{t-1}\circ_d\phi)) + (1 - \gamma) s_{t-m} The notation here follows [1]_; :math:`l_t` denotes the level at time :math:`t`, `b_t` the trend, and `s_t` the seasonal component. :math:`m` is the number of seasonal periods, and :math:`\phi` a trend damping factor. The parameters :math:`\alpha, \beta, \gamma` are the smoothing parameters, which are called ``smoothing_level``, ``smoothing_trend``, and ``smoothing_seasonal``, respectively. Note that the formulation above as forecast and smoothing equation does not distinguish different error models -- it is the same for additive and multiplicative errors. But the different error models lead to different likelihood models, and therefore will lead to different fit results. The error models specify how the true values :math:`y_t` are updated. In the additive error model, .. math:: y_t = \hat{y}_{t|t-1} + e_t, in the multiplicative error model, .. math:: y_t = \hat{y}_{t|t-1}\cdot (1 + e_t). Using these error models, it is possible to formulate state space equations for the ETS models: .. math:: y_t &= Y_t + \eta \cdot e_t\\ l_t &= L_t + \alpha \cdot (M_e \cdot L_t + \kappa_l) \cdot e_t\\ b_t &= B_t + \beta \cdot (M_e \cdot B_t + \kappa_b) \cdot e_t\\ s_t &= S_t + \gamma \cdot (M_e \cdot S_t+\kappa_s)\cdot e_t\\ with .. math:: B_t &= b_{t-1} \circ_d \phi\\ L_t &= l_{t-1} \circ_b B_t\\ S_t &= s_{t-m}\\ Y_t &= L_t \circ_s S_t, and .. math:: \eta &= \begin{cases} Y_t\quad\text{if error is multiplicative}\\ 1\quad\text{else} \end{cases}\\ M_e &= \begin{cases} 1\quad\text{if error is multiplicative}\\ 0\quad\text{else} \end{cases}\\ and, when using the additive error model, .. math:: \kappa_l &= \begin{cases} \frac{1}{S_t}\quad \text{if seasonality is multiplicative}\\ 1\quad\text{else} \end{cases}\\ \kappa_b &= \begin{cases} \frac{\kappa_l}{l_{t-1}}\quad \text{if trend is multiplicative}\\ \kappa_l\quad\text{else} \end{cases}\\ \kappa_s &= \begin{cases} \frac{1}{L_t}\quad\text{if seasonality is multiplicative}\\ 1\quad\text{else} \end{cases} When using the multiplicative error model .. math:: \kappa_l &= \begin{cases} 0\quad \text{if seasonality is multiplicative}\\ S_t\quad\text{else} \end{cases}\\ \kappa_b &= \begin{cases} \frac{\kappa_l}{l_{t-1}}\quad \text{if trend is multiplicative}\\ \kappa_l + l_{t-1}\quad\text{else} \end{cases}\\ \kappa_s &= \begin{cases} 0\quad\text{if seasonality is multiplicative}\\ L_t\quad\text{else} \end{cases} When fitting an ETS model, the parameters :math:`\alpha, \beta`, \gamma, \phi` and the initial states `l_{-1}, b_{-1}, s_{-1}, \ldots, s_{-m}` are selected as maximizers of log likelihood. References ---------- .. [1] Hyndman, R.J., & Athanasopoulos, G. (2019) *Forecasting: principles and practice*, 3rd edition, OTexts: Melbourne, Australia. OTexts.com/fpp3. Accessed on April 19th 2020. ) OrderedDictN)norm rv_continuous rv_discrete) rv_frozen) descriptionsforg) SimpleTable) fmt_params)cache_readonly)Bunch) array_like bool_likeint_like string_like)base)_initialization_simple_initialization_heuristic)freq_to_periodceZdZdZ d0fd Z d1dZd Zed Ze d Z e d Z e d Z e dZ e dZe dZe dZe dZe dZe dZe dZe dZe dZe dZe dZdZdZe dZdZdZe dZe d Zd!Z d"Z! d2fd% Z" d3d&Z#e$j%d'Z&d(Z'd4d)Z(d*Z)d5d+Z*e d,Z+ d6d-Z, d6d.Z-d/Z.xZ/S)7ETSModela> ETS models. Parameters ---------- endog : array_like The observed time-series process :math:`y` error : str, optional The error model. "add" (default) or "mul". trend : str or None, optional The trend component model. "add", "mul", or None (default). damped_trend : bool, optional Whether or not an included trend component is damped. Default is False. seasonal : str, optional The seasonality model. "add", "mul", or None (default). seasonal_periods : int, optional The number of periods in a complete seasonal cycle for seasonal (Holt-Winters) models. For example, 4 for quarterly data with an annual cycle or 7 for daily data with a weekly cycle. Required if `seasonal` is not None. initialization_method : str, optional Method for initialization of the state space model. One of: * 'estimated' (default) * 'heuristic' * 'known' If 'known' initialization is used, then `initial_level` must be passed, as well as `initial_trend` and `initial_seasonal` if applicable. 'heuristic' uses a heuristic based on the data to estimate initial level, trend, and seasonal state. 'estimated' uses the same heuristic as initial guesses, but then estimates the initial states as part of the fitting process. Default is 'estimated'. initial_level : float, optional The initial level component. Only used if initialization is 'known'. initial_trend : float, optional The initial trend component. Only used if initialization is 'known'. initial_seasonal : array_like, optional The initial seasonal component. An array of length `seasonal_periods`. Only used if initialization is 'known'. bounds : dict or None, optional A dictionary with parameter names as keys and the respective bounds intervals as values (lists/tuples/arrays). The available parameter names are, depending on the model and initialization method: * "smoothing_level" * "smoothing_trend" * "smoothing_seasonal" * "damping_trend" * "initial_level" * "initial_trend" * "initial_seasonal.0", ..., "initial_seasonal." The default option is ``None``, in which case the traditional (nonlinear) bounds as described in [1]_ are used. Notes ----- The ETS models are a family of time series models. They can be seen as a generalization of simple exponential smoothing to time series that contain trends and seasonalities. Additionally, they have an underlying state space model. An ETS model is specified by an error type (E; additive or multiplicative), a trend type (T; additive or multiplicative, both damped or undamped, or none), and a seasonality type (S; additive or multiplicative or none). The following gives a very short summary, a more thorough introduction can be found in [1]_. Denote with :math:`\circ_b` the trend operation (addition or multiplication), with :math:`\circ_d` the operation linking trend and dampening factor :math:`\phi` (multiplication if trend is additive, power if trend is multiplicative), and with :math:`\circ_s` the seasonality operation (addition or multiplication). Furthermore, let :math:`\ominus` be the respective inverse operation (subtraction or division). With this, it is possible to formulate the ETS models as a forecast equation and 3 smoothing equations. The former is used to forecast observations, the latter are used to update the internal state. .. math:: \hat{y}_{t|t-1} &= (l_{t-1} \circ_b (b_{t-1}\circ_d \phi)) \circ_s s_{t-m}\\ l_{t} &= \alpha (y_{t} \ominus_s s_{t-m}) + (1 - \alpha) (l_{t-1} \circ_b (b_{t-1} \circ_d \phi))\\ b_{t} &= \beta/\alpha (l_{t} \ominus_b l_{t-1}) + (1 - \beta/\alpha) b_{t-1}\\ s_{t} &= \gamma (y_t \ominus_s (l_{t-1} \circ_b (b_{t-1}\circ_d\phi)) + (1 - \gamma) s_{t-m} The notation here follows [1]_; :math:`l_t` denotes the level at time :math:`t`, `b_t` the trend, and `s_t` the seasonal component. :math:`m` is the number of seasonal periods, and :math:`\phi` a trend damping factor. The parameters :math:`\alpha, \beta, \gamma` are the smoothing parameters, which are called ``smoothing_level``, ``smoothing_trend``, and ``smoothing_seasonal``, respectively. Note that the formulation above as forecast and smoothing equation does not distinguish different error models -- it is the same for additive and multiplicative errors. But the different error models lead to different likelihood models, and therefore will lead to different fit results. The error models specify how the true values :math:`y_t` are updated. In the additive error model, .. math:: y_t = \hat{y}_{t|t-1} + e_t, in the multiplicative error model, .. math:: y_t = \hat{y}_{t|t-1}\cdot (1 + e_t). Using these error models, it is possible to formulate state space equations for the ETS models: .. math:: y_t &= Y_t + \eta \cdot e_t\\ l_t &= L_t + \alpha \cdot (M_e \cdot L_t + \kappa_l) \cdot e_t\\ b_t &= B_t + \beta \cdot (M_e \cdot B_t + \kappa_b) \cdot e_t\\ s_t &= S_t + \gamma \cdot (M_e \cdot S_t+\kappa_s)\cdot e_t\\ with .. math:: B_t &= b_{t-1} \circ_d \phi\\ L_t &= l_{t-1} \circ_b B_t\\ S_t &= s_{t-m}\\ Y_t &= L_t \circ_s S_t, and .. math:: \eta &= \begin{cases} Y_t\quad\text{if error is multiplicative}\\ 1\quad\text{else} \end{cases}\\ M_e &= \begin{cases} 1\quad\text{if error is multiplicative}\\ 0\quad\text{else} \end{cases}\\ and, when using the additive error model, .. math:: \kappa_l &= \begin{cases} \frac{1}{S_t}\quad \text{if seasonality is multiplicative}\\ 1\quad\text{else} \end{cases}\\ \kappa_b &= \begin{cases} \frac{\kappa_l}{l_{t-1}}\quad \text{if trend is multiplicative}\\ \kappa_l\quad\text{else} \end{cases}\\ \kappa_s &= \begin{cases} \frac{1}{L_t}\quad\text{if seasonality is multiplicative}\\ 1\quad\text{else} \end{cases} When using the multiplicative error model .. math:: \kappa_l &= \begin{cases} 0\quad \text{if seasonality is multiplicative}\\ S_t\quad\text{else} \end{cases}\\ \kappa_b &= \begin{cases} \frac{\kappa_l}{l_{t-1}}\quad \text{if trend is multiplicative}\\ \kappa_l + l_{t-1}\quad\text{else} \end{cases}\\ \kappa_s &= \begin{cases} 0\quad\text{if seasonality is multiplicative}\\ L_t\quad\text{else} \end{cases} When fitting an ETS model, the parameters :math:`\alpha, \beta`, \gamma, \phi` and the initial states `l_{-1}, b_{-1}, s_{-1}, \ldots, s_{-m}` are selected as maximizers of log likelihood. References ---------- .. [1] Hyndman, R.J., & Athanasopoulos, G. (2019) *Forecasting: principles and practice*, 3rd edition, OTexts: Melbourne, Australia. OTexts.com/fpp3. Accessed on April 19th 2020. addNF estimatednonect|d| | |d}t|d|dd|_t|d|d|_|j|jdd|_t |d |_t|d |d|_|j|jdd|_|jdu|_|jdu|_ |j rMt|d d |_ |t|j |_ |j d krtdnd |_ tj|jdkr0|jdks|jdks |jdkrtd|jr|jstd|||| | || |jdks|j8|jdks|jt(j|_dSt(j|_dS|jdks|jt(j|_dSt(j|_dS)N)exogdatesfreqmissing)rmuladditivemultiplicativeerroroptionstrendT)r&optional damped_trendseasonalseasonal_periods)r)z'seasonal_periods must be larger than 1.rr!z^endog must be strictly positive when using multiplicative error, trend or seasonal components.z#Can only dampen the trend componentr)super__init__rr$r(rr*r+ has_trend has_seasonalrr,r _index_freq ValueErrornpanyendogset_initialization_method set_boundssmooth_ets_smooth_add_add_smoothing_func_ets_smooth_add_mul_ets_smooth_mul_add_ets_smooth_mul_mul)selfr6r$r(r*r+r,initialization_method initial_level initial_trendinitial_seasonalboundsrrr r& __class__s i/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/statsmodels/tsa/exponential_smoothing/ets.pyr/zETSModel.__init__s$  Eg    ? AAA"1"E  7Gd     : !BQBDJ%lNCC# j'D     = $ M"1"-DM4/ M5   &$, "4t%%%D ! '(6t7G(H(H%$)) !JKKK*%&D ! 6$*/ " "  J%  zU""}%%F    DT^ DBCC C && !         :  $*"4}%%)>'-'A$$$'-'A$$$}%%)>'-'A$$$'-'A$$$cxt|dd|_|jdkrB|td|jr|td|jr|tdn|jd kr,t |j|j|j|j \}}}n{|jd krp|j d d |j d zzzkr,t|j|j|j|j \}}}n+t |j|j|j|j \}}}|jsd}|jsd}||_ ||_ ||_tt!|jt%j|j|_tt!|jt%j|j|_dS)a Sets a new initialization method for the state space model. Parameters ---------- initialization_method : str, optional Method for initialization of the state space model. One of: * 'estimated' (default) * 'heuristic' * 'known' If 'known' initialization is used, then `initial_level` must be passed, as well as `initial_trend` and `initial_seasonal` if applicable. 'heuristic' uses a heuristic based on the data to estimate initial level, trend, and seasonal state. 'estimated' uses the same heuristic as initial guesses, but then estimates the initial states as part of the fitting process. Default is 'estimated'. initial_level : float, optional The initial level component. Only used if initialization is 'known'. initial_trend : float, optional The initial trend component. Only used if initialization is 'known'. initial_seasonal : array_like, optional The initial seasonal component. An array of length `seasonal_periods`. Only used if initialization is 'known'. r@)rknown heuristicr%rINzW`initial_level` argument must be provided when initialization method is set to "known".zy`initial_trend` argument must be provided for models with a trend component when initialization method is set to "known".z`initial_seasonal` argument must be provided for models with a seasonal component when initialization method is set to "known".rJ)r(r+r,r r)rr@r3r0r1rr6r(r+r,nobsrrArBrCrzip_internal_param_namesr4arange_k_params_internal_internal_params_index param_namesk_params _params_index)r?r@rArBrCs rFr7z"ETSModel.set_initialization_methods3H&1 ! #7& & & "  % 0 0$ E~ -"7 @   %5%= @  '; 6 6 * j!%!6      '; 6 6y2T%:a%? @@@@ +J*!]%)%:  !!$$.J*!]%)%:  !!$~ M  ! ** 0'2 *BId6M,N,N O O' ' #)  ")DM":": ; ;  rGc| i|_dSt|ttfst d|D]=}||jvrt d|dt ||d|dd||<>||_dS) a Set bounds for parameter estimation. Parameters ---------- bounds : dict or None, optional A dictionary with parameter names as keys and the respective bounds intervals as values (lists/tuples/arrays). The available parameter names are in ``self.param_names``. The default option is ``None``, in which case the traditional (nonlinear) bounds as described in [1]_ are used. References ---------- .. [1] Hyndman, R.J., & Athanasopoulos, G. (2019) *Forecasting: principles and practice*, 3rd edition, OTexts: Melbourne, Australia. OTexts.com/fpp3. Accessed on April 19th 2020. Nzbounds must be a dictionaryz Invalid key: z in bounds dictionaryzbounds[])rL)shape)rD isinstancedictrr3rSr)r?rDkeys rFr8zETSModel.set_boundshs& >DKKKft[&9:: @ !>???  d...$BBBB)3K!13!1!1!1s !DKKKrGctj|jd}|jdkrt d|jtjkr!tj|jdt}|dfS)zH Prepare data for use in the state space representation WC) requirementsr-zendog must be 1-dimensional)r^dtypeN)r4require orig_endogndimr3r_doublefloat)datar6s rF prepare_datazETSModel.prepare_datasn  4?>>> :??:;; ; ;") # #Jd%Ed{rGc|jSNrMr?s rFnobs_effectivezETSModel.nobs_effective yrGcdSNr-rjs rFk_endogzETSModel.k_endogsqrGcdd|j|j|jfD}|jr|dddz|dz}|S)Nc\g|])}t|d*S)r)strupper).0ss rF z'ETSModel.short_name..s<   Aq !!   rGrrLd)joinr$r(r+r*)r?names rF short_namezETSModel.short_namesjww  *dj$-@        -!9s?T!W,D rGcdg}|jr|dgz }|jr|dgz }|jr|dgz }|jdkr;|dgz }|jr|dgz }|jr!|dt |jDz }|S) Nsmoothing_levelsmoothing_trendsmoothing_seasonal damping_trendrrArBcg|]}d|Szinitial_seasonal.rorvis rFrxz)ETSModel._param_names..s0   ,++   rG)r0r1r*r@ranger,r?rSs rF _param_nameszETSModel._param_namess() > / -. .K   2 01 1K   - O, ,K  % 4 4 O, ,K~ 100     "4#899    rGc@dg}|jr|dgz }|jr|dgz }|S)Nlevelr(r+)r0r1r?namess rF state_nameszETSModel.state_namess;  >  gY E   " j\ !E rGcvdg}|jr|dgz }|jr!|dt|jDz }|S)NrArBcg|]}d|Srrors rFrxz0ETSModel.initial_state_names..s.,-'A''rG)r0r1rr,rs rFinitial_state_nameszETSModel.initial_state_namessd ! > ' o& &E    16t7L1M1M E rGc gdS)Nr~rrrrorjs rF_smoothing_param_nameszETSModel._smoothing_param_namess    rGcPddg}|dt|jDz }|S)NrArBcg|]}d|Srrors rFrxz:ETSModel._internal_initial_state_names..s.   () # # #   rG)rr,rs rF_internal_initial_state_namesz&ETSModel._internal_initial_state_namessL      -243H-I-I    rGc |j|jzSrh)rrrjs rFrOzETSModel._internal_param_namess*T-OOOrGcZdt|jzt|jzSrn)intr0r1rjs rF _k_stateszETSModel._k_statess'3t~&&&T->)?)???rGcd|jzS)NrLr,rjs rF_k_states_internalzETSModel._k_states_internals4(((rGc:|jt|jzSrh)rrr*rjs rF_k_smoothing_paramszETSModel._k_smoothing_paramss~D$5 6 666rGcldt|jzt|j |jzzSrn)rr0r1r,rjs rF_k_initial_stateszETSModel._k_initial_statess< $.!! "4$%%%(== > rGc>|j}|jdkr ||jz }|S)Nr)rr@r)r?ks rFrTzETSModel.k_paramss*  $  % 4 4 ' 'ArGcd|jzS)Nrrjs rFrQzETSModel._k_params_internal st,,,rGcvtj|j|j}t |jD]\}}|j|}||||<|jsd|d<|jdkrO|j |d<|j |d<tj |j r |j |dd<n|j ddd |dd<|S) zu Converts a parameter array passed from outside to the internally used full parameter array. r_r-r'rrN) r4zerosrQr_ enumeraterSrRr*r@rArBisscalarrC)r?paramsinternalrr{ internal_idxs rF_internal_paramszETSModel._internal_params s8D36<HHH !122 / /GAt6t 1$*111a4LOAAAqD !   O4011 O O-3 A %t';;.AE */>a!a%i.H2.N!QU ++rGcdddddS)Ng?g{Gz?\(\?rrorjs rF_default_start_paramszETSModel._default_start_paramsNs ##"&!    rGcg}|jD]+}||jvr ||j|,|jdkrt |}||jgz }|jr ||jgz }|j rl|j }|j dkr"||xx|dzcc<||dz}n!||xx|dz cc<||dz}|| z }tj|S)z Default start params in the format of external parameters. This should not be called directly, but by calling ``self.start_params``. rr!r)rrSappendrr@lenrAr0rBr1rCr+tolistr4array)r?rplvl_idxrCs rF _start_paramszETSModel._start_paramsWs., = =AD$$$ d8;<<<  % 4 4&kkG t)* *F~ /4-.. 4$(#8 =E))7OOO'7';;OOO$(8(<<$$7OOO'7';;OOO$(8(<<$*11333xrGcP||}|jD]}|j|}||jvr||gdz|j|<n)|jr"||jvr|j|gdz|j|<||jvr)tj||dzg|j|R||<|S)z This converts start params to internal params, sets internal-only parameters as bounded, sets bounds for fixed parameters, and then makes sure that all start parameters are within the specified bounds. rLgMbP?) rrOrRrSrD_has_fixed_params _fixed_paramsr4clip)r?rrrrs rF_convert_and_bound_start_paramsz(ETSModel._convert_and_bound_start_paramsvs //77+  A-a0C(((#2#"6!7!!; A' =A1C,C,C"&"4Q"7!81!< ADK')w#C(([^((($ rGctj|jdztj|jdz d\d<d<|jdkrEtj dd<tjdd<|jdkr d\d<d<n d \d<d<|jD].}|j|}||j vr|j |\|<|</fd t|jDS) Ng-C6?)g?rr'rrrr!)r-r-rrc0g|]}||fSroro)rvrlbubs rFrxz*ETSModel._setup_bounds..s%GGG1A1GGGrG) r4rrQonesr@infr+rOrRrDr)r?rrrrs @@rF _setup_boundszETSModel._setup_boundssXd- . . 5 WT, - - 4! 1r!u  % 4 4wBqtHvBqtH}%%!%22!%22+ 2 2A-a0CDK#';q> 3CGGGGGd.E(F(FGGGGrGTc ~||j}ntj|}|jrdt |jdkrLtjt |j}t|dd} nz| |} | } d|j v} | r| dxx| dzcc<d|j v} | r| dxxd| dz zcc<tj |jtj}tj| }g}g|d <t#|jD]s}| |d| |dkrd ||<| |d||<7|| ||d | |ttj|}tj |j}tj |j|jf}d |d <|5t-j|f||||| | fd ||||d d |} dddn #1swxYwYtj| }d}t#|jD]+}||r ||||<| j|||<|dz },| r|dxx|dzcc<| r|dxxd|dz zcc<||}|r|S||}| |_| j|_| j|_|S)a Fit an ETS model by maximizing log-likelihood. Log-likelihood is a function of the model parameters :math:`\alpha, \beta, \gamma, \phi` (depending on the chosen model), and, if `initialization_method` was set to `'estimated'` in the constructor, also the initial states :math:`l_{-1}, b_{-1}, s_{-1}, \ldots, s_{-m}`. The fit is performed using the L-BFGS algorithm. Parameters ---------- start_params : array_like, optional Initial values for parameters that will be optimized. If this is ``None``, default values will be used. The length of this depends on the chosen model. This should contain the parameters in the following order, skipping parameters that do not exist in the chosen model. * `smoothing_level` (:math:`\alpha`) * `smoothing_trend` (:math:`\beta`) * `smoothing_seasonal` (:math:`\gamma`) * `damping_trend` (:math:`\phi`) If ``initialization_method`` was set to ``'estimated'`` (the default), additionally, the parameters * `initial_level` (:math:`l_{-1}`) * `initial_trend` (:math:`l_{-1}`) * `initial_seasonal.0` (:math:`s_{-1}`) * ... * `initial_seasonal.` (:math:`s_{-m}`) also have to be specified. maxiter : int, optional The maximum number of iterations to perform. full_output : bool, optional Set to True to have all available output in the Results object's mle_retvals attribute. The output is dependent on the solver. See LikelihoodModelResults notes section for more information. disp : bool, optional Set to True to print convergence messages. callback : callable callback(xk), optional Called after each iteration, as callback(xk), where xk is the current parameter vector. return_params : bool, optional Whether or not to return only the array of maximizing parameters. Default is False. **kwargs Additional keyword arguments to pass to the optimizer. Returns ------- results : ETSResults Nr)r mle_retvals mle_settingsrr-rrLrrDT approx_gradlbfgs)fargsmethodmaxiter full_outputdispcallback skip_hessian) start_paramsr4asarrayrr_free_params_indexlistrrrrrrDrrQint64 empty_likerrrMruse_internal_logliker.fitrrr9mlefitrr)r?rrrrr return_paramskwargs final_paramsrinternal_start_paramsrD use_beta_staruse_gamma_staris_fixed fixed_valuesparams_without_fixedryhatr fitted_paramsidx_without_fixedresultrEs rFrz ETSModel.fitsD  ,LL:l33L  !I =c$*A&B&Ba&G&G:d4+=+D+D+F+F&G&GHHL#DFF%)$H$H%% !''))F.T[@M E%a(((,A!,DD(((1DN I%a(((A0Ea0H,HH(((x 7rxHHHH=)>??L#% !F8 4233 7 7!9Q<6!9Q<//"&HQK&,QilLOO(//0Ea0HIII8$++F1I6666#%:.B#C#C 8DI&&D8TY(?@AAD$(F= !**,,  $( $%& ## +%!% !               *M*?@@M ! 4233 + +A;+'3AM!$$'-}5F'GM!$%*%% 5a   M!$44    9a   A a(8$88   --m<r)r4 iscomplexobjrr6complexrrQrrr_ascontiguousarrayr; _residualsrMlogpimeanr$abssum) r?rrrrrrrrereslogLs rF_loglike_internalzETSModel._loglike_internalPsoJ ?6 " " :dj888DD:D  x 7rxHHHH8'v|LL+HBHEEEH          oodo.. zA~BE BGC1H4E4E(E!F!F!JK :    41rvd419o/F/F+F#GHDO BF26$<<(( (D rGc#`K|j}|j|_ dV||_dS#||_wxYwrh)logliker)r?external_loglikes rFrzETSModel.use_internal_loglikesE<-  , EEE+DLLL+DL + + + +s$ -c 0|tj|}tj|j|j}tj|j|jf|j}|tj|||S)a Log-likelihood of model. Parameters ---------- params : np.ndarray of np.float Model parameters: (alpha, beta, gamma, phi, l[-1], b[-1], s[-1], ..., s[-m]) Notes ----- The log-likelihood of a exponential smoothing model is [1]_: .. math:: l(\theta, x_0|y) = - \frac{n}{2}(\log(2\pi s^2) + 1) - \sum\limits_{t=1}^n \log(k_t) with .. math:: s^2 = \frac{1}{n}\sum\limits_{t=1}^n \frac{(\hat{y}_t - y_t)^2}{k_t} where :math:`k_t = 1` for the additive error model and :math:`k_t = y_t` for the multiplicative error model. References ---------- .. [1] J. K. Ord, A. B. Koehler R. D. and Snyder (1997). Estimation and Prediction for a Class of Dynamic Nonlinear Statistical Models. *Journal of the American Statistical Association*, 92(440), 1621-1629 r)rr4rrrMr_rr)r?rrrrs rFrzETSModel.loglikesF&&rz&'9'9::x 666x Y/ 0    %%bj&8&8$EEErGcD||j}|jdkr||z |z S||z S)z$Calculates residuals of a predictionNr!)r6r$)r?rres rFrzETSModel._residualss4 <:D :  4K4' '$; rGc||}tj|j}tj|j|jf}tj|jtj}tj|j|j}| ||j ||||| |}|j rm| d|jdz \}}}} tj|| }dg} |jr| dgz } |jr| dgz } tj|| | }||fS) aE Exponential smoothing with given parameters Parameters ---------- params : array_like Model parameters Returns ------- yhat : pd.Series or np.ndarray Predicted values from exponential smoothing. If original data was a ``pd.Series``, returns a ``pd.Series``, else a ``np.ndarray``. xhat : pd.DataFrame or np.ndarray Internal states of exponential smoothing. If original data was a ``pd.Series``, returns a ``pd.DataFrame``, else a ``np.ndarray``. rrr-rrr(r+rcolumns)rr4rrMrrQrrr_r;r6r use_pandas_get_prediction_indexrrr0r1r) r?rrrrrrr_r statenamess rF_smoothzETSModel._smoothsE$//77x ""xD$;<==8D328DDDx 7v|LLL   TZtX|   !!$'' ? K!7749q=IINAq!U9T///D!J~ (wi'   +zl* \&zJJJFV|rGctj|}||}||||S)aB Exponential smoothing with given parameters Parameters ---------- params : array_like Model parameters return_raw : bool, optional Whether to return only the state space results or the full results object. Default is ``False``. Returns ------- result : ETSResultsWrapper or tuple If ``return_raw=False``, returns a ETSResultsWrapper object. Otherwise a tuple of arrays or pandas objects, depending on the format of the endog data. )r4rr _wrap_results)r?r return_rawresultss rFr9zETSModel.smooths<&F##,,v&&!!&':>>>rGc"dttfiS)Nr) ETSResultsETSResultsWrapperrjs rF _res_classeszETSModel._res_classess $5677rGc |dd}|dkr"|r|j|fi|}n |j|fd|i|}ntd|S)a Hessian matrix of the likelihood function, evaluated at the given parameters Parameters ---------- params : array_like Array of parameters at which to evaluate the hessian. approx_centered : bool Whether to use a centered scheme for finite difference approximation approx_complex_step : bool Whether to use complex step differentiation for approximation Returns ------- hessian : ndarray Hessian matrix evaluated at `params` Notes ----- This is a numerical approximation. rapproxapprox_centeredz#Invalid Hessian calculation method.)get_hessian_complex_step_hessian_finite_differenceNotImplementedError)r?rr(approx_complex_steprrhessians rFr.zETSModel.hessians4Hh// X  " 4$4VFFvFF9$9,;?E&&KLL LrGc |dd}|dkr"|r|j|fi|}n |j|fd|i|}ntd|S)Nrr'r(zInvalid score method.)r)_score_complex_step_score_finite_differencer,)r?rr(r-rrscores rFr2zETSModel.score@sHh// X  " 00BB6BB55,;?E&&=>> > rGcdSrhro)rargsrs rFupdatezETSModel.updateQs rG) rNFNNrNNNNNNr)NNN)NrTTNF)NNFFrh)F)FT)0__name__ __module__ __qualname____doc__r/r7r8 staticmethodrfpropertyrkrpr|rrrrrrOrrrrrTrQrrrrrrrrrrr contextlibcontextmanagerrrrrr9r%r.r2r5 __classcell__rEs@rFrrsDFFV) ^B^B^B^B^B^BF k k k k Z ! ! !D  \ XX  X X*XX  X XPPXP@@X@))X)77X7  X X --X-.''X'(  X   X <2$H$H$HP YYYYYY@FFFFP,,,(F(F(FT'''R????.88X8BF&&&&RBF"       rGrceZdZdZfdZedZedZedZedZ dZ dZ dd Z dd Z d ZdZddZ ddZdfd ZxZS)r#zR Results from an error, trend, seasonal (ETS) exponential smoothing model c |\}}||_||_|_t jjdz}t |||gd}|D]!}t|t||"fdj j pgD_ j |} |_ j jr j j} nj } t j|j_| dddf_| d_jjd<jd_j_jrK| dddf_| d_jjd<jd_j_jrv| ddj jf_| d dddd _ j jj jd<jj j_!j!_"j#r| d _$j$_%j&tOj(z } | dz_)t jj*_+t j,j*d _-j*j+z j-z _.t_d si_0d_1i_2d_3d_4d} d_5j&dkr,t jd_6d_5dj0d<dSj7_6tpd9| j0d<dS#tj:j;$rQd_5tOj} t j| | ftj<z_6dj0d<YdSwxYw)NrL)scale) r|r$r(r+r*r0r1r,r@c0g|]}|jvrd|zn|S)z %s (fixed)) fixed_params)rvr{r?s rFrxz'ETSResults.__init__..rs@   $(4+<#<#>AAAqD\ ,Q/ $ 21[^ #z > -1DJ!0!3D $($6D q ! ADI#'9D   1 DJ$>!>?DK$3ABB$7"$=D !%   *,, TZ%?@DJ&*jD #   *&q)DH!%D  D,=(>(>> %) '$*--6$*1555 J (  -) tZ(( DM   )-%$)!( DJ}!!*,(6*:*:' /I m,,,*.*@'/;H/E/L/L /0M00 m,,,y$   DJ4;''H&(h(/C&D&Drv&MD #' M* % % % %  s>" ""j== T[O(1t'<#<==K.qs3K! -i!mQQQ.>?KO rGc|}|j}|jr|j}|jr/|j}|j}t j|dz |z t}|j r|j }|j j } | dkrd|dz|dz zzS| dkr,d|dz |dz||z|zz|dz|zdz d|zdz zzzzS| dkrwd|dz|dz zz||z|zd|z dzz d|zd|z z||zzzz||zd||zz zd|z dzd|dzz zz d|zd|dzz z||zdd|zz||zz zzzz S| dkrd|dz|dz zz||zd|z|zzzS| d krGd|dz |dz||z|zz|dzdz |zd|zdz zzzz||zd|z|z||z|dzzzzzS| d krd|dz|dz zz||zd|z|zzz||z|zd|z dzz d|zd|z z||zzzz||zd||zz zd|z dzd|dzz zz d|zd|dzz z||zdd|zz||zz zzzz d|z|z|zd|z d||zz zz |d||zz z||zd|||zzz zz zzSt) a References ---------- .. [1] Hyndman, R.J., & Athanasopoulos, G. (2019) *Forecasting: principles and practice*, 3rd edition, OTexts: Melbourne, Australia. OTexts.com/fpp3. Accessed on April 19th 2020. r-rANNrLAANrAAdNANAAAAAAdA)r~r0rr1rr,r4rrr*rrNr|r,) r?stepshrQrSrUmrrVrNs rF_relative_forecast_variancez&ETSResults._relative_forecast_variances $ > ('D   3+E%A AEQ;c222A   %$C % E>>uzQU++ + e^^A UT\A-- A 0AQUQY0OO f__1*A&'CZ!^CA~'5yAG,tcz9;CZ1sax<0CA~SAX68E Q\2*AG cQh(>?@ "e^^uzQU++eai1u9u;L.MM M e^^q5QJdlQ&'qyAo)QUQY78!)q5y504!8q1u3EEFG f__1*A&'!)q5y5012#:>G>#u9C(4#:577CZ1sax<0CA~SAX68E Q\2*AG cQh(>?@ X%+CAqL13AqL)C1HCAEN8J,KKM ,& %rGNr-c ||}||}tj||jjf}tjt |tj} tj|} tj ||| | \} } } }}}| | z}d| z | z}|j d}tj tj |||df|}tj||f}tj|j}t#|tjr |j ||fkrt'd|}ns|dkr+tj|j||fd}nB||%tj|||z}nt#|t0r9tj|}||||z}nt#|tjjr||||z}nt'dt#|t4t6fr*||j}|j|d ||fi}n=t#|t<r|||f }nt'd |jd k}|j d k}|j!d k}|rtj"}tj#}ntj$}tj"}|r tj"}n tj$}tK|D]d}|||dz dddf|} |||dz d ddf| }!||dz d|zdz ddf}"||!|"}#|j!dkr,d}$|rd|"z nd}%|r|%||dz d ddfz n|%}&|rd|!z nd}'n6|#}$|rd n|"}%|r|%||dz d ddfz n|%||dz d ddfz}&|rd n|!}'|#|$||ddfzz||ddf<|!| ||!z|%zz||ddfzz||d ddf<| ||| z|&zz||ddfzz||dddf<|"|||"z|'zz||ddfzz||dddf<||dz ddddf||ddddf<f|dkrdtK|D}(nd}(|j&||||zdz |(S)a Random simulations using the state space formulation. Parameters ---------- nsimulations : int The number of simulation steps. anchor : int, str, or datetime, optional First period for simulation. The simulation will be conditional on all existing datapoints prior to the `anchor`. Type depends on the index of the given `endog` in the model. Two special cases are the strings 'start' and 'end'. `start` refers to beginning the simulation at the first period of the sample (i.e. using the initial values as simulation anchor), and `end` refers to beginning the simulation at the first period after the sample. Integer values can run from 0 to `nobs`, or can be negative to apply negative indexing. Finally, if a date/time index was provided to the model, then this argument can be a date string to parse or a datetime type. Default is 'start'. Note: `anchor` corresponds to the observation right before the `start` observation in the `predict` method. repetitions : int, optional Number of simulated paths to generate. Default is 1 simulated path. random_errors : optional Specifies how the random errors should be obtained. Can be one of the following: * ``None``: Random normally distributed values with variance estimated from the fit errors drawn from numpy's standard RNG (can be seeded with the `random_state` argument). This is the default option. * A distribution function from ``scipy.stats``, e.g. ``scipy.stats.norm``: Fits the distribution function to the fit errors and draws from the fitted distribution. Note the difference between ``scipy.stats.norm`` and ``scipy.stats.norm()``, the latter one is a frozen distribution function. * A frozen distribution function from ``scipy.stats``, e.g. ``scipy.stats.norm(scale=2)``: Draws from the frozen distribution function. * A ``np.ndarray`` with shape (`nsimulations`, `repetitions`): Uses the given values as random errors. * ``"bootstrap"``: Samples the random errors from the fit errors. random_state : int or np.random.RandomState, optional A seed for the random number generator or a ``np.random.RandomState`` object. Only used if `random_errors` is ``None``. Default is ``None``. Returns ------- sim : pd.Series, pd.DataFrame or np.ndarray An ``np.ndarray``, ``pd.Series``, or ``pd.DataFrame`` of simulated values. If the original data was a ``pd.Series`` or ``pd.DataFrame``, `sim` will be a ``pd.Series`` if `repetitions` is 1, and a ``pd.DataFrame`` of shape (`nsimulations`, `repetitions`) else. Otherwise, if `repetitions` is 1, a ``np.ndarray`` of shape (`nsimulations`,) is returned, and if `repetitions` is not 1 a ``np.ndarray`` of shape (`nsimulations`, `repetitions`) is returned. rr-zHIf random is an ndarray, it must have shape (nsimulations, repetitions)! bootstrapT)sizereplaceNzWArgument random_state must be None, an integer, or an instance of np.random.RandomStater)rz,Argument random_errors has unexpected value!r!rrLrrr'cg|]}d|zS)z simulation.%dro)rvnums rFrxz'ETSResults.simulate..^sIIIs_s*IIIrG simulation)r)'_get_prediction_start_indexrur4rrNrrr zeros_liker9_initialize_ets_smoothrXtilereshapersqrtrBrYndarrayr3randomchoicerXrandnr RandomStaterrrrvsrr+r(r$multiplypowerrr _wrap_data))r? nsimulationsanchor repetitions random_errors random_statersrxrrrQ beta_star gamma_starrVrrrSrUnstatesysigmaepsrngr mul_seasonal mul_trend mul_errorop_bop_dop_stBLSYetakappa_lkappa_bkappa_srs) rFsimulatezETSResults.simulate:sNj X44V<< 229== HlDJ$AB C C8C --RX>>>}\22   ) !X|       y Uj('!* GBJq<!"<=={ K K HlK0 1 1 ## mRZ 0 0 M"|[&AAA 3 CC k ) ))"" , ! {'C D D M"&&tz22F#-#VN<2MNNCC  y 1 1 M##, )D#EECCKLL L}- J%' J%'   ;D8DD6D;D  ;DD6D|$$ , ,AQq1ua{^S))AQq1ua{^Q''A!a%QAAA%&AQ AzU""#/6!a%%Q6?L'Aa!eQkN22W#/6!a%%Q+2!!!2GaAq!!! n,, 1QUAqqq[>1 ,2!!#AqqqD /)AadGUi!mg&=>QTJJAaAAAgJTY]W%<=AqqqD IIAaAAAgJUi!mg&=>QTJJAaAAAgJAE1R4N+AaQQQhKK ??IIeK6H6HIIIEE Ez$$ y)l2Q6e%   rGc.||dS)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 Returns ------- forecast : ndarray Array of out of sample forecasts. A (steps x k_endog) array. end) _forecast)r?r}s rFforecastzETSResults.forecastes"~~eU+++rGcZ|||tj|dfS)z0 Dynamic prediction/forecasting r-)rr)rr4r)r?r}rs rFrzETSResults._forecastxs4 }} &%0D0D   rGc 8|d}|j|||\}}}}|||zdzkrtdt|tt jtjfr$|j |\}}}||z }n"t|tr |rd}n|dz|z }|dkr d}d}d} |} n3|}t||zdz |}t||z dzd} ||z} | dkrd} n| dz } ||z} | | z dz} ||||| | | | | |f S)Nrr-z2Prediction start cannot lie outside of the sample.start) rNrr3rYrtdtdatetimer Timestamp_get_index_locboolminmax)r?rdynamicrr out_of_sampler start_smooth end_smoothnsmooth start_dynamicanchor_dynamic end_dynamicndynamics rF_handle_prediction_indexz#ETSResults._handle_prediction_indexs =E(,z'G'G 3( ( $sM1 3&* * *D  gR[",? @ @ * J55g>>MGQoGG  & & * *'E/ a<<LJG!MM!LUW_q0#66J*|3a7;;G!GOM A  $NN*Q.NM) .2            rGFc `|||||\ }}}}}}} } } }tj| | z} | dkr|j||dz| d| <| dkr|| || | d<||dzkr||dzz } | | d} |j| || S)aT 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. index : pd.Index, optional Optionally an index to associate the predicted results to. If None, an attempt is made to create an index for the predicted results from the model's index or model's row labels. Returns ------- forecast : array_like or pd.Series. Array of out of in-sample predictions and / or out-of-sample forecasts. An (npredict,) array. If original data was a pd.Series or DataFrame, a pd.Series is returned. rr-N)rr4rrnrrNr)r?rrrrrrrrrrrrndiscards rFpredictzETSResults.predictsb  ) )%#u E E          HWx' ( ( Q;;,\JN-JKAaiL a<<..>BBAghhK 37??a(H()) Az$$Q{;;;rGrc Btt|||||||fi|S)aq Calculates mean prediction and prediction intervals. 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. index : pd.Index, optional Optionally an index to associate the predicted results to. If None, an attempt is made to create an index for the predicted results from the model's index or model's row labels. method : str or None, optional Method to use for calculating prediction intervals. 'exact' (default, if available) or 'simulated'. simulate_repetitions : int, optional Number of simulation repetitions for calculating prediction intervals when ``method='simulated'``. Default is 1000. **simulate_kwargs : Additional arguments passed to the ``simulate`` method. Returns ------- PredictionResults Predicted mean values and prediction intervals )PredictionResultsWrapperPredictionResults)r?rrrrrsimulate_repetitionssimulate_kwargss rFget_predictionzETSResults.get_predictionsHh( $  "     rG皙?c d|jd}t||d|}|jjdkrt j|j jdkr d |jj }d|jjzg}|} fd tt D}t|||t } |jd | |S) a( Summarize the fitted model Parameters ---------- alpha : float, optional Significance level for the confidence intervals. Default is 0.05. start : int, optional Integer of the start observation. Default is 0. Returns ------- summary : Summary instance This holds the summary table and text, which can be printed or converted to various output formats. See Also -------- statsmodels.iolib.summary.Summary zETS()z ETS Results)rQrtitle model_namerr-rzinitialization method: %sc@g|]}t|dgS)r)precr )rvrrs rFrxz&ETSResults.summary..ms:./fQia((()rG)txt_fmtr)r|r.summaryrNr@r4rrPrbrrrr r tablesinsert) r?rQrrrr param_header params_stubs params_datainitial_state_tablerrEs @rFrzETSResults.summaryFs*/DO... ''//! "   : +{ : :Xd011F{QJ2E+dj.NNL!L38V3E3EK#.\<###  N ! !"&9 : : :rG)Nr-NNr-)NNFNNNFNNr)rN)r6r7r8r9r/r rkrnrXrqrurrrrrrrrr>r?s@rFr#r#VshhhhhT^""^"^^ $O&O&O&h i i i i V ,,,,&   < < < |D<D<D<DJJJO}'?:: $   , ,UGS% H H         &oo['.  -3Xg011BF: Q;;/6|/Aa 0DJq3;?+ ,#--j.    ;+ % %K{{1$$$FF)A-Fw . .A&&((#)(<. *A-FF ""$G$ -$8*  Nz+a.",GG N*,)Ka*H*H*H''*,.1*M*M*M'%)%<%@%@a%@%H%HD " " "GHw.//E!||aA.."S%>%>>@@ sQw C!G,hii( gAA%HHH  " " "rGc|jS)z"The variance of the predicted mean)rrjs rF var_pred_meanzPredictionResults.var_pred_mean s %%rGrc|jdkr]tj|jd|dz z d}tj|j|dz d}tj||fj}nat jd|dz z }|tj|j z}tj|j |z |j |zfj}|j r0tj ||j}d|ddd |ddg}||_|S) a Calculates prediction intervals by performing multiple simulations. Parameters ---------- alpha : float, optional The significance level for the prediction interval. Default is 0.05, that is, a 95% prediction interval. rr-rLrrzlower PI (alpha=frzupper PI (alpha=)rr4quantilervstackTrppfrrrrrrrr)r?rQsimulated_upper_pisimulated_lower_pipred_intqhalf_interval_sizers rFr zPredictionResults.pred_int s= ;+ % %!#'UQYQ""" "$'""" y"46H!IJJLHHUQY''A!"RWT-C%D%D!D y'*<<'*<<   ? %|HDODDDH-5-----5----E %H rGrcrtj||}i}|j|d<|jdkrtj|jd|d<|dddf|d<|dddf|d <tj||j t|  }|S) N)rQr rr-rmean_numericalrpi_lowerpi_upperr) r4rr rrr rrrrrkeys)r?r6rQr  to_includer s rF summary_framezPredictionResults.summary_frameE s:dmm%m8899 !0 6 ;+ % %+-7'a,,,J' ("*!!!Q$ :!)!!!Q$ :l dotJOOr1sLL\$#####8888888888//////111111'''''''''******//////888888777777)))))) 0///////////666666BBBBBBBBBBBB433333LA A A A A t&A A A H$` ` ` ` ` *` ` ` F+"'444FFFFFFFFR / / / / /t2 / / /.0ABBBBBrG