compute_kupiec: Value-at-Risk (VaR) Unconditional Coverage Test (Kupiec)

In RCtest: Reality Check and Predictive Ability Tests for Forecast Evaluation

Value-at-Risk (VaR) Unconditional Coverage Test (Kupiec)

Description

Performs Kupiec's (1995) Unconditional Coverage (UC) test for evaluating Value-at-Risk (VaR) forecasts from competing forecast against realized values.

Hypotheses:

• H0: The forecast correctly captures VaR — violations occur with the expected frequency alpha.

• H1: The forecast fails to correctly capture VaR — the observed frequency of violations differs significantly from alpha.

Usage

compute_kupiec(
  forecast_matrix,
  forecast_sd_models,
  benchmark_col = ncol(forecast_matrix),
  alpha = 0.05
)

Arguments

forecast_matrix	matrix of dimension P x K_total. Columns contain point forecasts for each model; the benchmark column supplies the realized values.
forecast_sd_models	matrix of dimension P x K, where K = K_total - 1. Contains time-varying forecast standard deviations, typically from estimate_forecast_variance.
benchmark_col	Index or name of the benchmark column. Defaults to the last column.
alpha	numeric VaR significance level (e.g., 0.05 for 95% VaR). A violation occurs when the realized value falls below the estimated VaR.

Details

For each competing forecast k, the VaR at level alpha is:

VaR_{t,k} = \hat{y}_{t,k} + \Phi^{-1}(\alpha) \cdot \hat{\sigma}_{t,k}

where \Phi^{-1} is the standard normal quantile function. A violation occurs when the realized value falls below VaR_{t,k}. The likelihood-ratio statistic LR_{UC} follows a \chi^2(1) distribution under H0 (Kupiec, 1995). Failing to reject H0 (large p-value) indicates correctly calibrated VaR; rejecting H0 (small p-value) indicates the forecast under- or over-estimates tail risk.

Value

A named list (one element per competing forecast) of htest objects, each containing:

statistic

The LR-UC test statistic (\chi^2-distributed under H0).

p.value

P-value from the \chi^2(1) distribution. A large p-value indicates correctly calibrated VaR coverage.

actual_exceedances

Observed number of VaR violations.

expected

Expected number of violations (P * alpha).

References

Kupiec, P. H. (1995). Techniques for Verifying the Accuracy of Risk Measurement Models. The Journal of Derivatives, 3(2), 173–184. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.3905/jod.1995.407942")}

See Also

estimate_forecast_variance, run_comprehensive_erc_analysis

Examples

data(metals)
benchmark_col      <- 15
K_total            <- ncol(metals)
comp_cols          <- setdiff(seq_len(K_total), benchmark_col)
forecast_variance  <- estimate_forecast_variance(metals,
                        benchmark_col = benchmark_col, window_size = 20)
forecast_sd_models <- sqrt(forecast_variance[, comp_cols])
coverage_results   <- compute_kupiec(metals, forecast_sd_models,
                        benchmark_col = benchmark_col, alpha = 0.05)
print(coverage_results[[1]])

RCtest documentation built on June 2, 2026, 9:07 a.m.