DESCRIPTION:
Iterated extended Kalman filter and smoother for a state space model
for exponential family data with linear Gaussian latent process. The
model is

  
exp{y_{t}^{T}h_{t}  b(h_{t})  c(y_{t})}, 
   
      
      
      
      



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 × (k1) 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 rowwise. 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 timepoint.
 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 onestep
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.tildem.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 m_{t} given the observations up to
and including time t. These are arranged rowwise in a matrix.
 Ct:
 Posterior variances C_{t} given the
observations up to and including time t. These are arranged in a
3dimensional array such that C_{t} is placed in filtered$Ct[,,t].
 llh:
 Loglikelihood of of the approximating Gaussian
state space model.
 Rt:
 Prior variances for the states arranged in
3dimensional array such that R_{t} 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 ~m_{t} given all the
observations. These are arranged rowwise in a matrix.
 C.tilde:
 Posterior variances ~C_{t} given all
observations. These are arranged in a 3dimensional array such that
~C_{t} 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 onestep 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)
