% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/KalmanFilterSmoother.R
\name{kalmanFilterSmoother}
\alias{kalmanFilterSmoother}
\title{Univariate Representation of the Multivariate Kalman Filter and
Smoother}
\usage{
kalmanFilterSmoother(
  data,
  delay,
  no_of_factors,
  loading_matrix,
  meas_error_var_cov,
  trans_error_var_cov,
  trans_var_coeff,
  factor_lag_order,
  fcast_horizon = 0,
  decorr_errors = TRUE,
  comp_null = 1e-15,
  parallel = FALSE,
  jitter = 1e-08
)
}
\arguments{
\item{data}{Numeric (no_of_vars \eqn{\times}{x} no_of_obs) matrix of data or
zoo/xts object sampled at the same frequency.}

\item{delay}{Integer vector of variable delays.}

\item{no_of_factors}{Integer number of factors.}

\item{loading_matrix}{Numeric (no_of_vars \eqn{\times}{x} no_of_factors)
loading matrix.}

\item{meas_error_var_cov}{Numeric (no_of_factors \eqn{\times}{x}
no_of_factors) variance-covariance matrix of the measurement errors.}

\item{trans_error_var_cov}{Numeric (no_of_vars \eqn{\times}{x} no_of_vars)
variance-covariance matrix of the transition errors.}

\item{trans_var_coeff}{Either a list of length max_factor_lag_order with each
entry a numeric (no_of_factors \eqn{\times}{x} no_of_factors) VAR
coefficient matrix or a matrix of dimensions (no_of_factors x(no_of_factors
\itemize{
\item max_factor_lag_order)) holding the VAR coefficients of the factor VAR
process in each (no_of_factors \eqn{\times}{x} no_of_factors) block.
}}

\item{factor_lag_order}{Integer order of the VAR process in the state
equation.}

\item{fcast_horizon}{Integer number of additional Filter predictions into the
future.}

\item{decorr_errors}{Logical, whether or not the errors should be
decorrelated (should be \code{TRUE} if \code{meas_error_var_cov} is not diagonal).}

\item{comp_null}{Computational zero.}

\item{parallel}{Logical, whether or not to use Eigen's internal parallel
matrix operations.}

\item{jitter}{Numerical jitter for stability of internal solver algorithms.
The jitter is added to the diagonal entries of the variance-covariance matrix
of the measurement errors.}
}
\value{
An object of class \code{KFSFit} with components:
\describe{
\item{data}{Original data matrix.}
\item{smoothed_factors}{Object containing the smoothed factor estimates.
The object inherits its class from \code{data}: If \code{data} is provided as \code{zoo},
\code{smoothed_factors} will be a \code{zoo} object. If \code{data} is provided as
\code{matrix}, \code{smoothed_factors} will be a (\code{no_of_factors} \eqn{\times}{x}
\code{no_of_obs}) matrix.}
\item{smoothed_state_variance}{(\code{no_of_factors} \eqn{\times}{x}
(\code{no_of_factors * no_of_obs})) matrix, where each (\code{no_of_factors}
\eqn{\times}{x} \code{no_of_factors}) block represents the smoother uncertainty
at time point \eqn{t}{t}}
\item{factor_var_lag_order}{Integer order of the VAR process in the state
equation.}
\item{llt_success_code}{Integer indicating the status of the Cholesky
factorization: \code{0} = LLT succeeded, \code{-1} = LLT failed but LDLT succeeded,
\code{-2} = both failed and errors are treated as uncorrelated.}
}
}
\description{
Filter and smooth the latent states/factors of a linear Gaussian state-space
model, with measurement equation
\deqn{
  \bm{x}_t = \bm{\Lambda} \bm{f}_{t} + \bm{\xi}_t,\quad \bm{\xi}_t \sim \mathcal{N}(\bm{0}, \bm{\Sigma}_{\xi}),
}
and transition equation
\deqn{
  \bm{f}_t = \sum_{p=0}^P\bm{\Phi}_p \bm{f}_{t-p} + \bm{\epsilon}_t,\quad \bm{\epsilon}_t \sim \mathcal{N}(\bm{0}, \bm{\Sigma}_{f}).
}
for t = 1, \dots, T. For filtering and smoothing, the univariate
representation of the multivariate Kalman Filter and Smoother is implemented
according to \insertRef{koopman2000fast}{TwoStepSDFM}.
}
\details{
To implement the univariate representation of the Kalman Filter and Smoother,
the measurement error term has to be cross-sectionally uncorrelated. If
\code{meas_error_var_cov} is not diagonal, one should set \code{decorr_errors = TRUE} so
that the data can be decorrelated internally prior to filtering and smoothing.

When decorrelating, the function first adds \code{jitter} to the diagonal elements
of \code{meas_error_var_cov} and then tries to compute the Cholesky factor via
Eigen's standard LLT decomposition \insertCite{eigenweb}{TwoStepSDFM}. If the
initial decorrelation fails, it silently switches to Eigen's more robust,
but slower, LDLT decomposition with pivoting
\insertCite{eigenweb}{TwoStepSDFM}. If this also fails, it is likely that
\code{meas_error_var_cov} is not well-behaved. The analysis should be repeated
with a larger \code{jitter} or a more robust variance-covariance matrix
(estimator). The success of the internal Cholesky decomposition is reported
by \code{llt_success_code}.
}
\examples{
data(factor_model)
no_of_factors <- dim(factor_model$factors)[2]
factor_lag_order <- dim(factor_model$trans_var_coeff)[2] / no_of_factors
filter_fit <- kalmanFilterSmoother(data = factor_model$data, delay = factor_model$delay, 
                                   no_of_factors = no_of_factors, 
                                   loading_matrix = factor_model$loading_matrix, 
                                   meas_error_var_cov = factor_model$meas_error_var_cov, 
                                   trans_error_var_cov = factor_model$trans_error_var_cov,
                                   trans_var_coeff = factor_model$trans_var_coeff, 
                                   factor_lag_order = factor_lag_order, 
                                   fcast_horizon = 5, decorr_errors = TRUE,  
                                   comp_null = 1e-15, parallel = FALSE,  jitter = 1e-8)
print(filter_fit)
filter_plots <- plot(filter_fit)
filter_plots$`Factor Time Series Plots`

}
\references{
\insertRef{koopman2000fast}{TwoStepSDFM}

\insertRef{eigenweb}{TwoStepSDFM}
}
\author{
Domenic Franjic
}
