Coverage for /home/martinb/.local/share/virtualenvs/camcops/lib/python3.6/site-packages/statsmodels/tsa/arima/estimators/statespace.py : 22%

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.
4Author: Chad Fulton
5License: BSD-3
6"""
7import numpy as np
9from statsmodels.tools.tools import add_constant, Bunch
10from statsmodels.tsa.statespace.sarimax import SARIMAX
12from statsmodels.tsa.arima.specification import SARIMAXSpecification
13from statsmodels.tsa.arima.params import SARIMAXParams
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.
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.
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.
66 Notes
67 -----
68 The primary reference is [1]_.
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)
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)
91 # Check start parameters
92 if start_params is not None:
93 sp = SARIMAXParams(spec=spec)
94 sp.params = start_params
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`.')
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`.')
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)
115 # Construct results
116 p.params = res_ss.params
117 res = Bunch({
118 'spec': spec,
119 'statespace_results': res_ss,
120 })
122 return p, res