statsmodels.tsa.statespace.initialization.Initialization#

class statsmodels.tsa.statespace.initialization.Initialization(k_states, initialization_type=None, initialization_classes=None, approximate_diffuse_variance=1000000.0, constant=None, stationary_cov=None)[source]#

State space initialization

Parameters:

k_statesint: Number of states in the state space model.
initialization_typestr, optional: The type of initialization to use globally for all of the states. Must be one of ‘known’, ‘diffuse’, ‘approximate_diffuse’, or ‘stationary’. If not specified, no global initialization is performed and blocks of states must instead be initialized using the set method.
initialization_classesdict, optional: Dictionary with BLAS prefixes as keys and the associated Cython initialization classes as values. If not specified, the default mapping is used.
approximate_diffuse_variancefloat, optional: If using approximate diffuse initialization, the initial variance used. Default is 1e6.
constantarray_like, optional: A vector of constant values, denoted \(a\). Only used if initialization_type is specified.
stationary_covarray_like, optional: The covariance matrix of the stationary part, denoted \(Q_0\). Only used if initialization_type is specified.

Attributes:

initialized: bool, whether or not all states have been initialized

Methods

`__call__`([index, model, initial_state_mean, ...])	Construct initialization representation
`clear`()	Clear all previously set initializations, either global or block level
`from_components`(k_states[, a, Pstar, Pinf, ...])	Construct initialization object from component matrices
`set`(index, initialization_type[, constant, ...])	Set initialization for states, either globally or for a block
`unset`(index)	Unset initialization for states, either globally or for a block

from_results

Notes

As developed in Durbin and Koopman (2012), the state space recursions must be initialized for the first time period. The general form of this initialization is:

\[\begin{split}\alpha_1 & = a + A \delta + R_0 \eta_0 \\ \delta & \sim N(0, \kappa I), \kappa \to \infty \\ \eta_0 & \sim N(0, Q_0)\end{split}\]

Thus the state vector can be initialized with a known constant part (elements of \(a\)), with part modeled as a diffuse initial distribution (as a part of \(\delta\)), and with a part modeled as a known (proper) initial distribution (as a part of \(\eta_0\)).

There are two important restrictions:

An element of the state vector initialized as diffuse cannot be also modeled with a stationary component. In the validate method, violations of this cause an exception to be raised.
If an element of the state vector is initialized with both a known constant part and with a diffuse initial distribution, the effect of the diffuse initialization will essentially ignore the given known constant value. In the validate method, violations of this cause a warning to be given, since it is not technically invalid but may indicate user error.

The \(\eta_0\) component is also referred to as the stationary part because it is often set to the unconditional distribution of a stationary process.

Initialization is specified for blocks (consecutive only, for now) of the state vector, with the entire state vector and individual elements as special cases. Denote the block in question as \(\alpha_1^{(i)}\). It can be initialized in the following ways:

‘known’
‘diffuse’ or ‘exact_diffuse’ or ‘approximate_diffuse’
‘stationary’
‘mixed’

In the first three cases, the block’s initialization is specified as an instance of the Initialization class, with the initialization_type attribute set to one of those three string values. In the ‘mixed’ cases, the initialization is also an instance of the Initialization class, but it will itself contain sub-blocks. Details of each type follow.

Regardless of the type, for each block, the following must be defined: the constant array, an array diffuse with indices corresponding to diffuse elements, an array stationary with indices corresponding to stationary elements, and stationary_cov, a matrix with order equal to the number of stationary elements in the block.

Known

If a block is initialized as known, then a known (possibly degenerate) distribution is used; in particular, the block of states is understood to be distributed \(\alpha_1^{(i)} \sim N(a^{(i)}, Q_0^{(i)})\). Here, it is possible to set \(a^{(i)} = 0\), and it is also possible that \(Q_0^{(i)}\) is only positive-semidefinite; i.e. \(\alpha_1^{(i)}\) may be degenerate. One particular example is that if the entire block’s initial values are known, then \(R_0^{(i)} = 0\), and so Var(alpha_1^{(i)}) = 0.

Here, constant must be provided (although it can be zeros), and stationary_cov is optional (by default it is a matrix of zeros).

Diffuse

If a block is initialized as diffuse, then set \(\alpha_1^{(i)} \sim N(a^{(i)}, \kappa^{(i)} I)\). If the block is initialized using the exact diffuse initialization procedure, then it is understood that \(\kappa^{(i)} \to \infty\).

If the block is initialized using the approximate diffuse initialization procedure, then kappa^{(i)} is set to some large value rather than driven to infinity.

In the approximate diffuse initialization case, it is possible, although unlikely, that a known constant value may have some effect on initialization if \(\kappa^{(i)}\) is not set large enough.

Here, constant may be provided, and approximate_diffuse_variance may be provided.

Stationary

If a block is initialized as stationary, then the block of states is understood to have the distribution \(\alpha_1^{(i)} \sim N(a^{(i)}, Q_0^{(i)})\). \(a^{(i)}\) is the unconditional mean of the block, computed as \((I - T^{(i)})^{-1} c_t\). \(Q_0^{(i)}\) is the unconditional variance of the block, computed as the solution to the discrete Lyapunov equation:

\[T^{(i)} Q_0^{(i)} T^{(i)} + (R Q R')^{(i)} = Q_0^{(i)}\]

\(T^{(i)}\) and \((R Q R')^{(i)}\) are the submatrices of the corresponding state space system matrices corresponding to the given block of states.

Here, no values can be provided.

Mixed

In this case, the block can be further broken down into sub-blocks. Usually, only the top-level Initialization instance will be of ‘mixed’ type, and in many cases, even the top-level instance will be purely ‘known’, ‘diffuse’, or ‘stationary’.

For a block of type mixed, suppose that it has J sub-blocks, \(\alpha_1^{(i,j)}\). Then \(\alpha_1^{(i)} = a^{(i)} + A^{(i)} \delta + R_0^{(i)} \eta_0^{(i)}\).

Examples

Basic examples have one specification for all of the states:

>>> Initialization(2, 'known', constant=[0, 1])
>>> Initialization(2, 'known', stationary_cov=np.eye(2))
>>> Initialization(2, 'known', constant=[0, 1],
                   stationary_cov=np.eye(2))
>>> Initialization(2, 'diffuse')
>>> Initialization(2, 'approximate_diffuse',
                   approximate_diffuse_variance=1e6)
>>> Initialization(2, 'stationary')

More complex examples initialize different blocks of states separately

>>> init = Initialization(k_states=3)
>>> init.set((0, 1), 'known', constant=[0, 1])
>>> init.set((0, 1), 'known', stationary_cov=np.eye(2))
>>> init.set((0, 1), 'known', constant=[0, 1],
             stationary_cov=np.eye(2))
>>> init.set((0, 1), 'diffuse')
>>> init.set((0, 1), 'approximate_diffuse',
             approximate_diffuse_variance=1e6)
>>> init.set((0, 1), 'stationary')

A still more complex example initializes a block using a previously created Initialization object:

>>> init1 = Initialization(2, 'known', constant=[0, 1])
>>> init2 = Initialization(k_states=3)
>>> init2.set((1, 2), init1)

Methods

`clear`()	Clear all previously set initializations, either global or block level
`from_components`(k_states[, a, Pstar, Pinf, ...])	Construct initialization object from component matrices
`from_results`(filter_results)
`set`(index, initialization_type[, constant, ...])	Set initialization for states, either globally or for a block
`unset`(index)	Unset initialization for states, either globally or for a block

Properties

initialized

bool, whether or not all states have been initialized