Welcome State space notation Functions > ieks
Last update Jul 10, 2004

DESCRIPTION:

Iterated extended Kalman filter and smoother for a state space model for exponential family data with linear Gaussian latent process. The model is
Observation equation:
p(yt | ht)
=
exp{ytTht - b(ht) - c(yt)},
Link function:
g{b(ht)}
=
lt,
Signal:
lt
=
FtTqt,
System equation:
qt
=
Gtqt-1 + wt,
 wt
~
Np(0,Wt),
Initial prior:
q0
~
Np(m0,C0).

USAGE:

      ieks(ssm, m.start = NA, max.iter = 50, eps = 0.0001)

REQUIRED ARGUMENTS:

ssm:
An object of class ssm. The following attributes must be specified for all distributions
Ft:
Function returning a p × 1 design vector for binomial, Gaussian and Poisson data. If the data is multinomial the function must return a p × (k-1) design matrix, where k is the number of categories.
Gt:
Function returning a p × p evolution transfer matrix.
Wt:
Function returning a p × p evolution variance matrix.
m0:
p × 1 vector (prior mean).
C0:
p × p matrix (prior variance).
fam:
The distribution of the observations. Choices are binomial, Poisson, Gaussian, and multinomial.
link:
The link function between the mean and the signal. The possible choices are given in the table below.

OPTIONAL ARGUMENTS:

The following attributes of the ssm object might be needed:
Yt:
A 1 × n vector of observations in the Gaussian, binomial and Poisson case. In the case of multinomial data with k categories, Yt must be an n × k matrix containing the multinomial observations arranged row-wise. If data is not supplied (i.e. Yt=NA) a time series will be simulated using simulate.ssm before the iterated extended Kalman filter and smoother is applied.
nt:
This must be specified for binomial and multinomial data. In that case it should be a 1 × n vector containing the number of trials at each time-point.
Vt:
Function returning the observation variance (only needed for Gaussian observations).
Xt:
Matrix containing the covariates needed in the system matrices Ft, Gt, Vt and/or Wt. The matrix Xt must have n rows, such that row t contains the covariates needed for generating the system matrices at time t.
psi:
Parameter vector. Must be supplied if it is needed in the calculation of any of the system matrices.
m.start:
Starting values for the Taylor approximation. Default is m.start = NA implying that the Taylor expansion points are determined sequentially based on the one-step forecast mean of the state.
The following arguments are optional:
max.iter:
Maximum number of iterations. Default is 50.
eps:
Criteria for determining convergence. Default values is eps=0.0001. The criteria for convergence is
max{abs(\fracsmoothed$m.tilde-m.startm.start)} < eps

VALUE:

Returns an object of class ssm with the same attributes as the object in the call and the following additional attributes:
filtered:
A list containing the results obtained by the final pass of the extended Kalman filter. The elements of the list are
mt:
Posterior means mt given the observations up to and including time t. These are arranged row-wise in a matrix.
Ct:
Posterior variances Ct given the observations up to and including time t. These are arranged in a 3-dimensional array such that Ct is placed in filtered$Ct[,,t].
llh:
Log-likelihood of of the approximating Gaussian state space model.
Rt:
Prior variances for the states arranged in 3-dimensional array such that Rt is placed in filtered$Rt[,,t]. The reason for returning these is that they are needed in the Kalman smoother.
smoothed:
A list containing the results obtained in the final pass of the Kalman smoother on the approximating model. The elements in the list are
m.tilde:
Posterior means ~mt given all the observations. These are arranged row-wise in a matrix.
C.tilde:
Posterior variances ~Ct given all observations. These are arranged in a 3-dimensional array such that ~Ct is placed in filtered$Ct[,,t].

SIDE EFFECTS:

If the value of the attribute Yt of the ssm object is NA a time series is generated before the iterated extended Kalman filter and smoother is applied. This is performed by the function simulate.ssm and causes the creation of the dataset .Random.seed if it does not already exist, otherwise its value is updated. If a time series is simulated the generated states ( theta) and the signals (lambda) will be stored as a list in the attribute simulated of the returned ssm object.

DETAILS:

The appropriate filter and smoother are applied iteratively approximating the exponential family observation density with a Gaussian density based on a Taylor expansion around the values supplied in the attribute m.start of the ssm object. If m.start is not supplied, the Taylor expansion in the first pass of the filter will based on the one-step forecast mean of the observation. In the subsequent steps the Taylor expansion points are based on the output from the Kalman smoother.
The following families and links are supported:
Binomial       identity, logit, probit
Gaussian       identity
Poisson        identity, log
Multinomial       canonical, pom.

Please refer to Klein (2003) for details concerning the approximations used in the specific cases.

REFERENCES:

Durbin & Koopman, (2002), Time Series Analysis by State Space Models, Oxford Statistical Science Series.
Fahrmeir & Tutz, (1994), Multivariate Statistical Modelling Based on Generalized Linear Models, Springer Series in Statistics.
Klein, (2003), State Space Models for Exponential Family Data, Ph.D. Thesis, Department of Statistics, University of Southern Denmark.

EXAMPLES:

# Specify a state space model
ss <- ssm(Ft = function(i,x,phi) 
                       {c(1,1)},
          Gt = function(i,x,phi)  
                       {matrix(c(0.8,0,0,0),
                               ncol=2,byrow=T)},
          Wt = function(i,x,phi)  
                       {diag(2)/2},
          m0 = c(0,0),
          C0 = diag(10,2),
          nt = rep(10,50),
          fam = "binomial",
          link = "logit")

# Simulate observations
ss <- simulate.ssm(ss)

# Apply the iterated Kalman filter and smooher
ss <- ieks(ss)