fkf {FKF} | R Documentation |
This function allows for fast and flexible Kalman filtering. The
state-space parameters are allowed to be time-varying and intercepts
are supported in both, the transition equation and the measurement
equation. fkf
wraps the C
-function FKF
which
fully relies on linear algebra subroutines contained in BLAS and
LAPACK.
fkf(a0, P0, dt, ct, Tt, Zt, HHt, GGt, yt, check.input = TRUE)
a0 |
A vector giving the initial value/estimation of the state variable. |
P0 |
A matrix giving the variance of a0 . |
dt |
A matrix giving the intercept of the transition
equation (see Details). |
ct |
A matrix giving the intercept of the measurement
equation (see Details). |
Tt |
An array giving the factor of the transition
equation (see Details). |
Zt |
An array giving the factor of the measurement
equation (see Details). |
HHt |
An array giving the variance of the innovations of
the transition equation (see Details). |
GGt |
An array giving the variance of the disturbances of
the measurement equation (see Details). |
yt |
A matrix containing the observations. yt must
not contain “NA”-values (see Details). |
check.input |
A logical stating whether the input shall be
checked for consistency (“storage.mode”, “class”,
dimensionality, and “NA's”) (see Details). |
The filter:
The state space model is represented by the transition equation and the measurement equation. Let m be the dimension of the state variable, d be the dimension of the observations, and n the number of observations. The transition equation and the measurement equation are given by
alpha(t + 1) = d(t) + T(t) alpha(t) + H(t) eta(t)
y(t) = c(t) + Z(t) alpha(t) + G(t) epsilon(t),
where eta(t) and epsilon(t) are iid N(0, I(m)) and iid N(0, I(d)), respectively, and alpha(t) denotes the state variable. The parameters admit the following dimensions:
a[t] in R^m | d[t] in R^m | eta[t] in R^m |
d[t] in R^(m * m) | d[t] in R^(m * m) | |
y[t] in R^d | c[t] in R^d | epsilon[t] in R^d. |
Z[t] in R^(d * m) | G[t] in R^(d * d) |
Note that fkf
takes as input HHt
and GGt
which
corresponds to H[t] %*% t(H[t]) and G[t] %*% t(G[t]).
Parameters:
The parameters can either be constant or deterministic time-varying. Assume the number of observations is n (i.e. y = y[,1:n]). Then, the parameters admit the following classes and dimensions:
dt | either a m * n (time-varying) or a m * 1 (constant) matrix. |
Tt | either a m * m * n or a m * m * 1 array. |
HHt | either a m * m * n or a m * m * 1 array. |
| either a d * n or a d * 1 matrix. |
Zt | either a d * d * n or a d * d * 1 array. |
GGt | either a d * d * n or a d * d * 1 array. |
yt | a d * n matrix. |
If check.input
is TRUE
each argument will be checked for
correctness of the dimensionality, storage mode, and class.
check.input
should always be TRUE
unless the performance
becomes crucial and correctness of the arguments concerning
dimensions, class, storage.mode and absence of 'NA's is ensured.
Note:
The class of the arguments if of importance. For instance, to check
whether a parameter is constant the dim
attribute is
accessed. If, e.g., Zt
is a constant, it could be a d * d-matrix. But the third dimension
(i.e. dim(Zt)[3]
) is needed to check for constancy. This
requires Zt
to be an d * d *
1-array.
BLAS and LAPACK routines used:
The R function fkf
basically wraps the C
-function
FKF
, which entirely relies on linear algebra subroutines
provided by BLAS and LAPACK. The following functions are used:
BLAS: | dcopy , dgemm , daxpy . |
LAPACK: | dpotri , dpotrf . |
FKF
is called through the .Call
interface. Internally,
FKF
extracts the dimensions, allocates memory, and initializes
the R-objects to be returned. FKF
subsequently calls
cfkf
which performs the Kalman filtering.
The only critical part is to compute the inverse of F[,,t]
and the determinant of F[,,t]. If the inverse can not be
computed, the filter stops and returns the corresponding message in
status
(see Value). If the computation of the
determinant fails, the filter will continue, but the log-likelihood in
logLik
will be “NA”.
The inverse is computed in
two steps: First, the Cholesky factorization of F[,,t] is
calculated by dpotrf
. Second, dpotri
calculates the
inverse based on the output of dpotrf
.
The determinant of F[,,t] is computed using again the
Cholesky decomposition.
An S3-object of class “fkf”, which is a list with the following
elements:
att | A m * n-matrix containing the filtered state variables, i.e. att[,t] = E(alpha[t] | y[,t]). |
at | A m * (n + 1)-matrix containing the predicted state variables, i.e. at[,t] = E(alpha[t] | y[,t - 1]). |
Ptt | A m * m * n-array containing the variance of att , i.e. Ptt[,,t] = var(alpha[t] | y[,t]). |
Pt | A m * m * (n + 1)-array containing the variances of at , i.e. Pt[,,t] = var(alpha[t] | y[,t - 1]). |
vt | A d * n-matrix of the prediction errors given by vt[,t] = yt[,t] - ct[,t] - Zt[,,t] %*% at[,t]. |
Ft | A d * d * n-array which contains the variances of vt , i.e. Ft[,,t] = var(v[,t]). |
Kt | A m times d times n-array containing the “Kalman gain”. |
logLik | The log-likelihood. |
status | A vector which contains the status of LAPACK's dpotri and dpotrf . (0, 0) means sucessful exit. |
sys.time | The time elapsed as an object of class “proc_time”. |
at
and Pt
is filled with the
function arguments a0
and P0
, and the last, i.e. the (n +
1)-th, element of at
and Pt
contains the predictions
(at[,n + 1] =
E(alpha[n + 1] | y[,n]) and Pt[,,n + 1] = var(alpha[n + 1] | y[,n]).
David Luethi, Philipp Erb
Harvey, Andrew C. (1990) Forecasting, Structural Time Series Models and the Kalman Filter. Cambridge University Press.
Hamilton, James D. (1994). Time Series Analysis. Princeton University Press.
Zivot, E. and Wang, J. (2005). Modeling Financial Time Series with S-PLUS. Springer-Verlag, New York.
plot
to visualize and analyze
fkf
-objects,
function dlmFilter from package dlm
, and function
kfilter from package sspir
.
## This example shows how to fit an AR(2) model using the Kalman filter. n <- 200 ## Set the AR parameters ar1 <- -0.24 ar2 <- 0.6 sigma <- .4 ## Sample from an AR(2) process a <- arima.sim(model = list(ar = c(ar1, ar2)), n = n, innov = rnorm(n) * sigma) ## Create a state space representation out of the three AR parameters ar2.to.state.space <- function(ar1, ar2, sigma){ Tt <- matrix(c(ar1, 1, ar2, 0), ncol = 2) Zt <- matrix(c(1, 0), ncol = 2) ct <- matrix(0.0) dt <- matrix(0.0, nrow = 2) GGt <- matrix(0.0) HHt <- matrix(c(sigma^2, 0, 0, 0), ncol = 2) a0 <- as.numeric(c(0, 0)) P0 <- matrix(c(100,0,0,100), ncol = 2) return(list(a0 = a0, P0 = P0, ct = ct, dt = dt, Zt = Zt, Tt = Tt, GGt = GGt, HHt = HHt)) } ## The objective function passed to 'optim' objective <- function(theta, yt) { sp <- ar2.to.state.space(theta["ar1"], theta["ar2"], theta["sigma"]) ans <- fkf(a0 = sp$a0, P0 = sp$P0, dt = sp$dt, ct = sp$ct, Tt = sp$Tt, Zt = sp$Zt, HHt = sp$HHt, GGt = sp$GGt, yt = yt, check.input = FALSE) return(-ans$logLik) } theta <- c(ar1 = 0, ar2 = 0, sigma = 1) fit <- optim(theta, objective, yt = rbind(a)) fit ## Filter the series with estimated parameter values sp <- ar2.to.state.space(fit$par["ar1"], fit$par["ar2"], fit$par["sigma"]) ans <- fkf(a0 = sp$a0, P0 = sp$P0, dt = sp$dt, ct = sp$ct, Tt = sp$Tt, Zt = sp$Zt, HHt = sp$HHt, GGt = sp$GGt, yt = rbind(a)) ## Compare the prediction with the realization plot(ans, at.idx=1, att.idx = NA, CI = NA) lines(a, lty = "dotted") ## Compare the filtered series with the realization plot(ans, at.idx=NA, att.idx = 1, CI = NA) lines(a, lty = "dotted") ## Check whether the residuals are Gaussian plot(ans, type = "resid.qq") ## Check for linear serial dependence through 'acf' plot(ans, type = "acf")