Representation¶

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

State space representation of a time series process

Parameters:

k_endog : array_like or integer The observed time-series process \(y\) if array like or the number of variables in the process if an integer. k_states : int The dimension of the unobserved state process. k_posdef : int, 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_variance : float, optional Initial variance used when approximate diffuse initialization is specified. Default is 1e6. initialization : {‘approximate_diffuse’,’stationary’,’known’}, optional Initialization method for the initial state. initial_state : array_like, optional If known initialization is used, the mean of the initial state’s distribution. initial_state_cov : array_like, optional If known initialization is used, the covariance matrix of the initial state’s distribution. nobs : integer, 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. dtype : 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. design : array_like, optional The design matrix, \(Z\). Default is set to zeros. obs_intercept : array_like, optional The intercept for the observation equation, \(d\). Default is set to zeros. obs_cov : array_like, optional The covariance matrix for the observation equation \(H\). Default is set to zeros. transition : array_like, optional The transition matrix, \(T\). Default is set to zeros. state_intercept : array_like, optional The intercept for the transition equation, \(c\). Default is set to zeros. selection : array_like, optional The selection matrix, \(R\). Default is set to zeros. state_cov : array_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

[R5]	Durbin, James, and Siem Jan Koopman. 2012. Time Series Analysis by State Space Methods: Second Edition. Oxford University Press.

Attributes

nobs	(int) The number of observations.
k_endog	(int) The dimension of the observation series.
k_states	(int) The dimension of the unobserved state process.
k_posdef	(int) The dimension of a guaranteed positive definite covariance matrix describing the shocks in the measurement equation.
shapes	(dictionary of name:tuple) A dictionary recording the initial shapes of each of the representation matrices as tuples.
initialization	(str) Kalman filter initialization method. Default is unset.
initial_variance	(float) Initial variance for approximate diffuse initialization. Default is 1e6.

bind(endog)[source]¶

Bind data to the statespace representation

Parameters:	endog : array Endogenous data to bind to the model. Must be column-ordered ndarray with shape (k_endog, nobs) or row-ordered ndarray with shape (nobs, k_endog).

Notes

The strict requirements arise because the underlying statespace and Kalman filtering classes require Fortran-ordered arrays in the wide format (shaped (k_endog, nobs)), and this structure is setup to prevent copying arrays in memory.

By default, numpy arrays are row (C)-ordered and most time series are represented in the long format (with time on the 0-th axis). In this case, no copying or re-ordering needs to be performed, instead the array can simply be transposed to get it in the right order and shape.

Although this class (Representation) has stringent bind requirements, it is assumed that it will rarely be used directly.

design = None¶

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

dtype¶

(dtype) Datatype of currently active representation matrices

endog = None¶

(array) The observation vector, alias for obs.

initialize_approximate_diffuse(variance=None)[source]¶

Initialize the statespace model with approximate diffuse values.

Rather than following the exact diffuse treatment (which is developed for the case that the variance becomes infinitely large), this assigns an arbitrary large number for the variance.

Parameters:	variance : float, optional The variance for approximating diffuse initial conditions. Default is 1e6.

initialize_known(initial_state, initial_state_cov)[source]¶

Initialize the statespace model with known distribution for initial state.

These values are assumed to be known with certainty or else filled with parameters during, for example, maximum likelihood estimation.

Parameters:	initial_state : array_like Known mean of the initial state vector. initial_state_cov : array_like Known covariance matrix of the initial state vector.

initialize_stationary()[source]¶

Initialize the statespace model as stationary.

obs¶

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

obs_cov = None¶

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

obs_intercept = None¶

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

prefix¶

(str) BLAS prefix of currently active representation matrices

selection = None¶

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

state_cov = None¶

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

state_intercept = None¶

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

time_invariant¶

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

transition = None¶

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

class dismalpy.ssm.representation.FrozenRepresentation(model)[source]¶

Frozen Statespace Model

Takes a snapshot of a Statespace model.

Parameters:	model : Representation A Statespace representation

Attributes

nobs	(int) Number of observations.
k_endog	(int) The dimension of the observation series.
k_states	(int) The dimension of the unobserved state process.
k_posdef	(int) The dimension of a guaranteed positive definite covariance matrix describing the shocks in the measurement equation.
dtype	(dtype) Datatype of representation matrices
prefix	(str) BLAS prefix of representation matrices
shapes	(dictionary of name:tuple) A dictionary recording the shapes of each of the representation matrices as tuples.
endog	(array) The observation vector.
design	(array) The design matrix, \(Z\).
obs_intercept	(array) The intercept for the observation equation, \(d\).
obs_cov	(array) The covariance matrix for the observation equation \(H\).
transition	(array) The transition matrix, \(T\).
state_intercept	(array) The intercept for the transition equation, \(c\).
selection	(array) The selection matrix, \(R\).
state_cov	(array) The covariance matrix for the state equation \(Q\).
missing	(array of bool) An array of the same size as endog, filled with boolean values that are True if the corresponding entry in endog is NaN and False otherwise.
nmissing	(array of int) An array of size nobs, where the ith entry is the number (between 0 and k_endog) of NaNs in the ith row of the endog array.
time_invariant	(bool) Whether or not the representation matrices are time-invariant
initialization	(str) Kalman filter initialization method.
initial_state	(array_like) The state vector used to initialize the Kalamn filter.
initial_state_cov	(array_like) The state covariance matrix used to initialize the Kalamn filter.