convergenceDFM (version 0.1.4)

run_complete_factor_analysis_robust: Complete factor-OU convergence analysis pipeline

Description

Executes the end-to-end analysis workflow: data preparation, PLS-based factor extraction, DFM estimation, Factor-OU estimation, convergence tests, and robustness checks. This is the main user-facing function.

Usage

run_complete_factor_analysis_robust(
  X_matrix,
  Y_matrix,
  TMG = NULL,
  COM_matrix = NULL,
  SPVR_matrix = NULL,
  CA = NULL,
  sector_names = NULL,
  max_comp = 3,
  dfm_lags = 1,
  ou_chains = 10,
  ou_iter = 10000,
  skip_ou = FALSE,
  run_convergence_tests = TRUE,
  path_cpi = NULL,
  path_weights = NULL,
  verbose = TRUE
)

Value

List with components:

factors

List containing PLS-extracted factors (scores_X, scores_Y) and related objects (pls_X, pls_Y, ncomp_X, ncomp_Y).

dfm

List with DFM estimation results including VAR fit, lag order, diagnostics, and optional impulse responses.

factor_ou

List with Factor-OU model estimates: beta, lambda, sigma, half_life, method used, and optional Stan fit object.

convergence_tests

List with formal convergence test results (if run_convergence_tests = TRUE).

robustness_tests

List with robustness test results (if run_robustness_tests = TRUE).

diagnostics

List with data diagnostics (multicollinearity, stationarity, structural breaks).

bayesian_cpi

List with Bayesian disaggregation results (if CPI paths provided).

metadata

List with analysis metadata (timestamp, versions, parameters).

Arguments

X_matrix

Matrix of first set of variables

Y_matrix

Matrix of second set of variables

TMG

Optional TMG matrix (default: NULL)

COM_matrix

Optional COM matrix (default: NULL)

SPVR_matrix

Optional SPVR matrix (default: NULL)

CA

Optional CA parameter (default: NULL)

sector_names

Vector of sector names (default: NULL)

max_comp

Maximum number of components (default: 3)

dfm_lags

Number of lags for DFM (default: 1)

ou_chains

Number of MCMC chains for OU estimation (default: 10)

ou_iter

Number of MCMC iterations (default: 10000)

skip_ou

Logical, skip OU estimation (default: FALSE)

run_convergence_tests

Logical, run convergence tests (default: TRUE)

path_cpi

Path to CPI data (default: NULL)

path_weights

Path to weights data (default: NULL)

verbose

Logical; print progress and diagnostic information. Default TRUE.

Details

uses column names of X_matrix. and reweighting tests). Can be NULL.

This function orchestrates the complete analysis:

1. Data validation and diagnostics

2. Bayesian CPI disaggregation (if applicable)

3. PLS-based factor extraction with optimal component selection

4. Dynamic Factor Model estimation via VAR

5. Factor Ornstein-Uhlenbeck mean-reversion model

6. Formal convergence tests (stationarity, cointegration, speed)

7. Robustness tests (permutation, reweighting, jackknife)

See Also

estimate_DFM, estimate_factor_OU, run_convergence_robustness_tests, visualize_factor_dynamics

Examples

# \donttest{
# Basic usage with simulated data
set.seed(123)
X <- matrix(rnorm(100 * 10), 100, 10)
Y <- X + matrix(rnorm(100 * 10, 0, 0.5), 100, 10)

results <- run_complete_factor_analysis_robust(
  X_matrix = X,
  Y_matrix = Y,
  max_comp = 3,
  dfm_lags = 1,
  ou_chains = 4,
  ou_iter = 2000,
  verbose = FALSE
)

# View convergence summary
summary(results$convergence_tests)

# Visualize results
visualize_factor_dynamics(
  dfm_result = results$dfm,
  ou_result = results$factor_ou,
  factors_data = results$factors
)
# }