MARSSkf | R Documentation |
Provides Kalman filter and smoother output for MARSS models with (or without) time-varying parameters. MARSSkf()
is a small helper function to select which Kalman filter/smoother function to use based on the value in MLEobj$fun.kf
. The choices are MARSSkfas()
which uses the filtering and smoothing algorithms in the KFAS package based on algorithms in Koopman and Durbin (2001-2003), and MARSSkfss()
which uses the algorithms in Shumway and Stoffer. The default function is MARSSkfas()
which is faster and generally more stable (fewer matrix inversions), but there are some cases where MARSSkfss()
might be more stable and it returns a variety of diagnostics that MARSSkfas()
does not.
MARSSkf(MLEobj, only.logLik = FALSE, return.lag.one = TRUE, return.kfas.model = FALSE,
newdata = NULL, smoother = TRUE)
MARSSkfss(MLEobj, smoother=TRUE)
MARSSkfas(MLEobj, only.logLik=FALSE, return.lag.one=TRUE, return.kfas.model=FALSE)
MLEobj |
A |
smoother |
Used by |
only.logLik |
Used by |
return.lag.one |
Used by |
return.kfas.model |
Used by |
newdata |
A new matrix of data to use in place of the data used to fit the model (in the |
For state-space models, the Kalman filter and smoother provide optimal (minimum mean square error) estimates of the hidden states. The Kalman filter is a forward recursive algorithm which computes estimates of the states \mathbf{x}_t
conditioned on the data up to time t
(xtt
). The Kalman smoother is a backward recursive algorithm which starts at time T
and works backwards to t = 1
to provide estimates of the states conditioned on all data (xtT
). The data may contain missing values (NAs). All parameters may be time varying.
The initial state is either an estimated parameter or treated as a prior (with mean and variance). The initial state can be specified at t=0
or t=1
. The EM algorithm in the MARSS package (MARSSkem()
) provides both Shumway and Stoffer's derivation that uses t=0
and Ghahramani et al algorithm which uses t=1
. The MLEobj$model$tinitx
argument specifies whether the initial states (specified with x0
and V0
in the model
list) is at t=0
(tinitx=0
) or t=1
(tinitx=1
). If MLEobj$model$tinitx=0
, x0
is defined as \textrm{E}[\mathbf{X}_0|\mathbf{y}_0]
and V0
is defined as \textrm{E}[\mathbf{X}_0\mathbf{X}_0|\mathbf{y}_0]
which appear in the Kalman filter at t=1
(first set of equations). If MLEobj$model$tinitx=1
, x0
is defined as \textrm{E}[\mathbf{X}_1|\mathbf{y}_0]
and V0
is defined as \textrm{E}[\mathbf{X}_1\mathbf{X}_1|\mathbf{y}_0]
which appear in the Kalman filter at t=1
(and the filter starts at t=1 at the 3rd and 4th equations in the Kalman filter recursion). Thus if MLEobj$model$tinitx=1
, x0=xtt1[,1]
and V0=Vtt1[,,1]
in the Kalman filter output while if MLEobj$model$tinitx=0
, the initial condition will not be in the filter output since time starts at 1 not 0 in the output.
MARSSkfss()
is a native R implementation based on the Kalman filter and smoother equation as shown in Shumway and Stoffer (sec 6.2, 2006). The equations have been altered to allow the initial state distribution to be to be specified at t=0
or t=1
(data starts at t=1
) per per Ghahramani and Hinton (1996). In addition, the filter and smoother equations have been altered to allow partially deterministic models (some or all elements of the \mathbf{Q}
diagonals equal to 0), partially perfect observation models (some or all elements of the \mathbf{R}
diagonal equal to 0) and fixed (albeit unknown) initial states (some or all elements of the \mathbf{V0}
diagonal equal to 0) (per Holmes 2012). The code includes numerous checks to alert the user if matrices are becoming ill-conditioned and the algorithm unstable.
MARSSkfas()
uses the (Fortran-based) Kalman filter and smoother function (KFS()
) in the KFAS package (Helske 2012) based on the algorithms of Koopman and Durbin (2000, 2001, 2003). The Koopman and Durbin algorithm is faster and more stable since it avoids matrix inverses. Exact diffuse priors are also allowed in the KFAS Kalman filter function. The standard output from the KFAS functions do not include the lag-one covariance smoother needed for the EM algorithm. MARSSkfas
computes the smoothed lag-one covariance using the Kalman filter applied to a stacked MARSS model as described on page 321 in Shumway and Stoffer (2000). Also the KFAS model specification only has the initial state at t=1
(as \mathbf{X}_1
conditioned on \mathbf{y}_0
, which is missing). When the initial state is specified at t=0
(as \mathbf{X}_0
conditioned on \mathbf{y}_0
), MARSSkfas()
computes the required \textrm{E}[\mathbf{X}_1|\mathbf{y}_0
and \textrm{var}[\mathbf{X}_1|\mathbf{y}_0
using the Kalman filter equations per Ghahramani and Hinton (1996).
The likelihood returned for both functions is the exact likelihood when there are missing values rather than the approximate likelihood sometimes presented in texts for the missing values case. The functions return the same filter, smoother and log-likelihood values. The differences are that MARSSkfas()
is faster (and more stable) but MARSSkfss()
has many internal checks and error messages which can help debug numerical problems (but slow things down). Also MARSSkfss()
returns some output specific to the traditional filter algorithm (J
and Kt
).
A list with the following components. m
is the number of state processes and n
is the number of observation time series. "V" elements are called "P" in Shumway and Stoffer (2006, eqn 6.17 with s=T). The output is referenced against equations in Shumway and Stoffer (2006) denoted S&S; the Kalman filter and smoother implemented in MARSS is for a more general MARSS model than that shown in S&S but the output has the same meaning. In the expectations below, the parameters are left off; \textrm{E}[\mathbf{X} | \mathbf{y}_1^t]
is really \textrm{E}[\mathbf{X} | \Theta, \mathbf{Y}_1^t=\mathbf{y}_1^t]
where \Theta
is the parameter list. \mathbf{y}_1^t
denotes the data from t=1
to t=t
.
The notation for the conditional expectations is \mathbf{x}_t^t
= \textrm{E}[\mathbf{X} | \mathbf{y}_1^t]
, \mathbf{x}_t^{t-1}
= \textrm{E}[\mathbf{X} | \mathbf{y}_1^{t-1}]
and \mathbf{x}_t^T
= \textrm{E}[\mathbf{X} | \mathbf{y}_1^T]
. The conditional variances and covariances use similar notation. Note that in the Holmes (2012), the EM Derivation, \mathbf{x}_t^T
and \mathbf{V}_t^T
are given special symbols because they appear repeatedly: \tilde{\mathbf{x}}_t
and \tilde{\mathbf{V}}_t
but here the more general notation is used.
xtT |
|
VtT |
|
Vtt1T |
|
x0T |
Initial smoothed state estimate |
x01T |
Smoothed state estimate |
x00T |
Smoothed state estimate |
V0T |
Initial smoothed state covariance matrix |
V10T |
Smoothed state covariance matrix |
V00T |
Smoothed state covariance matrix |
J |
(m x m x T) Kalman smoother output. Only for |
J0 |
J at the initial time (t=0 or t=1) (m x m x T). Kalman smoother output. Only for |
xtt |
State first moment conditioned on |
xtt1 |
State first moment conditioned on |
Vtt |
State variance conditioned on |
Vtt1 |
State variance conditioned on |
Kt |
Kalman gain (m x m x T). Kalman filter output (ref S&S eqn 6.23). Only for |
Innov |
Innovations |
Sigma |
Innovations covariance matrix. Kalman filter output. Only returned with |
logLik |
Log-likelihood logL(y(1:T) | Theta) (ref S&S eqn 6.62) |
kfas.model |
The model in KFAS model form (class |
errors |
Any error messages. |
Eli Holmes, NOAA, Seattle, USA.
A. C. Harvey (1989). Chapter 5, Forecasting, structural time series models and the Kalman filter. Cambridge University Press.
R. H. Shumway and D. S. Stoffer (2006). Time series analysis and its applications: with R examples. Second Edition. Springer-Verlag, New York.
Ghahramani, Z. and Hinton, G.E. (1996) Parameter estimation for linear dynamical systems. University of Toronto Technical Report CRG-TR-96-2.
Holmes, E. E. (2012). Derivation of the EM algorithm for constrained and unconstrained multivariate autoregressive
state-space (MARSS) models. Technical Report. arXiv:1302.3919 [stat.ME] RShowDoc("EMDerivation",package="MARSS")
to open a copy.
Jouni Helske (2012). KFAS: Kalman filter and smoother for exponential family state space models. https://CRAN.R-project.org/package=KFAS
Koopman, S.J. and Durbin J. (2000). Fast filtering and smoothing for non-stationary time series models, Journal of American Statistical Association, 92, 1630-38.
Koopman, S.J. and Durbin J. (2001). Time series analysis by state space methods. Oxford: Oxford University Press.
Koopman, S.J. and Durbin J. (2003). Filtering and smoothing of state vector for diffuse state space models, Journal of Time Series Analysis, Vol. 24, No. 1.
The MARSS User Guide: Holmes, E. E., E. J. Ward, and M. D. Scheuerell (2012) Analysis of multivariate time-series using the MARSS package. NOAA Fisheries, Northwest Fisheries Science Center, 2725 Montlake Blvd E., Seattle, WA 98112 Type RShowDoc("UserGuide",package="MARSS")
to open a copy.
MARSS()
, marssMODEL
, MARSSkem()
, KFAS()
dat <- t(harborSeal)
dat <- dat[2:nrow(dat), ]
# you can use MARSS to construct a marssMLE object
# MARSS calls MARSSinits to construct default initial values
# with fit = FALSE, the $par element of the marssMLE object will be NULL
fit <- MARSS(dat, fit = FALSE)
# MARSSkf needs a marssMLE object with the par element set
fit$par <- fit$start
# Compute the kf output at the params used for the inits
kfList <- MARSSkf(fit)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.