statsmodels.tsa.statespace.representation.Representation

class statsmodels.tsa.statespace.representation.Representation(k_endog, k_states, k_posdef=None, initial_variance=1000000.0, nobs=0, dtype=<class 'numpy.float64'>, design=None, obs_intercept=None, obs_cov=None, transition=None, state_intercept=None, selection=None, state_cov=None, statespace_classes=None, **kwargs)[source]

State space representation of a time series process

Parameters:
k_endog{array_like, int}

The observed time-series process \(y\) if array like or the number of variables in the process if an integer.

k_statesint

The dimension of the unobserved state process.

k_posdefint, optional

The dimension of a guaranteed positive definite covariance matrix describing the shocks in the measurement equation. Must be less than or equal to k_states. Default is k_states.

initial_variancefloat, optional

Initial variance used when approximate diffuse initialization is specified. Default is 1e6.

initializationInitialization object or str, optional

Initialization method for the initial state. If a string, must be one of {‘diffuse’, ‘approximate_diffuse’, ‘stationary’, ‘known’}.

initial_statearray_like, optional

If initialization=’known’ is used, the mean of the initial state’s distribution.

initial_state_covarray_like, optional

If initialization=’known’ is used, the covariance matrix of the initial state’s distribution.

nobsint, optional

If an endogenous vector is not given (i.e. k_endog is an integer), the number of observations can optionally be specified. If not specified, they will be set to zero until data is bound to the model.

dtypenp.dtype, optional

If an endogenous vector is not given (i.e. k_endog is an integer), the default datatype of the state space matrices can optionally be specified. Default is np.float64.

designarray_like, optional

The design matrix, \(Z\). Default is set to zeros.

obs_interceptarray_like, optional

The intercept for the observation equation, \(d\). Default is set to zeros.

obs_covarray_like, optional

The covariance matrix for the observation equation \(H\). Default is set to zeros.

transitionarray_like, optional

The transition matrix, \(T\). Default is set to zeros.

state_interceptarray_like, optional

The intercept for the transition equation, \(c\). Default is set to zeros.

selectionarray_like, optional

The selection matrix, \(R\). Default is set to zeros.

state_covarray_like, optional

The covariance matrix for the state equation \(Q\). Default is set to zeros.

**kwargs

Additional keyword arguments. Not used directly. It is present to improve compatibility with subclasses, so that they can use **kwargs to specify any default state space matrices (e.g. design) without having to clean out any other keyword arguments they might have been passed.

Notes

A general state space model is of the form

\[\begin{split}y_t & = Z_t \alpha_t + d_t + \varepsilon_t \\ \alpha_t & = T_t \alpha_{t-1} + c_t + R_t \eta_t \\\end{split}\]

where \(y_t\) refers to the observation vector at time \(t\), \(\alpha_t\) refers to the (unobserved) state vector at time \(t\), and where the irregular components are defined as

\[\begin{split}\varepsilon_t \sim N(0, H_t) \\ \eta_t \sim N(0, Q_t) \\\end{split}\]

The remaining variables (\(Z_t, d_t, H_t, T_t, c_t, R_t, Q_t\)) in the equations are matrices describing the process. Their variable names and dimensions are as follows

Z : design \((k\_endog \times k\_states \times nobs)\)

d : obs_intercept \((k\_endog \times nobs)\)

H : obs_cov \((k\_endog \times k\_endog \times nobs)\)

T : transition \((k\_states \times k\_states \times nobs)\)

c : state_intercept \((k\_states \times nobs)\)

R : selection \((k\_states \times k\_posdef \times nobs)\)

Q : state_cov \((k\_posdef \times k\_posdef \times nobs)\)

In the case that one of the matrices is time-invariant (so that, for example, \(Z_t = Z_{t+1} ~ \forall ~ t\)), its last dimension may be of size \(1\) rather than size nobs.

References

Attributes:
nobsint

The number of observations.

k_endogint

The dimension of the observation series.

k_statesint

The dimension of the unobserved state process.

k_posdefint

The dimension of a guaranteed positive definite covariance matrix describing the shocks in the measurement equation.

shapesdictionary of name:tuple

A dictionary recording the initial shapes of each of the representation matrices as tuples.

initializationstr

Kalman filter initialization method. Default is unset.

initial_variancefloat

Initial variance for approximate diffuse initialization. Default is 1e6.

Methods

bind(endog)

Bind data to the statespace representation

clone(endog, **kwargs)

Clone a state space representation while overriding some elements

diff_endog(new_endog[, tolerance])

extend(endog[, start, end])

Extend the current state space model, or a specific (time) subset

initialize(initialization[, ...])

Create an Initialization object if necessary

initialize_approximate_diffuse([variance])

Initialize the statespace model with approximate diffuse values.

initialize_diffuse()

Initialize the statespace model as stationary.

initialize_known(constant, stationary_cov)

Initialize the statespace model with known distribution for initial state.

initialize_stationary()

Initialize the statespace model as stationary.

Properties

design

(array) Design matrix: \(Z~(k\_endog \times k\_states \times nobs)\)

dtype

(dtype) Datatype of currently active representation matrices

endog

(array) The observation vector, alias for obs.

obs

(array) Observation vector: \(y~(k\_endog \times nobs)\)

obs_cov

(array) Observation covariance matrix: \(H~(k\_endog \times k\_endog \times nobs)\)

obs_intercept

(array) Observation intercept: \(d~(k\_endog \times nobs)\)

prefix

(str) BLAS prefix of currently active representation matrices

selection

(array) Selection matrix: \(R~(k\_states \times k\_posdef \times nobs)\)

state_cov

(array) State covariance matrix: \(Q~(k\_posdef \times k\_posdef \times nobs)\)

state_intercept

(array) State intercept: \(c~(k\_states \times nobs)\)

time_invariant

(bool) Whether or not currently active representation matrices are time-invariant

transition

(array) Transition matrix: \(T~(k\_states \times k\_states \times nobs)\)