crossVal: Cross-validate SDFM Hyper-Parameters
In TwoStepSDFM: Estimate a Sparse Mixed Frequency Gaussian Factor Model Using a Two-Step Procedure

crossVal

R Documentation

Cross-validate SDFM Hyper-Parameters

Description

This function uses time series cross-validation \insertCiterob2018forecastingTwoStepSDFM in combination with random hyper-parameter search \insertCitebergstra2012randomTwoStepSDFM to validate the hyper-parameters of a sparse dynamic factor model as described in \insertReffranjic2024nowcastingTwoStepSDFM

Usage

crossVal(
  data,
  variable_of_interest,
  fcast_horizon,
  delay,
  frequency,
  no_of_factors,
  seed,
  min_ridge_penalty,
  max_ridge_penalty,
  cv_repetitions,
  cv_size,
  lasso_penalty_type,
  min_max_penalty,
  max_factor_lag_order = 10,
  lag_estim_criterion = "BIC",
  decorr_errors = TRUE,
  max_iterations = 1000,
  weights = NULL,
  comp_null = 1e-15,
  spca_conv_crit = 1e-04,
  parallel = FALSE,
  no_of_cores = 1,
  max_ar_lag_order = 5,
  max_predictor_lag_order = 5,
  jitter = 1e-08,
  svd_method = "precise",
  verbose = TRUE
)

Arguments

`data`	Numeric (no_of_vars `\times` no_of_obs) matrix of data or zoo/xts object sampled at mixed frequencies (quarterly and monthly).
`variable_of_interest`	Integer indicating the index of the target variables.
`fcast_horizon`	Integer value indicating the target forecasting horizon.
`delay`	Integer vector of variable delays, measured as the number of months since the latest available observation.
`frequency`	Integer vector of frequencies of the variables in the data set (currently supported: `12` for monthly and `4` for quarterly data).
`no_of_factors`	Integer number of factors.
`seed`	32-bit unsigned integer seed for all random processes inside the function.
`min_ridge_penalty`	Numeric lower bound for the sampled ridge penalty coefficient candidates.
`max_ridge_penalty`	Numeric upper bound for the sampled ridge penalty coefficient candidates.
`cv_repetitions`	Integer number of `fcast_horizon`-step-ahead predictions computed for each candidate set.
`cv_size`	Integer number of candidate sets.
`lasso_penalty_type`	Character indicating the lasso penalty type. If set to `"selected"`, the `\ell_1`-size constraint will be returned as number of non-zero elements of each column of the loading matrix. If set to `"penalty"`, the lasso size constraint will be returned. If set to `"steps"`, the number of LARS-EN steps will be returned.
`min_max_penalty`	Vector of size two, where the first element indicates the lower and the second element indicates the upper bound of the lasso penalty equivalent. If `lasso_penalty_type` is set to `"selected"` or `"steps"`, both elements must be strictly positive integers.
`max_factor_lag_order`	Integer maximum order of the VAR process in the transition equation.
`lag_estim_criterion`	Information criterion used for the estimation of the factor VAR order (`"BIC"` (default), `"AIC"`, `"HIC"`).
`decorr_errors`	Logical, whether or not the errors should be decorrelated.
`max_iterations`	Integer maximum number of iterations of the SPCA algorithm.
`weights`	Numeric vector, weights for each variable weighing the `\ell_1` size constraint.
`comp_null`	Numeric computational zero.
`spca_conv_crit`	Numeric conversion criterion for the SPCA algorithm.
`parallel`	Logical, whether or not to run the cross-validation loop in parallel.
`no_of_cores`	Integer number of cores to use when run in parallel.
`max_ar_lag_order`	Integer maximum number of lags of the target variable included in the final ARDL prediction routine.
`max_predictor_lag_order`	Integer maximum number of lags of the predictors included in the final ARDL prediction routine.
`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.
`svd_method`	Either `"fast"` or `"precise"`. Option `"fast"` uses Eigen's BDCSVD divide and conquer method for the computation of the singular values. Option `"precise"` (default) implements the slower, but numerically more stable JacobiSVD method.
`verbose`	Logical, whether to print some progress tracking output to the console.

Details

fcast_horizon should be set to the target prediction horizon, as hyper-parameters can differ substantially between different horizons. For nowcasting, use fcast_horizon = 0. For backcasting, fcast_horizon can be set to a negative number indicating the step-back backcasting horizon.

Internally, candidates of the hyper-parameters are drawn randomly. However, a regular dense DFM will always be considered by default. The ridge penalty is drawn as \exp(u), where u is uniformly distributed between min_ridge_penalty and max_ridge_penalty. If lasso_penalty_type = "selected", the lasso penalty is drawn as a random vector \bm{v}, where each entry is uniformly distributed. If lasso_penalty_type = "steps", the lasso penalty is drawn as a random value v that is uniformly distributed. If lasso_penalty_type = "penalty", the lasso penalty is drawn as a random vector \exp(\bm{v}), where each entry of \bm{v} is uniformly distributed. In all three cases, the upper and lower bounds of the uniform distributions governing the lasso penalties are given by the first and second entry of min_max_penalty, respectively.

For medium to large data sets in combination with a medium to large cv_size, it can be beneficial to set parallel = TRUE. This will enable parallelisation via the doParallel, doSNOW, foreach, and parallel packages in R. In this case, no_of_cores should be set to the number of physical cores of the user's machine. It is not advisable to use the number of logical cores, as this can considerably deteriorate performance.

This function serves as a direct wrapper to nowcast. For more information on the additional function parameters, see the corresponding help page.

Value

An object of class SDFMcrossVal with main components:

CV: A list with components `CV Results` (matrix of all cross-validation errors and corresponding hyper-parameter values) and `Min. CV` (row of ⁠CV Results⁠ with the minimum cross-validation error).
BIC: A list with components ⁠BIC Results⁠ (matrix of all BIC values and corresponding hyper-parameter values) and ⁠Min. BIC⁠ (row of ⁠BIC Results⁠ with the minimum BIC).

Author(s)

Domenic Franjic

References

\insertRef

bergstra2012randomTwoStepSDFM

\insertRef

rob2018forecastingTwoStepSDFM

\insertRef

franjic2024nowcastingTwoStepSDFM

Examples

data(mixed_freq_factor_model)
no_of_vars <- dim(mixed_freq_factor_model$data)[2]
no_of_factors <- dim(mixed_freq_factor_model$factors)[2]
cv_results <- crossVal(data = mixed_freq_factor_model$data, variable_of_interest = 1, 
                       fcast_horizon = 0, delay = mixed_freq_factor_model$delay, 
                       frequency = mixed_freq_factor_model$frequency,
                       no_of_factors = no_of_factors, seed = 25032026,
                       min_ridge_penalty = 1e-5, max_ridge_penalty = 10, 
                       cv_repetitions = 1, cv_size = 50, lasso_penalty_type = "selected",
                       min_max_penalty = c(5, 45), verbose = FALSE)
print(cv_results)
cv_plots <- plot(cv_results)        
cv_plots$`CV Results`
cv_plots$`BIC Results`

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