ENH: Add VaR backtests (Kupiec, Christoffersen, Basel traffic light) - #965

Target 9.1: merge after v9.0.0 is tagged. xref #904. This implements the five standard
backtests from the proposal. max_undetectable_understatement is left out, pending a
decision on the issue.

Adds the new module arch/univariate/backtest.py, exported from arch.univariate:

• var_exceptions(returns, var): the exceptions, -returns > var. VaR is a positive
  loss, and a loss equal to the VaR is not an exception. It is a bool array, or a Series
  named "exception" when an input is a pandas object.
• kupiec_pof(returns, var, p=0.05): the Kupiec (1995) proportion-of-failures
  likelihood-ratio test, chi2(1).
• christoffersen_independence(returns, var): Christoffersen's (1998) Markov independence
  test, chi2(1).
• christoffersen_conditional_coverage(returns, var, p=0.05): LR_uc + LR_ind, chi2(2).
• traffic_light(returns, var, p=0.01, window=250): the Basel Committee (1996) zone,
  returned as a frozen TrafficLightResult with the zone, the count, the cumulative
  probability P(X <= x), the type 1 error P(X >= x) (Table 1 of the framework), nobs
  and p.

The three tests return WaldTestStatistic.

One VaR convention throughout arch: VaR is named by its confidence level, and the
argument is always p, the probability of an exception (the size of the tail): p=0.05
for a 95% VaR and p=0.01 for a 99% VaR. This is rugarch's alpha; MATLAB's VaRLevel
is 1 - p.

• The tests default to p=0.05, a 95% VaR, as rugarch and MATLAB do. traffic_light
  defaults to the 99% VaR of the Basel framework.
• var_ratio and ARCHModelFixedResult.var_ratio now take p (default 0.001, a 99.9%
  VaR). Their level, the confidence level, is deprecated with a FutureWarning, and
  p and level cannot both be given.
• The forecasting notebook labels its VaR columns "99%" and "95%", not "1%" and "5%".

Other conventions:

• The zones follow the wording of the Basel framework: the yellow zone begins where the
  probability of that number of exceptions or fewer "equals or exceeds 95%", and the red
  zone where it equals or exceeds 99.99%. For other sample sizes the boundaries are
  deduced from the binomial distribution, as the framework says. traffic_light counts
  the last window observations (the Basel year) and raises for a shorter series. Zero
  exceptions is always green.
• LR_cc is LR_uc on all T observations plus LR_ind on the T-1 transitions, as in rugarch
  and MATLAB.

Inputs:

• The data must be finite and 1-d.
• Two Series are aligned on the index. Otherwise the lengths must match, and the inputs
  are matched by position. The docs note that forecasts are indexed by their origin by
  default, so forecast(..., align="target") (or a shift) is needed before a backtest.
• 0·log 0 = 0 through xlogy.

Validation:

• R 4.6.1, rugarch 1.5.6 VaRTest, on 11 cases: largest difference in the statistics
  1.2e-14.
• Degenerate series (zero or all exceptions, first-only or last-only, 2 observations)
  cannot go through rugarch, which indexes a 2x2 table. They are checked against an
  independent R likelihood implementation, cross-checked with rugarch.
• The traffic-light probabilities and type 1 errors match R pbinom to 1e-12, and the
  published Tables 1 and 2 of the BIS 1996 backtesting framework, including the zone
  boundaries at 5 and 10.
• The Kupiec 99% non-rejection regions (255/510/1000 observations) match the usually quoted
  values.
• The references are stored as constants in the tests. The R script that produces them is
  arch/tests/univariate/results/var_backtest_reference.R; it prints the constants, and
  rerunning it reproduces them exactly.

Tests:

• test_backtest.py and test_validation_backtest.py, plus the var_ratio tests for
  p and the deprecated level.
• Each of 8 deliberately introduced bugs is caught.
• The univariate suite passes (14,325 passed), the new tests pass on the minimum versions
  (Python 3.10, NumPy 1.23, SciPy 1.8, pandas 1.5) and with -W error, and the forecasting
  notebook runs. numpydoc lint 0.

For review:

1. var_ratio(level=...) ships in 9.0, so it is deprecated here rather than removed. If
   this lands before 9.0.0 is tagged, level can be dropped instead.
2. traffic_light keeps p=0.01 as its default (Basel), while the tests default to 0.05.

Thanks to @sarthakguptaquant for the proposal.

🤖 Generated with Claude Code