kalmanFilterSmoother: Univariate Representation of the Multivariate Kalman Filter...

In TwoStepSDFM: Estimate a Sparse Mixed Frequency Gaussian Factor Model Using a Two-Step Procedure

Univariate Representation of the Multivariate Kalman Filter and Smoother

Description

Filter and smooth the latent states/factors of a linear Gaussian state-space model, with measurement equation

\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

\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, ..., T. For filtering and smoothing, the univariate representation of the multivariate Kalman Filter and Smoother is implemented according to \insertRefkoopman2000fastTwoStepSDFM.

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

data	Numeric (no_of_vars \times no_of_obs) matrix of data or zoo/xts object sampled at the same frequency.
delay	Integer vector of variable delays.
no_of_factors	Integer number of factors.
loading_matrix	Numeric (no_of_vars \times no_of_factors) loading matrix.
meas_error_var_cov	Numeric (no_of_factors \times no_of_factors) variance-covariance matrix of the measurement errors.
trans_error_var_cov	Numeric (no_of_vars \times no_of_vars) variance-covariance matrix of the transition errors.
trans_var_coeff	Either a list of length max_factor_lag_order with each entry a numeric (no_of_factors \times no_of_factors) VAR coefficient matrix or a matrix of dimensions (no_of_factors x(no_of_factors max_factor_lag_order)) holding the VAR coefficients of the factor VAR process in each (no_of_factors \times no_of_factors) block.
factor_lag_order	Integer order of the VAR process in the state equation.
fcast_horizon	Integer number of additional Filter predictions into the future.
decorr_errors	Logical, whether or not the errors should be decorrelated (should be TRUE if meas_error_var_cov is not diagonal).
comp_null	Computational zero.
parallel	Logical, whether or not to use Eigen's internal parallel matrix operations.
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.

Details

To implement the univariate representation of the Kalman Filter and Smoother, the measurement error term has to be cross-sectionally uncorrelated. If meas_error_var_cov is not diagonal, one should set decorr_errors = TRUE so that the data can be decorrelated internally prior to filtering and smoothing.

When decorrelating, the function first adds jitter to the diagonal elements of meas_error_var_cov and then tries to compute the Cholesky factor via Eigen's standard LLT decomposition \insertCiteeigenwebTwoStepSDFM. If the initial decorrelation fails, it silently switches to Eigen's more robust, but slower, LDLT decomposition with pivoting \insertCiteeigenwebTwoStepSDFM. If this also fails, it is likely that meas_error_var_cov is not well-behaved. The analysis should be repeated with a larger jitter or a more robust variance-covariance matrix (estimator). The success of the internal Cholesky decomposition is reported by llt_success_code.

Value

An object of class KFSFit with components:

data

Original data matrix.

smoothed_factors

Object containing the smoothed factor estimates. The object inherits its class from data: If data is provided as zoo, smoothed_factors will be a zoo object. If data is provided as matrix, smoothed_factors will be a (no_of_factors \times no_of_obs) matrix.

smoothed_state_variance

(no_of_factors \times (no_of_factors * no_of_obs)) matrix, where each (no_of_factors \times no_of_factors) block represents the smoother uncertainty at time point t

factor_var_lag_order

Integer order of the VAR process in the state equation.

llt_success_code

Integer indicating the status of the Cholesky factorization: 0 = LLT succeeded, -1 = LLT failed but LDLT succeeded, -2 = both failed and errors are treated as uncorrelated.

Author(s)

Domenic Franjic

References

\insertRef

koopman2000fastTwoStepSDFM

\insertRef

eigenwebTwoStepSDFM

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`

TwoStepSDFM documentation built on May 19, 2026, 9:07 a.m.