Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1""" 

2State space approach to estimating SARIMAX models. 

3 

4Author: Chad Fulton 

5License: BSD-3 

6""" 

7import numpy as np 

8 

9from statsmodels.tools.tools import add_constant, Bunch 

10from statsmodels.tsa.statespace.sarimax import SARIMAX 

11 

12from statsmodels.tsa.arima.specification import SARIMAXSpecification 

13from statsmodels.tsa.arima.params import SARIMAXParams 

14 

15 

16def statespace(endog, exog=None, order=(0, 0, 0), 

17 seasonal_order=(0, 0, 0, 0), include_constant=True, 

18 enforce_stationarity=True, enforce_invertibility=True, 

19 concentrate_scale=False, start_params=None, fit_kwargs=None): 

20 """ 

21 Estimate SARIMAX parameters using state space methods. 

22 

23 Parameters 

24 ---------- 

25 endog : array_like 

26 Input time series array. 

27 order : tuple, optional 

28 The (p,d,q) order of the model for the number of AR parameters, 

29 differences, and MA parameters. Default is (0, 0, 0). 

30 seasonal_order : tuple, optional 

31 The (P,D,Q,s) order of the seasonal component of the model for the 

32 AR parameters, differences, MA parameters, and periodicity. Default 

33 is (0, 0, 0, 0). 

34 include_constant : bool, optional 

35 Whether to add a constant term in `exog` if it's not already there. 

36 The estimate of the constant will then appear as one of the `exog` 

37 parameters. If `exog` is None, then the constant will represent the 

38 mean of the process. 

39 enforce_stationarity : bool, optional 

40 Whether or not to transform the AR parameters to enforce stationarity 

41 in the autoregressive component of the model. Default is True. 

42 enforce_invertibility : bool, optional 

43 Whether or not to transform the MA parameters to enforce invertibility 

44 in the moving average component of the model. Default is True. 

45 concentrate_scale : bool, optional 

46 Whether or not to concentrate the scale (variance of the error term) 

47 out of the likelihood. This reduces the number of parameters estimated 

48 by maximum likelihood by one. 

49 start_params : array_like, optional 

50 Initial guess of the solution for the loglikelihood maximization. The 

51 AR polynomial must be stationary. If `enforce_invertibility=True` the 

52 MA poylnomial must be invertible. If not provided, default starting 

53 parameters are computed using the Hannan-Rissanen method. 

54 fit_kwargs : dict, optional 

55 Arguments to pass to the state space model's `fit` method. 

56 

57 Returns 

58 ------- 

59 parameters : SARIMAXParams object 

60 other_results : Bunch 

61 Includes two components, `spec`, containing the `SARIMAXSpecification` 

62 instance corresponding to the input arguments; and 

63 `state_space_results`, corresponding to the results from the underlying 

64 state space model and Kalman filter / smoother. 

65 

66 Notes 

67 ----- 

68 The primary reference is [1]_. 

69 

70 References 

71 ---------- 

72 .. [1] Durbin, James, and Siem Jan Koopman. 2012. 

73 Time Series Analysis by State Space Methods: Second Edition. 

74 Oxford University Press. 

75 """ 

76 # Handle including the constant (need to do it now so that the constant 

77 # parameter can be included in the specification as part of `exog`.) 

78 if include_constant: 

79 exog = np.ones_like(endog) if exog is None else add_constant(exog) 

80 

81 # Create the specification 

82 spec = SARIMAXSpecification( 

83 endog, exog=exog, order=order, seasonal_order=seasonal_order, 

84 enforce_stationarity=enforce_stationarity, 

85 enforce_invertibility=enforce_invertibility, 

86 concentrate_scale=concentrate_scale) 

87 endog = spec.endog 

88 exog = spec.exog 

89 p = SARIMAXParams(spec=spec) 

90 

91 # Check start parameters 

92 if start_params is not None: 

93 sp = SARIMAXParams(spec=spec) 

94 sp.params = start_params 

95 

96 if spec.enforce_stationarity and not sp.is_stationary: 

97 raise ValueError('Given starting parameters imply a non-stationary' 

98 ' AR process with `enforce_stationarity=True`.') 

99 

100 if spec.enforce_invertibility and not sp.is_invertible: 

101 raise ValueError('Given starting parameters imply a non-invertible' 

102 ' MA process with `enforce_invertibility=True`.') 

103 

104 # Create and fit the state space model 

105 mod = SARIMAX(endog, exog=exog, order=spec.order, 

106 seasonal_order=spec.seasonal_order, 

107 enforce_stationarity=spec.enforce_stationarity, 

108 enforce_invertibility=spec.enforce_invertibility, 

109 concentrate_scale=spec.concentrate_scale) 

110 if fit_kwargs is None: 

111 fit_kwargs = {} 

112 fit_kwargs.setdefault('disp', 0) 

113 res_ss = mod.fit(start_params=start_params, **fit_kwargs) 

114 

115 # Construct results 

116 p.params = res_ss.params 

117 res = Bunch({ 

118 'spec': spec, 

119 'statespace_results': res_ss, 

120 }) 

121 

122 return p, res