%% Create State-Space Model Containing ARMA State
% This example shows how to create a stationary ARMA model subject to measurement error using ssm.
% To explicitly create a state-space model, it is helpful to write the state and observation equations in matrix form. In this example, the state of interest is the ARMA(2,1) process
% x_{t} = c + \phi_1 x_{t-1} + \phi_2 x_{t-2} + u_t + \theta_1 u_{t-1},
% where u_{t} is Gaussian with mean 0 and known standard deviation 0.5.
% The variables x_t, x_{t-1}, and u_{t} are in the state-space model framework. Therefore, the terms c, \phi_2x_{t-2}, and \theta_1 u_{t-1} require "dummy states" to be included in the model.
% Subsequently, the state equation is
% \left[ {\begin{array}{*{20}{c}}{{x_{1,t}}}\\{{x_{2,t}}}\\{{x_{3,t}}}\\{{x_{4,t}}}\end{array}}
% \right] = \left[
% {\begin{array}{*{20}{c}}\phi_1&c&\phi_2&\theta_1\\0&1&0&0\\1&0&0&0\\0&0&0&0\end{array}} \right]\left[
% {\begin{array}{*{20}{c}}{{x_{1,t - 1}}}\\{{x_{2,t - 1}}}\\{{x_{3,t -
% 1}}}\\{{x_{4,t -
% 1}}}\end{array}} \right] + \left[ {\begin{array}{*{20}{c}}0.5\\0\\0\\1\end{array}} \right]u_{1,t}
% Note that:
% c corresponds to a state (x_{2,t}) that is always 1.
% x_{3,t} = x_{1,t-1}, and x_{1,t} has the term \phi_2x_{3,t - 1} = \phi_2x_{1,t - 2}.
% x_{1,t} has the term 0.5 u_{1,t}.  ssm puts state disturbances as Gaussian random variables with mean 0 and variance 1. Therefore, the factor 0.5 is the standard deviation of the state disturbance.
% x_{4,t} = u_{1,t}, and x_{1,t} has the term \theta_1x_{4,t} = \theta_1u_{1,t-1}.
% The observation equation is unbiased for the ARMA(2,1) state process. The observation innovations are Gaussian with mean 0 and known standard deviation 0.1. Symbolically, the observation equation is
% {y_t} = \left[ {\begin{array}{*{20}{c}}1&0&0&0\end{array}}
% \right]\left[
% {\begin{array}{*{20}{c}}{{x_{1,t}}}\\{{x_{2,t}}}\\{{x_{3,t}}}\\{{x_{4,t}}}\end{array}}
% \right]+0.1\varepsilon_t.
% You can include a measurement-sensitivity factor (a bias) by replacing 1 in the row vector by a scalar or unknown parameter.
% Define the state-transition coefficient matrix. Use NaN values to indicate unknown parameters.

A = [NaN NaN NaN NaN; 0 1 0 0; 1 0 0 0; 0 0 0 0];

%
% Define the state-disturbance-loading coefficient matrix.

B = [0.5; 0; 0; 1];

%
% Define the measurement-sensitivity coefficient matrix.

C = [1 0 0 0];

%
% Define the observation-innovation coefficient matrix.

D = 0.1;

%
% Use ssm to create the state-space model. Set the initial-state mean (Mean0) to a vector of zeros and covariance matrix (Cov0) to the identity matrix, except set the mean and variance of the constant state to 1 and 0, respectively. Specify the type of initial state distributions (StateType) by noting that:
% x_{1,t} is a stationary, ARMA(2,1) process.
% x_{2,t} is the constant 1 for all periods.
% x_{3,t} is the lagged ARMA process, so it is stationary.
% x_{4,t} is a white-noise process, so it is stationary.

Mean0 = [0; 1; 0; 0];                                      
Cov0 = eye(4);
Cov0(2,2) = 0;
StateType = [0; 1; 0; 0];
Mdl = ssm(A,B,C,D,'Mean0',Mean0,'Cov0',Cov0,'StateType',StateType);

% Mdl is an ssm model. You can use dot notation to access its properties. For example, print A by entering Mdl.A.
%
% Use disp to verify the state-space model.

disp(Mdl)

% If you have a set of responses, you can pass them and Mdl to estimate to estimate the parameters.
% Copyright 2012 The MathWorks, Inc.