mloglik-td: Time Domain Log-Likelihood Function and Derivatives
In stsm: Structural Time Series Models

Description Usage Arguments Details Value References See Also Examples

This function evaluates the negative of the time domain log-likelihood function of a linear Gaussian state space model by means of the Kalman filter.

mloglik.td(x, model, 
  KF.version = eval(formals(KFKSDS::KalmanFilter)$KF.version),
  KF.args = list(), check.KF.args = TRUE,
  barrier = list(type = c("1", "2"), mu = 0), inf = 99999)

KFconvar(model, P0cov = FALSE, barrier = list(type = "1", mu = 0), debug = TRUE)

mloglik.td.deriv(model, gradient = TRUE, infomat = TRUE,
  KF.args = list(), version = c("1", "2"), kfres = NULL, 
  convergence = c(0.001, length(model@y)))

mloglik.td.grad(x, model, KF.version, KF.args = list(), 
  convergence = c(0.001, length(model@y)), 
  check.KF.args, barrier, inf)

`x`	a numeric vector containing the parameters of the model. This is an auxiliary argument so that this function can be used as input to `optim`.

model

an object of class stsm.

KF.version

character indicating the implementation of the Kalman filter to be used.

KF.args

a list of parameters to be passed to the function chosen to run the Kalman filter.

check.KF.args

logical. If TRUE, the elements passed in argument KF.args are checked for consistency with KF.version.

barrier

a list defining a barrier term to penalize parameter values close to the bounds m@lower and m@upper.

inf

a numeric indicating the value to be returned if the value of the log-likelihood function happens to be NA or non-finite.

P0cov

logical. If TRUE, values outside the diagonal of the covariance matrix of the initial state vector are set equal to the values in the diagonal, as done in StructTS

debug

logical. If TRUE, the correctness of the result is double-checked.

gradient

logical. If TRUE, first order derivatives of the negative of the spectral log-likelihood function are returned.

infomat

logical. If TRUE, the information matrix of the spectral log-likelihood are returned.

version

a character indicating whether implementation "2" or "2" (the default) should be used.They yield the same result but are kept for debugging and comparison of timings. This argument may be removed in future versions.

kfres

optional list containing the elements involved in the Kalman filter as returned by KF.deriv.

convergence

a numeric vector containing two parameters to control the convergence of the Kalman filter. See KF.

The general univariate linear Gaussian state space model is defined as follows:

y[t] = Za[t] + e[t], e[t] \sim N(0, H)

a[t+1] = Ta[t] + Rw[t], w[t] \sim N(0, V)

for t=1,…,n and a[1] \sim N(a0, P0). Z is a matrix of dimension 1xm; H is 1x1; T is mxm; R is mxr; V is rxr; a0 is mx1 and P0 is mxm, where r is the number of variance parameters in the state vector.

The Kalman filtering recursions for the model above are:

Prediction

a[t] = T a[t-1]

P[t] = T P[t-1] T' + R V R'

v[t] = y[t] - Z a[t]

F[t] = Z P[t] Z' + H

Updating

K[t] = P[t] Z' F[t]^{-1}

a[t] = a[t] + K[t] v[t]

P[t] = P[t] - K[t] Z P[t]'

for t=2,…,n, starting with a[1] and P[1] equal to a0 and P0. v[t] is the prediction error at observation in time t and F[t] is the variance of v[t].

The log-likelihood of the model for a given set of parameter values is:

logLik = -0.5 log(2π) - 0.5 ∑_{t=1}^n { log F[t] + v[t]^2 / F[t] }

For details about the options than can be passed through argument KF.args see the documentation of the same argument of function KalmanFilter in package KFKSDS. For mloglik.td.deriv, the only element that is used if provided in KF.args is P0cov (a logical indicating whether the covariance matrix of the initial state vector diagonal or not).

The argument x is an auxiliary vector that is necessary in some contexts. For example, the input to function optim must contain as first argument the vector of parameters where optimization is performed. If it is not required or is redundant information contained in model@pars it can be set to NULL.

For further information about the barrier term see Bounds on parameters and barrier term in the details section in maxlik.fd.scoring.

KFconvar evaluates the concentrated likelihood function. The likelihood is concentrated with respect to the parameter defined in model@cpar. The optimal value of the parameter that is concentrated out of the likelihood is:

s2 = (1/n) ∑_{t=1}^n v[t]/ F[t]

and the concentrated likelihood function is given by:

clogLik = (n/2) log(2π + 1) + 0.5 ∑_{t=1}^n log(f[t]) + (n/2) log(s2).

The gradient and the information matrix are calculated upon their corresponding analytical expressions.

Arguments KF.version, check.KF.args, barrier and inf are not used by mloglik.td.grad but they are needed in maxlik.td.optim, where this function is passed as the gradient to be used by optim including the arguments inf and barrier.

The minus log-likelihood function evaluated at the parameter values defined in the input model model or at x if this argument is not NULL. If the value happens to be NA or non-finite the value of argument inf is returned. This function is suited to be passed as the objective function to optim.

KFconvar returns a list containing the element mll, the negative of the concentrated minus log-likelihood function and the element cpar, the optimal value of the parameter that is concentrated out of the likelihood.

mloglik.td.deriv returns a list containing a vector of the first order derivatives of the negative of the time domain likelihood function and a matrix for the information matrix. They are set to NULL if any of them are not requested.

mloglik.td.grad returns a numeric vector containing the gradient. This function is suited to be passed as the gradient function to optim.

Durbin, J. and Koopman, S. J. (2001). Time Series Analysis by State Space Methods. Oxford University Press.

Harvey, A. C. (1989). Forecasting, Structural Time Series Models and the Kalman Filter. Cambridge University Press.

barrier.eval, logLik, maxlik.td, stsm, KalmanFilter, KalmanLike.

# local level plus seasonal model for a sample simulated series
data("llmseas")
m <- stsm.model(model = "llm+seas", y = llmseas,
  pars = c("var1" = 300, "var2" = 10, "var3" = 100))
# evaluate the time domain likelihood function using 
# excluding the contributions of the first 8 observations
mloglik.td(model = m, KF.version = "KFKSDS", KF.args = list(t0 = 9))

# compare analytical and numerical derivatives
# identical gradient up to a tolerance
a <- mloglik.td.deriv(m, infomat = TRUE)
g <- numDeriv::grad(func = mloglik.td, x = m@pars, 
  model = m, KF.version = "KFKSDS")
h <- numDeriv::hessian(func = mloglik.td, x = m@pars, 
  model = m, KF.version = "KFKSDS")
all.equal(a$gradient, g, check.attributes = FALSE)