----- Code written using below textbook as a reference. Results are checked against the expected outcomes in the text book. Properties: Hyndman, Rob J., and George Athanasopoulos. Forecasting: principles and practice. OTexts, 2014. Author: Terence L van Zyl Modified: Kevin Sheppard from statsmodels.compat.pandas import deprecate_kwarg import contextlib from typing import Any from collections.abc import Hashable , Sequence import warnings import numpy as np import pandas as pd from scipy.optimize import basinhopping , least_squares , minimize from scipy.special import inv_boxcox from scipy.stats import boxcox from statsmodels.tools.validation import ( array_like , bool_like , dict_like , float_like , int_like , string_like , from statsmodels.tsa.base.tsa_model import TimeSeriesModel from statsmodels.tsa.exponential_smoothing.ets import ( _initialization_heuristic , _initialization_simple , from statsmodels.tsa.holtwinters import ( _exponential_smoothers as smoothers , _smoothers as py_smoothers , from statsmodels.tsa.holtwinters._exponential_smoothers import HoltWintersArgs from statsmodels.tsa.holtwinters._smoothers import ( to_restricted , to_unrestricted , from statsmodels.tsa.holtwinters.results import ( HoltWintersResults , HoltWintersResultsWrapper , from statsmodels.tsa.tsatools import freq_to_period SMOOTHERS = { ( "mul" , "add" ): smoothers . holt_win_add_mul_dam , ( "mul" , "mul" ): smoothers . holt_win_mul_mul_dam , ( "mul" , None ): smoothers . holt_win__mul , ( "add" , "add" ): smoothers . holt_win_add_add_dam , ( "add" , "mul" ): smoothers . holt_win_mul_add_dam , ( "add" , None ): smoothers . holt_win__add , ( None , "add" ): smoothers . holt_add_dam , ( None , "mul" ): smoothers . holt_mul_dam , ( None , None ): smoothers . holt__ , PY_SMOOTHERS = { ( "mul" , "add" ): py_smoothers . holt_win_add_mul_dam , ( "mul" , "mul" ): py_smoothers . holt_win_mul_mul_dam , ( "mul" , None ): py_smoothers . holt_win__mul , ( "add" , "add" ): py_smoothers . holt_win_add_add_dam , ( "add" , "mul" ): py_smoothers . holt_win_mul_add_dam , ( "add" , None ): py_smoothers . holt_win__add , ( None , "add" ): py_smoothers . holt_add_dam , ( None , "mul" ): py_smoothers . holt_mul_dam , ( None , None ): py_smoothers . holt__ , def opt_wrapper ( func ): def f ( * args , ** kwargs ): err = func ( * args , ** kwargs ) if isinstance ( err , np . ndarray ): return err . T @ err return err return f class _OptConfig : alpha : float beta : float phi : float gamma : float level : float trend : float seasonal : np . ndarray y : np . ndarray params : np . ndarray mask : np . ndarray mle_retvals : Any def unpack_parameters ( self , params ) -> "_OptConfig" : self . alpha = params [ 0 ] self . beta = params [ 1 ] self . gamma = params [ 2 ] self . level = params [ 3 ] self . trend = params [ 4 ] self . phi = params [ 5 ] self . seasonal = params [ 6 :] return self [docs] class ExponentialSmoothing ( TimeSeriesModel ): Holt Winter's Exponential Smoothing Parameters ---------- endog : array_like The time series to model. trend : {"add", "mul", "additive", "multiplicative", None}, optional Type of trend component. damped_trend : bool, optional Should the trend component be damped. seasonal : {"add", "mul", "additive", "multiplicative", None}, optional Type of seasonal component. seasonal_periods : int, optional The number of periods in a complete seasonal cycle, e.g., 4 for quarterly data or 7 for daily data with a weekly cycle. initialization_method : str, optional Method for initialize the recursions. One of: * None * 'estimated' * 'heuristic' * 'legacy-heuristic' * 'known' None defaults to the pre-0.12 behavior where initial values are passed as part of ``fit``. If any of the other values are passed, then the initial values must also be set when constructing the model. If 'known' initialization is used, then `initial_level` must be passed, as well as `initial_trend` and `initial_seasonal` if applicable. Default is 'estimated'. "legacy-heuristic" uses the same values that were used in statsmodels 0.11 and earlier. initial_level : float, optional The initial level component. Required if estimation method is "known". If set using either "estimated" or "heuristic" this value is used. This allows one or more of the initial values to be set while deferring to the heuristic for others or estimating the unset parameters. initial_trend : float, optional The initial trend component. Required if estimation method is "known". If set using either "estimated" or "heuristic" this value is used. This allows one or more of the initial values to be set while deferring to the heuristic for others or estimating the unset parameters. initial_seasonal : array_like, optional The initial seasonal component. An array of length `seasonal` or length `seasonal - 1` (in which case the last initial value is computed to make the average effect zero). Only used if initialization is 'known'. Required if estimation method is "known". If set using either "estimated" or "heuristic" this value is used. This allows one or more of the initial values to be set while deferring to the heuristic for others or estimating the unset parameters. use_boxcox : {True, False, 'log', float}, optional Should the Box-Cox transform be applied to the data first? If 'log' then apply the log. If float then use the value as lambda. bounds : dict[str, tuple[float, float]], optional An dictionary containing bounds for the parameters in the model, excluding the initial values if estimated. The keys of the dictionary are the variable names, e.g., smoothing_level or initial_slope. The initial seasonal variables are labeled initial_seasonal.<j> for j=0,...,m-1 where m is the number of period in a full season. Use None to indicate a non-binding constraint, e.g., (0, None) constrains a parameter to be non-negative. dates : array_like of datetime, optional An array-like object of datetime objects. If a Pandas object is given for endog, it is assumed to have a DateIndex. freq : str, optional The frequency of the time-series. A Pandas offset or 'B', 'D', 'W', 'M', 'A', or 'Q'. This is optional if dates are given. missing : str Available options are 'none', 'drop', and 'raise'. If 'none', no nan checking is done. If 'drop', any observations with nans are dropped. If 'raise', an error is raised. Default is 'none'. Notes ----- This is a full implementation of the holt winters exponential smoothing as per [1]_. This includes all the unstable methods as well as the stable methods. The implementation of the library covers the functionality of the R library as much as possible whilst still being Pythonic. See the notebook `Exponential Smoothing <../examples/notebooks/generated/exponential_smoothing.html>`__ for an overview. References ---------- .. [1] Hyndman, Rob J., and George Athanasopoulos. Forecasting: principles and practice. OTexts, 2014. @deprecate_kwarg ( "damped" , "damped_trend" ) def __init__ ( self , endog , trend = None , damped_trend = False , seasonal = None , seasonal_periods = None , initialization_method = "estimated" , initial_level = None , initial_trend = None , initial_seasonal = None , use_boxcox = False , bounds = None , dates = None , freq = None , missing = "none" , super () . __init__ ( endog , None , dates , freq , missing = missing ) self . _y = self . _data = array_like ( endog , "endog" , ndim = 1 , contiguous = True , order = "C" options = ( "add" , "mul" , "additive" , "multiplicative" ) trend = string_like ( trend , "trend" , options = options , optional = True ) if trend in [ "additive" , "multiplicative" ]: trend = { "additive" : "add" , "multiplicative" : "mul" }[ trend ] self . trend = trend self . damped_trend = bool_like ( damped_trend , "damped_trend" ) seasonal = string_like ( seasonal , "seasonal" , options = options , optional = True if seasonal in [ "additive" , "multiplicative" ]: seasonal = { "additive" : "add" , "multiplicative" : "mul" }[ seasonal ] self . seasonal = seasonal self . has_trend = trend in [ "mul" , "add" ] self . has_seasonal = seasonal in [ "mul" , "add" ] if ( self . trend == "mul" or self . seasonal == "mul" ) and not np . all ( self . _data > 0.0 raise ValueError ( "endog must be strictly positive when using" "multiplicative trend or seasonal components." if self . damped_trend and not self . has_trend : raise ValueError ( "Can only dampen the trend component" ) if self . has_seasonal : self . seasonal_periods = int_like ( seasonal_periods , "seasonal_periods" , optional = True if seasonal_periods is None : try : self . seasonal_periods = freq_to_period ( self . _index_freq ) except Exception : raise ValueError ( "seasonal_periods has not been provided and index " "does not have a known freq. You must provide " "seasonal_periods" if self . seasonal_periods <= 1 : raise ValueError ( "seasonal_periods must be larger than 1." ) assert self . seasonal_periods is not None else : self . seasonal_periods = 0 self . nobs = len ( self . endog ) options = ( "known" , "estimated" , "heuristic" , "legacy-heuristic" ) self . _initialization_method = string_like ( initialization_method , "initialization_method" , optional = False , options = options , self . _initial_level = float_like ( initial_level , "initial_level" , optional = True self . _initial_trend = float_like ( initial_trend , "initial_trend" , optional = True self . _initial_seasonal = array_like ( initial_seasonal , "initial_seasonal" , optional = True estimated = self . _initialization_method == "estimated" self . _estimate_level = estimated self . _estimate_trend = estimated and self . trend is not None self . _estimate_seasonal = estimated and self . seasonal is not None self . _bounds = self . _check_bounds ( bounds ) self . _use_boxcox = use_boxcox self . _lambda = np . nan self . _y = self . _boxcox () self . _initialize () self . _fixed_parameters = {} def _check_bounds ( self , bounds ): bounds = dict_like ( bounds , "bounds" , optional = True ) if bounds is None : return msg = ( "bounds must be a dictionary of 2-element tuples of the form" " (lb, ub) where lb < ub, lb>=0 and ub<=1" variables = self . _ordered_names () for key in bounds : if key not in variables : supported = ", " . join ( variables [: - 1 ]) supported += ", and " + variables [ - 1 ] raise KeyError ( f " { key } does not match the list of supported variables " f "names: { supported } ." bound = bounds [ key ] if not isinstance ( bound , tuple ): raise TypeError ( msg ) lb = bound [ 0 ] if bound [ 0 ] is not None else - np . inf ub = bound [ 1 ] if bound [ 1 ] is not None else np . inf if len ( bound ) != 2 or lb >= ub : raise ValueError ( msg ) if ( "smoothing" in key or "damp" in key ) and ( bound [ 0 ] < 0.0 or bound [ 1 ] > 1.0 raise ValueError ( f " { key } must have a lower bound >= 0.0 and <= 1.0" return bounds def _boxcox ( self ): if self . _use_boxcox is None or self . _use_boxcox is False : self . _lambda = np . nan return self . _y if self . _use_boxcox is True : y , self . _lambda = boxcox ( self . _y ) elif isinstance ( self . _use_boxcox , ( int , float )): self . _lambda = float ( self . _use_boxcox ) y = boxcox ( self . _y , self . _use_boxcox ) else : raise TypeError ( "use_boxcox must be True, False or a float." ) return y [docs] @contextlib . contextmanager def fix_params ( self , values ): Temporarily fix parameters for estimation. Parameters ---------- values : dict Values to fix. The key is the parameter name and the value is the fixed value. Yields ------ No value returned. Examples -------- >>> from statsmodels.datasets.macrodata import load_pandas >>> data = load_pandas() >>> import statsmodels.tsa.api as tsa >>> mod = tsa.ExponentialSmoothing(data.data.realcons, trend="add", ... initialization_method="estimated") >>> with mod.fix_params({"smoothing_level": 0.2}): ... mod.fit() values = dict_like ( values , "values" ) valid_keys = ( "smoothing_level" ,) if self . has_trend : valid_keys += ( "smoothing_trend" ,) if self . has_seasonal : valid_keys += ( "smoothing_seasonal" ,) m = self . seasonal_periods valid_keys += tuple ([ f "initial_seasonal. { i } " for i in range ( m )]) if self . damped_trend : valid_keys += ( "damping_trend" ,) if self . _initialization_method in ( "estimated" , None ): extra_keys = [ key . replace ( "smoothing_" , "initial_" ) for key in valid_keys if "smoothing_" in key valid_keys += tuple ( extra_keys ) for key in values : if key not in valid_keys : valid = ", " . join ( valid_keys [: - 1 ]) + ", and " + valid_keys [ - 1 ] raise KeyError ( f " { key } if not allowed. Only { valid } are supported in " "this specification." if "smoothing_level" in values : alpha = values [ "smoothing_level" ] if alpha <= 0.0 : raise ValueError ( "smoothing_level must be in (0, 1)" ) beta = values . get ( "smoothing_trend" , 0.0 ) if beta > alpha : raise ValueError ( "smoothing_trend must be <= smoothing_level" ) gamma = values . get ( "smoothing_seasonal" , 0.0 ) if gamma > 1 - alpha : raise ValueError ( "smoothing_seasonal must be <= 1 - smoothing_level" try : self . _fixed_parameters = values yield finally : self . _fixed_parameters = {} def _initialize ( self ): if self . _initialization_method == "known" : return self . _initialize_known () msg = ( f "initialization method is { self . _initialization_method } but " "initial_ {0} has been set." if self . _initial_level is not None : raise ValueError ( msg . format ( "level" )) if self . _initial_trend is not None : raise ValueError ( msg . format ( "trend" )) if self . _initial_seasonal is not None : raise ValueError ( msg . format ( "seasonal" )) if self . _initialization_method == "legacy-heuristic" : return self . _initialize_legacy () elif self . _initialization_method == "heuristic" : return self . _initialize_heuristic () elif self . _initialization_method == "estimated" : if self . nobs < 10 + 2 * ( self . seasonal_periods // 2 ): return self . _initialize_simple () else : return self . _initialize_heuristic () def _initialize_simple ( self ): trend = self . trend if self . has_trend else False seasonal = self . seasonal if self . has_seasonal else False lvl , trend , seas = _initialization_simple ( self . _y , trend , seasonal , self . seasonal_periods self . _initial_level = lvl self . _initial_trend = trend self . _initial_seasonal = seas def _initialize_heuristic ( self ): trend = self . trend if self . has_trend else False seasonal = self . seasonal if self . has_seasonal else False lvl , trend , seas = _initialization_heuristic ( self . _y , trend , seasonal , self . seasonal_periods self . _initial_level = lvl self . _initial_trend = trend self . _initial_seasonal = seas def _initialize_legacy ( self ): lvl , trend , seasonal = self . initial_values ( force = True ) self . _initial_level = lvl self . _initial_trend = trend self . _initial_seasonal = seasonal def _initialize_known ( self ): msg = "initialization is 'known' but initial_ {0} not given" if self . _initial_level is None : raise ValueError ( msg . format ( "level" )) excess = "initial_ {0} set but model has no {0} component" if self . has_trend and self . _initial_trend is None : raise ValueError ( msg . format ( "trend" )) elif not self . has_trend and self . _initial_trend is not None : raise ValueError ( excess . format ( "trend" )) if self . has_seasonal and self . _initial_seasonal is None : raise ValueError ( msg . format ( "seasonal" )) elif not self . has_seasonal and self . _initial_seasonal is not None : raise ValueError ( excess . format ( "seasonal" )) [docs] def predict ( self , params , start = None , end = None ): In-sample and out-of-sample prediction. Parameters ---------- params : ndarray The fitted model parameters. start : int, str, or datetime Zero-indexed observation number at which to start forecasting, ie., the first forecast is start. Can also be a date string to parse or a datetime type. end : int, str, or datetime Zero-indexed observation number at which to end forecasting, ie., the first forecast is start. Can also be a date string to parse or a datetime type. Returns ------- ndarray The predicted values. if start is None : freq = getattr ( self . _index , "freq" , 1 ) if isinstance ( freq , int ): start = self . _index . shape [ 0 ] else : start = self . _index [ - 1 ] + freq start , end , out_of_sample , _ = self . _get_prediction_index ( start = start , end = end if out_of_sample > 0 : res = self . _predict ( h = out_of_sample , ** params ) else : res = self . _predict ( h = 0 , ** params ) return res . fittedfcast [ start : end + out_of_sample + 1 ] def _enforce_bounds ( self , p , sel , lb , ub ): initial_p = p [ sel ] # Ensure strictly inbounds loc = initial_p <= lb upper = ub [ loc ] . copy () upper [ ~ np . isfinite ( upper )] = 100.0 eps = 1e-4 initial_p [ loc ] = lb [ loc ] + eps * ( upper - lb [ loc ]) loc = initial_p >= ub lower = lb [ loc ] . copy () lower [ ~ np . isfinite ( lower )] = - 100.0 eps = 1e-4 initial_p [ loc ] = ub [ loc ] - eps * ( ub [ loc ] - lower ) return initial_p @staticmethod def _check_blocked_keywords ( d : dict , keys : Sequence [ Hashable ], name = "kwargs" for key in keys : if key in d : raise ValueError ( f " { name } must not contain ' { key } '" ) def _check_bound_feasibility ( self , bounds ): if bounds [ 1 ][ 0 ] > bounds [ 0 ][ 1 ]: raise ValueError ( "The bounds for smoothing_trend and smoothing_level are " "incompatible since smoothing_trend <= smoothing_level." if bounds [ 2 ][ 0 ] > ( 1 - bounds [ 0 ][ 1 ]): raise ValueError ( "The bounds for smoothing_seasonal and smoothing_level " "are incompatible since smoothing_seasonal <= " "1 - smoothing_level." @staticmethod def _setup_brute ( sel , bounds , alpha ): # More points when fewer parameters ns = 87 // sel [: 3 ] . sum () if not sel [ 0 ]: # Easy case since no cross-constraints nparams = int ( sel [ 1 ]) + int ( sel [ 2 ]) args = [] for i in range ( 1 , 3 ): if sel [ i ]: bound = bounds [ i ] step = bound [ 1 ] - bound [ 0 ] lb = bound [ 0 ] + 0.005 * step if i == 1 : ub = min ( bound [ 1 ], alpha ) - 0.005 * step else : ub = min ( bound [ 1 ], 1 - alpha ) - 0.005 * step args . append ( np . linspace ( lb , ub , ns )) points = np . stack ( np . meshgrid ( * args )) points = points . reshape (( nparams , - 1 )) . T return np . ascontiguousarray ( points ) bound = bounds [ 0 ] step = 0.005 * ( bound [ 1 ] - bound [ 0 ]) points = np . linspace ( bound [ 0 ] + step , bound [ 1 ] - step , ns ) if not sel [ 1 ] and not sel [ 2 ]: return points [:, None ] combined = [] b_bounds = bounds [ 1 ] g_bounds = bounds [ 2 ] if sel [ 1 ] and sel [ 2 ]: for a in points : b_lb = b_bounds [ 0 ] b_ub = min ( b_bounds [ 1 ], a ) g_lb = g_bounds [ 0 ] g_ub = min ( g_bounds [ 1 ], 1 - a ) if b_lb > b_ub or g_lb > g_ub : # infeasible point continue nb = int ( np . ceil ( ns * np . sqrt ( a ))) ng = int ( np . ceil ( ns * np . sqrt ( 1 - a ))) b = np . linspace ( b_lb , b_ub , nb ) g = np . linspace ( g_lb , g_ub , ng ) both = np . stack ( np . meshgrid ( b , g )) . reshape ( 2 , - 1 ) . T final = np . empty (( both . shape [ 0 ], 3 )) final [:, 0 ] = a final [:, 1 :] = both combined . append ( final ) elif sel [ 1 ]: for a in points : b_lb = b_bounds [ 0 ] b_ub = min ( b_bounds [ 1 ], a ) if b_lb > b_ub : # infeasible point continue nb = int ( np . ceil ( ns * np . sqrt ( a ))) final = np . empty (( nb , 2 )) final [:, 0 ] = a final [:, 1 ] = np . linspace ( b_lb , b_ub , nb ) combined . append ( final ) else : # sel[2] for a in points : g_lb = g_bounds [ 0 ] g_ub = min ( g_bounds [ 1 ], 1 - a ) if g_lb > g_ub : # infeasible point continue ng = int ( np . ceil ( ns * np . sqrt ( 1 - a ))) final = np . empty (( ng , 2 )) final [:, 1 ] = np . linspace ( g_lb , g_ub , ng ) final [:, 0 ] = a combined . append ( final ) return np . vstack ( combined ) def _ordered_names ( self ): names = ( "smoothing_level" , "smoothing_trend" , "smoothing_seasonal" , "initial_level" , "initial_trend" , "damping_trend" , m = self . seasonal_periods names += tuple ([ f "initial_seasonal. { i } " for i in range ( m )]) return names def _update_for_fixed ( self , sel , alpha , beta , gamma , phi , l0 , b0 , s0 ): if self . _fixed_parameters : fixed = self . _fixed_parameters names = self . _ordered_names () not_fixed = np . array ([ name not in fixed for name in names ]) if ( ~ sel [ ~ not_fixed ]) . any (): invalid = [] for name , s , nf in zip ( names , sel , not_fixed ): if not s and not nf : invalid . append ( name ) invalid_names = ", " . join ( invalid ) raise ValueError ( "Cannot fix a parameter that is not being " f "estimated: { invalid_names } " sel &= not_fixed alpha = fixed . get ( "smoothing_level" , alpha ) beta = fixed . get ( "smoothing_trend" , beta ) gamma = fixed . get ( "smoothing_seasonal" , gamma ) phi = fixed . get ( "damping_trend" , phi ) l0 = fixed . get ( "initial_level" , l0 ) b0 = fixed . get ( "initial_trend" , b0 ) for i in range ( self . seasonal_periods ): s0 [ i ] = fixed . get ( f "initial_seasonal. { i } " , s0 [ i ]) return sel , alpha , beta , gamma , phi , l0 , b0 , s0 def _construct_bounds ( self ): trend_lb = 0.0 if self . trend == "mul" else None season_lb = 0.0 if self . seasonal == "mul" else None lvl_lb = None if trend_lb is None and season_lb is None else 0.0 bounds = [ ( 0.0 , 1.0 ), # alpha ( 0.0 , 1.0 ), # beta ( 0.0 , 1.0 ), # gamma ( lvl_lb , None ), # level ( trend_lb , None ), # trend ( 0.8 , 0.995 ), # phi bounds += [( season_lb , None )] * self . seasonal_periods if self . _bounds is not None : assert isinstance ( self . _bounds , dict ) for i , name in enumerate ( self . _ordered_names ()): bounds [ i ] = self . _bounds . get ( name , bounds [ i ]) # Update bounds to account for fixed parameters fixed = self . _fixed_parameters if "smoothing_level" in fixed : # Update bounds if fixed alpha alpha = fixed [ "smoothing_level" ] # beta <= alpha if bounds [ 1 ][ 1 ] > alpha : bounds [ 1 ] = ( bounds [ 1 ][ 0 ], alpha ) # gamma <= 1 - alpha if bounds [ 2 ][ 1 ] > ( 1 - alpha ): bounds [ 2 ] = ( bounds [ 2 ][ 0 ], 1 - alpha ) # gamma <= 1 - alpha if "smoothing_trend" in fixed : # beta <= alpha beta = fixed [ "smoothing_trend" ] bounds [ 0 ] = ( max ( beta , bounds [ 0 ][ 0 ]), bounds [ 0 ][ 1 ]) if "smoothing_seasonal" in fixed : gamma = fixed [ "smoothing_seasonal" ] # gamma <= 1 - alpha => alpha <= 1 - gamma bounds [ 0 ] = ( bounds [ 0 ][ 0 ], min ( 1 - gamma , bounds [ 0 ][ 1 ])) # Ensure bounds are feasible for i , name in enumerate ( self . _ordered_names ()): lb = bounds [ i ][ 0 ] if bounds [ i ][ 0 ] is not None else - np . inf ub = bounds [ i ][ 1 ] if bounds [ i ][ 1 ] is not None else np . inf if lb >= ub : raise ValueError ( "After adjusting for user-provided bounds fixed values, " f "the resulting set of bounds for { name } , { bounds [ i ] } , " "are infeasible." self . _check_bound_feasibility ( bounds ) return bounds def _get_starting_values ( self , params , start_params , use_brute , sel , hw_args , bounds , alpha , func , if start_params is None and use_brute and np . any ( sel [: 3 ]): # Have a quick look in the region for a good starting place for # alpha, beta & gamma using fixed values for initial m = self . seasonal_periods sv_sel = np . array ([ False ] * ( 6 + m )) sv_sel [: 3 ] = True sv_sel &= sel hw_args . xi = sv_sel . astype ( int ) hw_args . transform = False # Setup the grid points, respecting constraints points = self . _setup_brute ( sv_sel , bounds , alpha ) opt = opt_wrapper ( func ) best_val = np . inf best_params = points [ 0 ] for point in points : val = opt ( point , hw_args ) if val < best_val : best_params = point best_val = val params [ sv_sel ] = best_params elif start_params is not None : if len ( start_params ) != sel . sum (): msg = "start_params must have {0} values but has {1} ." nxi , nsp = len ( sel ), len ( start_params ) raise ValueError ( msg . format ( nxi , nsp )) params [ sel ] = start_params return params def _optimize_parameters ( self , data : _OptConfig , use_brute , method , kwargs ) -> _OptConfig : # Prepare starting values alpha = data . alpha beta = data . beta phi = data . phi gamma = data . gamma y = data . y start_params = data . params has_seasonal = self . has_seasonal has_trend = self . has_trend trend = self . trend seasonal = self . seasonal damped_trend = self . damped_trend m = self . seasonal_periods params = np . zeros ( 6 + m ) l0 , b0 , s0 = self . initial_values ( initial_level = data . level , initial_trend = data . trend init_alpha = alpha if alpha is not None else 0.5 / max ( m , 1 ) init_beta = beta if beta is None and has_trend : init_beta = 0.1 * init_alpha init_gamma = gamma if has_seasonal and gamma is None : init_gamma = 0.05 * ( 1 - init_alpha ) init_phi = phi if phi is not None else 0.99 # Selection of parameters to optimize sel = np . array ( alpha is None , has_trend and beta is None , has_seasonal and gamma is None , self . _estimate_level , self . _estimate_trend , damped_trend and phi is None , + [ has_seasonal and self . _estimate_seasonal ] * m , sel , init_alpha , init_beta , init_gamma , init_phi , ) = self . _update_for_fixed ( sel , init_alpha , init_beta , init_gamma , init_phi , l0 , b0 , s0 func = SMOOTHERS [( seasonal , trend )] params [: 6 ] = [ init_alpha , init_beta , init_gamma , l0 , b0 , init_phi ] if m : params [ - m :] = s0 if not np . any ( sel ): from statsmodels.tools.sm_exceptions import EstimationWarning message = ( "Model has no free parameters to estimate. Set " "optimized=False to suppress this warning" warnings . warn ( message , EstimationWarning , stacklevel = 3 ) data = data . unpack_parameters ( params ) data . params = params data . mask = sel return data orig_bounds = self . _construct_bounds () bounds = np . array ( orig_bounds [: 3 ], dtype = float ) hw_args = HoltWintersArgs ( sel . astype ( int ), params , bounds , y , m , self . nobs params = self . _get_starting_values ( params , start_params , use_brute , sel , hw_args , bounds , init_alpha , func , # We always use [0, 1] for a, b and g and handle transform inside mod_bounds = [( 0 , 1 )] * 3 + orig_bounds [ 3 :] relevant_bounds = [ bnd for bnd , flag in zip ( mod_bounds , sel ) if flag ] bounds = np . array ( relevant_bounds , dtype = float ) lb , ub = bounds . T lb [ np . isnan ( lb )] = - np . inf ub [ np . isnan ( ub )] = np . inf hw_args . xi = sel . astype ( int ) # Ensure strictly inbounds initial_p = self . _enforce_bounds ( params , sel , lb , ub ) # Transform to unrestricted space params [ sel ] = initial_p params [: 3 ] = to_unrestricted ( params , sel , hw_args . bounds ) initial_p = params [ sel ] # Ensure parameters are transformed internally hw_args . transform = True if method in ( "least_squares" , "ls" ): # Least squares uses a different format for bounds ls_bounds = lb , ub self . _check_blocked_keywords ( kwargs , ( "args" , "bounds" )) res = least_squares ( func , initial_p , bounds = ls_bounds , args = ( hw_args ,), ** kwargs success = res . success elif method in ( "basinhopping" , "bh" ): # Take a deeper look in the local minimum we are in to find the # best solution to parameters, maybe hop around to try escape the # local minimum we may be in. minimizer_kwargs = { "args" : ( hw_args ,), "bounds" : relevant_bounds } kwargs = kwargs . copy () if "minimizer_kwargs" in kwargs : self . _check_blocked_keywords ( kwargs [ "minimizer_kwargs" ], ( "args" , "bounds" ), name = "kwargs['minimizer_kwargs']" , minimizer_kwargs . update ( kwargs [ "minimizer_kwargs" ]) del kwargs [ "minimizer_kwargs" ] default_kwargs = { "minimizer_kwargs" : minimizer_kwargs , "stepsize" : 0.01 , default_kwargs . update ( kwargs ) obj = opt_wrapper ( func ) res = basinhopping ( obj , initial_p , ** default_kwargs ) success = res . lowest_optimization_result . success else : obj = opt_wrapper ( func ) self . _check_blocked_keywords ( kwargs , ( "args" , "bounds" , "method" )) res = minimize ( obj , initial_p , args = ( hw_args ,), bounds = relevant_bounds , method = method , ** kwargs , success = res . success # finally transform to restricted space params [ sel ] = res . x params [: 3 ] = to_restricted ( params , sel , hw_args . bounds ) res . x = params [ sel ] if not success : from statsmodels.tools.sm_exceptions import ConvergenceWarning warnings . warn ( "Optimization failed to converge. Check mle_retvals." , ConvergenceWarning , params [ sel ] = res . x data . unpack_parameters ( params ) data . params = params data . mask = sel data . mle_retvals = res return data [docs] @deprecate_kwarg ( "smoothing_slope" , "smoothing_trend" ) @deprecate_kwarg ( "initial_slope" , "initial_trend" ) @deprecate_kwarg ( "damping_slope" , "damping_trend" ) def fit ( self , smoothing_level = None , smoothing_trend = None , smoothing_seasonal = None , damping_trend = None , optimized = True , remove_bias = False , start_params = None , method = None , minimize_kwargs = None , use_brute = True , use_boxcox = None , use_basinhopping = None , initial_level = None , initial_trend = None , Fit the model Parameters ---------- smoothing_level : float, optional The alpha value of the simple exponential smoothing, if the value is set then this value will be used as the value. smoothing_trend : float, optional The beta value of the Holt's trend method, if the value is set then this value will be used as the value. smoothing_seasonal : float, optional The gamma value of the holt winters seasonal method, if the value is set then this value will be used as the value. damping_trend : float, optional The phi value of the damped method, if the value is set then this value will be used as the value. optimized : bool, optional Estimate model parameters by maximizing the log-likelihood. remove_bias : bool, optional Remove bias from forecast values and fitted values by enforcing that the average residual is equal to zero. start_params : array_like, optional Starting values to used when optimizing the fit. If not provided, starting values are determined using a combination of grid search and reasonable values based on the initial values of the data. See the notes for the structure of the model parameters. method : str, default "L-BFGS-B" The minimizer used. Valid options are "L-BFGS-B" , "TNC", "SLSQP" (default), "Powell", "trust-constr", "basinhopping" (also "bh") and "least_squares" (also "ls"). basinhopping tries multiple starting values in an attempt to find a global minimizer in non-convex problems, and so is slower than the others. minimize_kwargs : dict[str, Any] A dictionary of keyword arguments passed to SciPy's minimize function if method is one of "L-BFGS-B", "TNC", "SLSQP", "Powell", or "trust-constr", or SciPy's basinhopping or least_squares functions. The valid keywords are optimizer specific. Consult SciPy's documentation for the full set of options. use_brute : bool, optional Search for good starting values using a brute force (grid) optimizer. If False, a naive set of starting values is used. use_boxcox : {True, False, 'log', float}, optional Should the Box-Cox transform be applied to the data first? If 'log' then apply the log. If float then use the value as lambda. .. deprecated:: 0.12 Set use_boxcox when constructing the model use_basinhopping : bool, optional Deprecated. Using Basin Hopping optimizer to find optimal values. Use ``method`` instead. .. deprecated:: 0.12 Use ``method`` instead. initial_level : float, optional Value to use when initializing the fitted level. .. deprecated:: 0.12 Set initial_level when constructing the model initial_trend : float, optional Value to use when initializing the fitted trend. .. deprecated:: 0.12 Set initial_trend when constructing the model or set initialization_method. Returns ------- HoltWintersResults See statsmodels.tsa.holtwinters.HoltWintersResults. Notes ----- This is a full implementation of the holt winters exponential smoothing as per [1]. This includes all the unstable methods as well as the stable methods. The implementation of the library covers the functionality of the R library as much as possible whilst still being Pythonic. The parameters are ordered [alpha, beta, gamma, initial_level, initial_trend, phi] which are then followed by m seasonal values if the model contains a seasonal smoother. Any parameter not relevant for the model is omitted. For example, a model that has a level and a seasonal component, but no trend and is not damped, would have starting values [alpha, gamma, initial_level, s0, s1, ..., s<m-1>] where sj is the initial value for seasonal component j. References ---------- [1] Hyndman, Rob J., and George Athanasopoulos. Forecasting: principles and practice. OTexts, 2014. # Variable renames to alpha,beta, etc as this helps with following the # mathematical notation in general alpha = float_like ( smoothing_level , "smoothing_level" , True ) beta = float_like ( smoothing_trend , "smoothing_trend" , True ) gamma = float_like ( smoothing_seasonal , "smoothing_seasonal" , True ) phi = float_like ( damping_trend , "damping_trend" , True ) initial_level = float_like ( initial_level , "initial_level" , True ) initial_trend = float_like ( initial_trend , "initial_trend" , True ) start_params = array_like ( start_params , "start_params" , optional = True ) minimize_kwargs = dict_like ( minimize_kwargs , "minimize_kwargs" , optional = True minimize_kwargs = {} if minimize_kwargs is None else minimize_kwargs use_basinhopping = bool_like ( use_basinhopping , "use_basinhopping" , optional = True supported_methods = ( "basinhopping" , "bh" ) supported_methods += ( "least_squares" , "ls" ) supported_methods += ( "L-BFGS-B" , "TNC" , "SLSQP" , "Powell" , "trust-constr" , method = string_like ( method , "method" , options = supported_methods , lower = False , optional = True , # TODO: Deprecate initial_level and related parameters from fit if initial_level is not None or initial_trend is not None : raise ValueError ( "Initial values were set during model construction. These " "cannot be changed during fit." if use_boxcox is not None : raise ValueError ( "use_boxcox was set at model initialization and cannot " "be changed" elif self . _use_boxcox is None : use_boxcox = False else : use_boxcox = self . _use_boxcox if use_basinhopping is not None : raise ValueError ( "use_basinhopping is deprecated. Set optimization method " "using 'method'." data = self . _data damped = self . damped_trend phi = phi if damped else 1.0 if self . _use_boxcox is None : if use_boxcox == "log" : lamda = 0.0 y = boxcox ( data , lamda ) elif isinstance ( use_boxcox , float ): lamda = use_boxcox y = boxcox ( data , lamda ) elif use_boxcox : y , lamda = boxcox ( data ) # use_boxcox = lamda else : y = data . squeeze () else : y = self . _y self . _y = y res = _OptConfig () res . alpha = alpha res . beta = beta res . phi = phi res . gamma = gamma res . level = initial_level res . trend = initial_trend res . seasonal = None res . y = y res . params = start_params res . mle_retvals = res . mask = None method = "SLSQP" if method is None else method if optimized : res = self . _optimize_parameters ( res , use_brute , method , minimize_kwargs else : l0 , b0 , s0 = self . initial_values ( initial_level = initial_level , initial_trend = initial_trend res . level = l0 res . trend = b0 res . seasonal = s0 if self . _fixed_parameters : fp = self . _fixed_parameters res . alpha = fp . get ( "smoothing_level" , res . alpha ) res . beta = fp . get ( "smoothing_trend" , res . beta ) res . gamma = fp . get ( "smoothing_seasonal" , res . gamma ) res . phi = fp . get ( "damping_trend" , res . phi ) res . level = fp . get ( "initial_level" , res . level ) res . trend = fp . get ( "initial_trend" , res . trend ) res . seasonal = fp . get ( "initial_seasonal" , res . seasonal ) hwfit = self . _predict ( h = 0 , smoothing_level = res . alpha , smoothing_trend = res . beta , smoothing_seasonal = res . gamma , damping_trend = res . phi , initial_level = res . level , initial_trend = res . trend , initial_seasons = res . seasonal , use_boxcox = use_boxcox , remove_bias = remove_bias , is_optimized = res . mask , hwfit . _results . mle_retvals = res . mle_retvals return hwfit [docs] def initial_values ( self , initial_level = None , initial_trend = None , force = False Compute initial values used in the exponential smoothing recursions. Parameters ---------- initial_level : {float, None} The initial value used for the level component. initial_trend : {float, None} The initial value used for the trend component. force : bool Force the calculation even if initial values exist. Returns ------- initial_level : float The initial value used for the level component. initial_trend : {float, None} The initial value used for the trend component. initial_seasons : list The initial values used for the seasonal components. Notes ----- Convenience function the exposes the values used to initialize the recursions. When optimizing parameters these are used as starting values. Method used to compute the initial value depends on when components are included in the model. In a simple exponential smoothing model without trend or a seasonal components, the initial value is set to the first observation. When a trend is added, the trend is initialized either using y[1]/y[0], if multiplicative, or y[1]-y[0]. When the seasonal component is added the initialization adapts to account for the modified structure. if self . _initialization_method is not None and not force : return ( self . _initial_level , self . _initial_trend , self . _initial_seasonal , y = self . _y trend = self . trend seasonal = self . seasonal has_seasonal = self . has_seasonal has_trend = self . has_trend m = self . seasonal_periods l0 = initial_level b0 = initial_trend if has_seasonal : l0 = y [ np . arange ( self . nobs ) % m == 0 ] . mean () if l0 is None else l0 if b0 is None and has_trend : # TODO: Fix for short m lead , lag = y [ m : m + m ], y [: m ] if trend == "mul" : b0 = np . exp (( np . log ( lead . mean ()) - np . log ( lag . mean ())) / m ) else : b0 = (( lead - lag ) / m ) . mean () s0 = list ( y [: m ] / l0 ) if seasonal == "mul" else list ( y [: m ] - l0 ) elif has_trend : l0 = y [ 0 ] if l0 is None else l0 if b0 is None : b0 = y [ 1 ] / y [ 0 ] if trend == "mul" else y [ 1 ] - y [ 0 ] s0 = [] else : if l0 is None : l0 = y [ 0 ] b0 = None s0 = [] return l0 , b0 , s0 @deprecate_kwarg ( "smoothing_slope" , "smoothing_trend" ) @deprecate_kwarg ( "damping_slope" , "damping_trend" ) def _predict ( self , h = None , smoothing_level = None , smoothing_trend = None , smoothing_seasonal = None , initial_level = None , initial_trend = None , damping_trend = None , initial_seasons = None , use_boxcox = None , lamda = None , remove_bias = None , is_optimized = None , Helper prediction function Parameters ---------- h : int, optional The number of time steps to forecast ahead. # Variable renames to alpha, beta, etc as this helps with following the # mathematical notation in general alpha = smoothing_level beta = smoothing_trend gamma = smoothing_seasonal phi = damping_trend # Start in sample and out of sample predictions data = self . endog damped = self . damped_trend has_seasonal = self . has_seasonal has_trend = self . has_trend trend = self . trend seasonal = self . seasonal m = self . seasonal_periods phi = phi if damped else 1.0 if use_boxcox == "log" : lamda = 0.0 y = boxcox ( data , 0.0 ) elif isinstance ( use_boxcox , float ): lamda = use_boxcox y = boxcox ( data , lamda ) elif use_boxcox : y , lamda = boxcox ( data ) else : lamda = None y = data . squeeze () if np . ndim ( y ) != 1 : raise NotImplementedError ( "Only 1 dimensional data supported" ) y_alpha = np . zeros (( self . nobs ,)) y_gamma = np . zeros (( self . nobs ,)) alphac = 1 - alpha y_alpha [:] = alpha * y betac = 1 - beta if beta is not None else 0 gammac = 1 - gamma if gamma is not None else 0 if has_seasonal : y_gamma [:] = gamma * y lvls = np . zeros (( self . nobs + h + 1 ,)) b = np . zeros (( self . nobs + h + 1 ,)) s = np . zeros (( self . nobs + h + m + 1 ,)) lvls [ 0 ] = initial_level b [ 0 ] = initial_trend s [: m ] = initial_seasons phi_h = ( np . cumsum ( np . repeat ( phi , h + 1 ) ** np . arange ( 1 , h + 1 + 1 )) if damped else np . arange ( 1 , h + 1 + 1 ) trended = { "mul" : np . multiply , "add" : np . add , None : lambda l , b : l }[ trend detrend = { "mul" : np . divide , "add" : np . subtract , None : lambda l , b : 0 }[ trend dampen = { "mul" : np . power , "add" : np . multiply , None : lambda b , phi : 0 }[ trend nobs = self . nobs if seasonal == "mul" : for i in range ( 1 , nobs + 1 ): lvls [ i ] = y_alpha [ i - 1 ] / s [ i - 1 ] + ( alphac * trended ( lvls [ i - 1 ], dampen ( b [ i - 1 ], phi )) if has_trend : b [ i ] = ( beta * detrend ( lvls [ i ], lvls [ i - 1 ])) + ( betac * dampen ( b [ i - 1 ], phi ) s [ i + m - 1 ] = y_gamma [ i - 1 ] / trended ( lvls [ i - 1 ], dampen ( b [ i - 1 ], phi ) ) + ( gammac * s [ i - 1 ]) _trend = b [ 1 : nobs + 1 ] . copy () season = s [ m : nobs + m ] . copy () lvls [ nobs :] = lvls [ nobs ] if has_trend : b [: nobs ] = dampen ( b [: nobs ], phi ) b [ nobs :] = dampen ( b [ nobs ], phi_h ) trend = trended ( lvls , b ) s [ nobs + m - 1 :] = [ s [( nobs - 1 ) + j % m ] for j in range ( h + 1 + 1 ) fitted = trend * s [: - m ] elif seasonal == "add" : for i in range ( 1 , nobs + 1 ): lvls [ i ] = ( y_alpha [ i - 1 ] - ( alpha * s [ i - 1 ]) + ( alphac * trended ( lvls [ i - 1 ], dampen ( b [ i - 1 ], phi ))) if has_trend : b [ i ] = ( beta * detrend ( lvls [ i ], lvls [ i - 1 ])) + ( betac * dampen ( b [ i - 1 ], phi ) s [ i + m - 1 ] = ( y_gamma [ i - 1 ] - ( gamma * trended ( lvls [ i - 1 ], dampen ( b [ i - 1 ], phi ))) + ( gammac * s [ i - 1 ]) _trend = b [ 1 : nobs + 1 ] . copy () season = s [ m : nobs + m ] . copy () lvls [ nobs :] = lvls [ nobs ] if has_trend : b [: nobs ] = dampen ( b [: nobs ], phi ) b [ nobs :] = dampen ( b [ nobs ], phi_h ) trend = trended ( lvls , b ) s [ nobs + m - 1 :] = [ s [( nobs - 1 ) + j % m ] for j in range ( h + 1 + 1 ) fitted = trend + s [: - m ] else : for i in range ( 1 , nobs + 1 ): lvls [ i ] = y_alpha [ i - 1 ] + ( alphac * trended ( lvls [ i - 1 ], dampen ( b [ i - 1 ], phi )) if has_trend : b [ i ] = ( beta * detrend ( lvls [ i ], lvls [ i - 1 ])) + ( betac * dampen ( b [ i - 1 ], phi ) _trend = b [ 1 : nobs + 1 ] . copy () season = s [ m : nobs + m ] . copy () lvls [ nobs :] = lvls [ nobs ] if has_trend : b [: nobs ] = dampen ( b [: nobs ], phi ) b [ nobs :] = dampen ( b [ nobs ], phi_h ) trend = trended ( lvls , b ) fitted = trend level = lvls [ 1 : nobs + 1 ] . copy () if use_boxcox or use_boxcox == "log" or isinstance ( use_boxcox , float ): fitted = inv_boxcox ( fitted , lamda ) err = fitted [: - h - 1 ] - data sse = err . T @ err # (s0 + gamma) + (b0 + beta) + (l0 + alpha) + phi k = m * has_seasonal + 2 * has_trend + 2 + 1 * damped aic = self . nobs * np . log ( sse / self . nobs ) + k * 2 dof_eff = self . nobs - k - 3 if dof_eff > 0 : aicc_penalty = ( 2 * ( k + 2 ) * ( k + 3 )) / dof_eff else : aicc_penalty = np . inf aicc = aic + aicc_penalty bic = self . nobs * np . log ( sse / self . nobs ) + k * np . log ( self . nobs ) resid = data - fitted [: - h - 1 ] if remove_bias : fitted += resid . mean () self . params = { "smoothing_level" : alpha , "smoothing_trend" : beta , "smoothing_seasonal" : gamma , "damping_trend" : phi if damped else np . nan , "initial_level" : lvls [ 0 ], "initial_trend" : b [ 0 ] / phi if phi > 0 else 0 , "initial_seasons" : s [: m ], "use_boxcox" : use_boxcox , "lamda" : lamda , "remove_bias" : remove_bias , # Format parameters into a DataFrame codes = [ "alpha" , "beta" , "gamma" , "l.0" , "b.0" , "phi" ] codes += [ f "s. { i } " for i in range ( m )] idx = [ "smoothing_level" , "smoothing_trend" , "smoothing_seasonal" , "initial_level" , "initial_trend" , "damping_trend" , idx += [ f "initial_seasons. { i } " for i in range ( m )] formatted = [ alpha , beta , gamma , lvls [ 0 ], b [ 0 ], phi ] formatted += s [: m ] . tolist () formatted = list ( map ( lambda v : np . nan if v is None else v , formatted )) formatted = np . array ( formatted ) if is_optimized is None : optimized = np . zeros ( len ( codes ), dtype = bool ) else : optimized = is_optimized . astype ( bool ) included = [ True , has_trend , has_seasonal , True , has_trend , damped ] included += [ True ] * m formatted = pd . DataFrame ( [[ c , f , o ] for c , f , o in zip ( codes , formatted , optimized )], columns = [ "name" , "param" , "optimized" ], index = idx , formatted = formatted . loc [ included ] hwfit = HoltWintersResults ( self , self . params , fittedfcast = fitted , fittedvalues = fitted [: - h - 1 ], fcastvalues = fitted [ - h - 1 :], sse = sse , level = level , trend = _trend , season = season , aic = aic , bic = bic , aicc = aicc , resid = resid , k = k , params_formatted = formatted , optimized = optimized , return HoltWintersResultsWrapper ( hwfit ) The time series to model. initialization_method : str, optional Method for initialize the recursions. One of: * None * 'estimated' * 'heuristic' * 'legacy-heuristic' * 'known' None defaults to the pre-0.12 behavior where initial values are passed as part of ``fit``. If any of the other values are passed, then the initial values must also be set when constructing the model. If 'known' initialization is used, then `initial_level` must be passed, as well as `initial_trend` and `initial_seasonal` if applicable. Default is 'estimated'. "legacy-heuristic" uses the same values that were used in statsmodels 0.11 and earlier. initial_level : float, optional The initial level component. Required if estimation method is "known". If set using either "estimated" or "heuristic" this value is used. This allows one or more of the initial values to be set while deferring to the heuristic for others or estimating the unset parameters. See Also -------- ExponentialSmoothing Exponential smoothing with trend and seasonal components. Exponential smoothing with a trend component. Notes ----- This is a full implementation of the simple exponential smoothing as per [1]_. `SimpleExpSmoothing` is a restricted version of :class:`ExponentialSmoothing`. See the notebook `Exponential Smoothing <../examples/notebooks/generated/exponential_smoothing.html>`__ for an overview. References ---------- .. [1] Hyndman, Rob J., and George Athanasopoulos. Forecasting: principles and practice. OTexts, 2014. def __init__ ( self , endog , initialization_method = None , # Future: 'estimated', initial_level = None , super () . __init__ ( endog , initialization_method = initialization_method , initial_level = initial_level , [docs] def fit ( self , smoothing_level = None , optimized = True , start_params = None , initial_level = None , use_brute = True , use_boxcox = None , remove_bias = False , method = None , minimize_kwargs = None , Fit the model Parameters ---------- smoothing_level : float, optional The smoothing_level value of the simple exponential smoothing, if the value is set then this value will be used as the value. optimized : bool, optional Estimate model parameters by maximizing the log-likelihood. start_params : ndarray, optional Starting values to used when optimizing the fit. If not provided, starting values are determined using a combination of grid search and reasonable values based on the initial values of the data. initial_level : float, optional Value to use when initializing the fitted level. use_brute : bool, optional Search for good starting values using a brute force (grid) optimizer. If False, a naive set of starting values is used. use_boxcox : {True, False, 'log', float}, optional Should the Box-Cox transform be applied to the data first? If 'log' then apply the log. If float then use the value as lambda. remove_bias : bool, optional Remove bias from forecast values and fitted values by enforcing that the average residual is equal to zero. method : str, default "L-BFGS-B" The minimizer used. Valid options are "L-BFGS-B" (default), "TNC", "SLSQP", "Powell", "trust-constr", "basinhopping" (also "bh") and "least_squares" (also "ls"). basinhopping tries multiple starting values in an attempt to find a global minimizer in non-convex problems, and so is slower than the others. minimize_kwargs : dict[str, Any] A dictionary of keyword arguments passed to SciPy's minimize function if method is one of "L-BFGS-B" (default), "TNC", "SLSQP", "Powell", or "trust-constr", or SciPy's basinhopping or least_squares. The valid keywords are optimizer specific. Consult SciPy's documentation for the full set of options. Returns ------- HoltWintersResults See statsmodels.tsa.holtwinters.HoltWintersResults. Notes ----- This is a full implementation of the simple exponential smoothing as per [1]. References ---------- [1] Hyndman, Rob J., and George Athanasopoulos. Forecasting: principles and practice. OTexts, 2014. return super () . fit ( smoothing_level = smoothing_level , optimized = optimized , start_params = start_params , initial_level = initial_level , use_brute = use_brute , remove_bias = remove_bias , use_boxcox = use_boxcox , method = method , minimize_kwargs = minimize_kwargs , Type of trend component. damped_trend : bool, optional Should the trend component be damped. initialization_method : str, optional Method for initialize the recursions. One of: * None * 'estimated' * 'heuristic' * 'legacy-heuristic' * 'known' None defaults to the pre-0.12 behavior where initial values are passed as part of ``fit``. If any of the other values are passed, then the initial values must also be set when constructing the model. If 'known' initialization is used, then `initial_level` must be passed, as well as `initial_trend` and `initial_seasonal` if applicable. Default is 'estimated'. "legacy-heuristic" uses the same values that were used in statsmodels 0.11 and earlier. initial_level : float, optional The initial level component. Required if estimation method is "known". If set using either "estimated" or "heuristic" this value is used. This allows one or more of the initial values to be set while deferring to the heuristic for others or estimating the unset parameters. initial_trend : float, optional The initial trend component. Required if estimation method is "known". If set using either "estimated" or "heuristic" this value is used. This allows one or more of the initial values to be set while deferring to the heuristic for others or estimating the unset parameters. See Also -------- ExponentialSmoothing Exponential smoothing with trend and seasonal components. SimpleExpSmoothing Basic exponential smoothing with only a level component. Notes ----- This is a full implementation of the Holt's exponential smoothing as per [1]_. `Holt` is a restricted version of :class:`ExponentialSmoothing`. See the notebook `Exponential Smoothing <../examples/notebooks/generated/exponential_smoothing.html>`__ for an overview. References ---------- .. [1] Hyndman, Rob J., and George Athanasopoulos. Forecasting: principles and practice. OTexts, 2014. @deprecate_kwarg ( "damped" , "damped_trend" ) def __init__ ( self , endog , exponential = False , damped_trend = False , initialization_method = None , # Future: 'estimated', initial_level = None , initial_trend = None , trend = "mul" if exponential else "add" super () . __init__ ( endog , trend = trend , damped_trend = damped_trend , initialization_method = initialization_method , initial_level = initial_level , initial_trend = initial_trend , [docs] @deprecate_kwarg ( "smoothing_slope" , "smoothing_trend" ) @deprecate_kwarg ( "initial_slope" , "initial_trend" ) @deprecate_kwarg ( "damping_slope" , "damping_trend" ) def fit ( self , smoothing_level = None , smoothing_trend = None , damping_trend = None , optimized = True , start_params = None , initial_level = None , initial_trend = None , use_brute = True , use_boxcox = None , remove_bias = False , method = None , minimize_kwargs = None , Fit the model Parameters ---------- smoothing_level : float, optional The alpha value of the simple exponential smoothing, if the value is set then this value will be used as the value. smoothing_trend : float, optional The beta value of the Holt's trend method, if the value is set then this value will be used as the value. damping_trend : float, optional The phi value of the damped method, if the value is set then this value will be used as the value. optimized : bool, optional Estimate model parameters by maximizing the log-likelihood. start_params : ndarray, optional Starting values to used when optimizing the fit. If not provided, starting values are determined using a combination of grid search and reasonable values based on the initial values of the data. initial_level : float, optional Value to use when initializing the fitted level. .. deprecated:: 0.12 Set initial_level when constructing the model initial_trend : float, optional Value to use when initializing the fitted trend. .. deprecated:: 0.12 Set initial_trend when constructing the model use_brute : bool, optional Search for good starting values using a brute force (grid) optimizer. If False, a naive set of starting values is used. use_boxcox : {True, False, 'log', float}, optional Should the Box-Cox transform be applied to the data first? If 'log' then apply the log. If float then use the value as lambda. remove_bias : bool, optional Remove bias from forecast values and fitted values by enforcing that the average residual is equal to zero. method : str, default "L-BFGS-B" The minimizer used. Valid options are "L-BFGS-B" (default), "TNC", "SLSQP", "Powell", "trust-constr", "basinhopping" (also "bh") and "least_squares" (also "ls"). basinhopping tries multiple starting values in an attempt to find a global minimizer in non-convex problems, and so is slower than the others. minimize_kwargs : dict[str, Any] A dictionary of keyword arguments passed to SciPy's minimize function if method is one of "L-BFGS-B" (default), "TNC", "SLSQP", "Powell", or "trust-constr", or SciPy's basinhopping or least_squares. The valid keywords are optimizer specific. Consult SciPy's documentation for the full set of options. Returns ------- HoltWintersResults See statsmodels.tsa.holtwinters.HoltWintersResults. Notes ----- This is a full implementation of the Holt's exponential smoothing as per [1]. References ---------- [1] Hyndman, Rob J., and George Athanasopoulos. Forecasting: principles and practice. OTexts, 2014. return super () . fit ( smoothing_level = smoothing_level , smoothing_trend = smoothing_trend , damping_trend = damping_trend , optimized = optimized , start_params = start_params , initial_level = initial_level , initial_trend = initial_trend , use_brute = use_brute , use_boxcox = use_boxcox , remove_bias = remove_bias , method = method , minimize_kwargs = minimize_kwargs ,