Lib Arch

arch

Two distinct libraries share one package. The volatility half is well known; arch.bootstrap is the most under-used correct tool in quantitative finance. 8.0.0 is a compatibility release (Python 3.14 wheels, NumPy 2.4 / pandas 3) — not an API break from 7.x. statsmodels has no equivalent.

The trap that costs you money

🚨 SPA, RealityCheck, StepM and MCS all take LOSSES — lower is better. Verified against arch/bootstrap/multiple_comparison.py: SPA/StepM document benchmark as "T element array of benchmark model losses" and models as "T by k element array of alternative model losses"; MCS's parameter is literally named losses.

Passing returns does not raise and does not warn. It inverts the test — the worst strategy is identified as the best, and the p-value you report is for the opposite hypothesis. For a return series the whole conversion is losses = -returns. Anything already loss-shaped (squared forecast error, negative log-likelihood, absolute error, drawdown) goes in as-is. A ratio — a Sharpe, an information ratio — is not accepted at all; these tests need the per-period loss column.

Which procedure answers which question

Verified signatures: SPA(benchmark, models, block_size=None, reps=1000, bootstrap="stationary", studentize=True, nested=False, *, seed=None); StepM(benchmark, models, size=0.05, ...); MCS(losses, size, reps=1000, block_size=None, method="R"|"max", ...).

• ✅ RealityCheck is literally class RealityCheck(SPA): pass — a zero-code subclass; White's Reality Check is SPA without studentization or recentring. Use SPA, and mention RealityCheck only when reproducing a pre-2005 paper.
• 🚨 SPA.pvalues returns three values — lower, consistent, upper. Report consistent. They bracket the influence of dominated models on the null; lower is liberal, upper conservative. Also .critical_values(pvalue=0.05) and .better_models(pvalue=0.05).
• StepM.superior_models names the survivors under FWER control; internally it builds an SPA. MCS takes no benchmark, raises with fewer than 2 columns, and gives .included/.excluded.
• ⚠️ block_size defaults to int(sqrt(T)). Set it from optimal_block_length (Politis-White) — preserving serial dependence is the entire reason for a block bootstrap. Cost is O(reps × T × k): 1000 reps over hundreds of candidates is minutes, not seconds.
• ⚠️ These control FWER over the models you pass, and know nothing about the variants you tried and discarded — that is what a trial ledger and the Deflated Sharpe Ratio are for. Use both.

Volatility models: fit on returns × 100

🚨 arch expects returns in PERCENT. Decimals give tiny variances, poor optimizer conditioning and convergence warnings — the single most common arch support question, and a usage issue rather than a bug. Rescale the forecast back out of percent before you use it.

• forecast() returns variance, not volatility — square-root it, then undo the ×100. reindex=False is what you almost always want; the default reindexes to the full sample.
• ⚠️ o=1 is what gives you the leverage effect. Plain GARCH(1,1) treats a −5% day and a +5% day identically, empirically false for equities. GJR (o=1) or EGARCH is the honest default.

Covers GARCH, EGARCH, GJR-GARCH/TARCH, APARCH, HARCH, HAR-RV, FIGARCH, RiskMetrics, ARCH; Normal / Student-t / skew-t / GED innovations; AR and HAR mean models; plus arch.unitroot (ADF, DF-GLS, Phillips-Perron, KPSS, Zivot-Andrews, Variance Ratio), cointegration and long-run covariance estimators. HAR on realized volatility remains a very strong baseline.

Minimal correct call

from arch import arch_model
from arch.bootstrap import SPA, StepM, MCS, optimal_block_length
am  = arch_model(returns * 100,                 # 🚨 PERCENT, not decimals
                 vol="GARCH", p=1, o=1, q=1,    # o=1 -> GJR asymmetry (leverage effect)
                 dist="skewt", mean="Constant")
res = am.fit(disp="off")
f   = res.forecast(horizon=10, reindex=False)   # variance, not vol
sigma_next = (f.variance.iloc[-1] ** 0.5) / 100 # 🚨 rescale back out of percent

z = (res.resid / res.conditional_volatility).dropna()   # GARCH-filtered VaR: a CONDITIONAL quantile
var_1d = (res.params["mu"] + sigma_next.iloc[0] * 100 * z.quantile(0.05)) / 100

losses_bm  = -bench_returns                     # 🚨 NEGATE. (T,)
losses_mdl = -model_returns                     # 🚨 NEGATE. (T, k)
bs = int(optimal_block_length(losses_bm).iloc[0, 0])

spa = SPA(losses_bm, losses_mdl, reps=1000, block_size=bs, seed=7); spa.compute()
print(spa.pvalues["consistent"])                # 🚨 the one to report

stepm = StepM(losses_bm, losses_mdl, size=0.05, reps=1000, block_size=bs); stepm.compute()
print(stepm.superior_models)                    # WHICH ones survive FWER control

mcs = MCS(losses_mdl, size=0.10, reps=1000, block_size=bs); mcs.compute()
print(mcs.included, mcs.excluded)               # no benchmark argument

Scripts

✅ scripts/spa_direction.py runs the inversion end to end. Six synthetic strategies whose realised annualised Sharpes are pinned to -1.5, -0.9, 0.0, +0.5, +1.0, +1.6 against a +0.3 benchmark (seed 0, T=1500 daily observations, reps=1000, seed=7). Measured, with arch 8.0.0:

The trap names the two worst strategies in the set as the superior ones — a swing of 3.1 Sharpe between what it crowns and what actually won. Nothing raised and nothing warned. 🚨 The consistent p-value is 0.0050 the correct way round and 0.0000 the wrong way round, so it rejects either way and cannot tell you which input you passed. The script's numpy-only reference SPA reproduces arch's p-values to max|diff| = 0.000000 and its StepM sets exactly, so the demonstration still runs on a machine without arch.

See also

• ../../../fin-core/skills/backtest-validation/SKILL.md — the domain skill for the arch.bootstrap half
• ../../../fin-core/skills/factor-and-timeseries-research/SKILL.md — the domain skill for the GARCH half
• ../../../fin-core/skills/factor-and-timeseries-research/references/arch.md — the source card
• ../../../fin-core/skills/backtest-validation/references/significance-tests.md — which test answers which question

Where this sits

This file is the deep dive on one library and assumes the choice is already made. For which library to pick, how it compares with the alternatives, and the traps that span several of them, the entry point is the domain skill backtest-validation (../../../fin-core/skills/backtest-validation/SKILL.md).