convergenceDFM

convergenceDFM is an R package for convergence analysis in macro-financial panels, combining Dynamic Factor Models (DFM) with mean-reverting Ornstein-Uhlenbeck (OU) processes.

Main Features

• Dynamic Factor Models (DFM): Static and approximate estimation for large panels with VAR/VECM stability checks, Portmanteau tests, and out-of-sample $R^2$.

• Cointegration analysis: Implementation of Johansen's test.

• Ornstein-Uhlenbeck processes: Convergence and half-life estimation based on OU processes.

• Robust inference: HC/HAC sandwich-type estimators via the 'sandwich' package.

• Factor preselection: Methods based on Partial Least Squares (PLS).

• Visualization: Publication-ready graphics.

• Robustness tests: Complete suite of diagnostics and validation.

Installation

Status: convergenceDFM is not yet on CRAN. Install the development version from GitHub.

Development version (GitHub)

# install.packages("remotes")
remotes::install_github("IsadoreNabi/convergenceDFM")

Optional dependency: cmdstanr

For advanced Bayesian features (optional), install cmdstanr:

install.packages("cmdstanr", 
                 repos = c("https://stan-dev.r-universe.dev", 
                          getOption("repos")))

Note: cmdstanr is not on CRAN and must be installed from the Stan repository. The main functionalities of the package do not require cmdstanr.

Basic Usage

The end-to-end pipeline is run_complete_factor_analysis_robust(). It performs data diagnostics, PLS factor extraction, DFM (VAR) estimation, factor-OU/AR(1) estimation, convergence tests and robustness checks.

library(convergenceDFM)

set.seed(123)
X <- matrix(rnorm(120 * 8), 120, 8)          # e.g. labour-value price indices
Y <- X + matrix(rnorm(120 * 8, 0, 0.5), 120, 8)  # e.g. market price indices

res <- run_complete_factor_analysis_robust(
  X_matrix  = X,
  Y_matrix  = Y,
  max_comp  = 3,
  dfm_lags  = 1,
  skip_ou   = TRUE,   # set FALSE to run the Bayesian factor-OU model (needs Stan)
  verbose   = FALSE
)

# Lower-level building blocks:
data_clean <- diagnose_data(X, Y, verbose = FALSE)
sel        <- select_optimal_components_safe(scale(X), scale(Y), max_comp = 3,
                                             verbose = FALSE)
dfm        <- estimate_DFM(res$factors, verbose = FALSE)
ou         <- estimate_factor_OU(res$factors, verbose = FALSE)  # Stan or fallback

# Coupling significance (corrected time-shift null):
null <- run_rotation_null_on_results(res, B = 500, seed = 1)

The exported entry points are run_complete_factor_analysis_robust(), estimate_DFM(), estimate_factor_OU(), run_convergence_robustness_tests(), rotation_null_test() / run_rotation_null_on_results(), deltaR2_ou(), rescue_short_run_channel() and the visualization helpers.

For more examples, see the vignettes:

browseVignettes("convergenceDFM")

Package Structure

convergenceDFM/
├── R/                  # Source code
├── inst/extdata/       # Example data shipped with the package
├── man/                # Documentation (auto-generated by roxygen2)
├── tests/              # Tests with testthat (edition 3)
├── vignettes/          # Vignettes and tutorials
├── DESCRIPTION         # Package metadata (license: GPL-3)
├── NAMESPACE           # Package namespace (auto-generated)
├── NEWS.md             # Changelog
└── README.md           # This file

Development

• Documentation: Generated with roxygen2.

• Tests: Complete suite with testthat.

References

The package implements methods from:

• Forni, M., Hallin, M., Lippi, M., & Reichlin, L. (2000). "The Generalized Dynamic-Factor Model: Identification and Estimation." Review of Economics and Statistics, 82(4), 540-554.

• Stock, J. H., & Watson, M. W. (2002). "Forecasting Using Principal Components From a Large Number of Predictors." Journal of the American Statistical Association, 97(460), 1167-1179.

• Johansen, S. (1988). "Statistical analysis of cointegration vectors." Journal of Economic Dynamics and Control, 12(2-3), 231-254.

• Uhlenbeck, G. E., & Ornstein, L. S. (1930). "On the Theory of the Brownian Motion." Physical Review, 36(5), 823.

• Vasicek, O. (1977). "An equilibrium characterization of the term structure." Journal of Financial Economics, 5(2), 177-188.

• Zeileis, A. (2004). "Econometric Computing with HC and HAC Covariance Matrix Estimators." Journal of Statistical Software, 11(10), 1-17.

• Mevik, B.-H., & Wehrens, R. (2007). "The pls Package: Principal Component and Partial Least Squares Regression in R." Journal of Statistical Software, 18(2), 1-23.

License

This package is free and open source software, licensed under GPL-3.

Author

José Mauricio Gómez Julián
Email: isadorenabi@pm.me