conformal-oracle 0.3.2

Conformal recalibration audit for tail quantile forecasters

conformal-oracle

Conformal recalibration audit for tail quantile forecasters.

Given any return series and either a forecaster object or a pre-computed quantile path, conformal-oracle computes a one-parameter conformal correction (static or rolling), classifies the forecast as signal-preserving or replacement, and reports a full backtest panel.

The core install is dependency-agnostic: it needs only NumPy, pandas, SciPy, statsmodels, and matplotlib. No forecaster library is required unless you use the built-in benchmark wrappers.

Implements the methodology from:

Pele, D.T., Bolovaneanu, V., Ginavar, A.T., Lessmann, S., Hardle, W.K. "Recalibrating Tail Event Forecasts under Temporal Dependence" (2026).

What's new in 0.3.1

Coverage bugfix (rolling mode). The rolling conformal correction now uses the finite-sample split-conformal quantile — the ceil((w+1)(1-alpha))-th order statistic of the trailing-window scores — rather than the plain empirical (1-alpha) quantile. Releases up to and including 0.3.0 systematically under-covered in mode="rolling"; if you produced rolling-mode results on an earlier version, re-run on 0.3.1 or later. Static mode is affected only negligibly (large calibration window).

New diagnostics. recalibration.diagnose_scale / ScaleDiagnostic (a location–scale decomposition of the conformal shift) and recalibration.ACICalibrator (an Adaptive Conformal Inference baseline with step size selected by first-half validation). See the changelog for details.

Install

pip install conformal-oracle                 # core (no arch dep)
pip install conformal-oracle[benchmarks]     # + GJR-GARCH, GARCH-Normal
pip install conformal-oracle[chronos]        # + Chronos TSFM
pip install conformal-oracle[all]            # everything

For development:

git clone https://github.com/QuantLet/Conformal_Oracle.git
cd Conformal_Oracle/python
pip install -e ".[dev,benchmarks]"

Quickstart -- agnostic audit (no forecaster dependency)

import pandas as pd
from conformal_oracle import audit

returns = pd.read_csv("returns.csv", index_col=0, parse_dates=True).squeeze()
# q_lo: your model's predicted 1% quantile, same index as returns
q_lo = pd.read_csv("my_var_forecast.csv", index_col=0, parse_dates=True).squeeze()

result = audit(returns, forecast=q_lo, alpha=0.01, mode="static")
print(result.summary())

# Rolling mode: re-estimates the conformal correction from a
# trailing 250-day window (more realistic for live deployment)
result_roll = audit(returns, forecast=q_lo, alpha=0.01, mode="rolling")
print(result_roll.summary())

No arch, no torch, no heavyweight dependency -- just your quantile series.

Quickstart -- with a forecaster object

from conformal_oracle import audit
from conformal_oracle.contrib.benchmarks import GJRGARCHForecaster

result = audit(returns, GJRGARCHForecaster(), alpha=0.01, mode="rolling")
print(result.summary())

Regime classification

from conformal_oracle import classify_regime

verdict = classify_regime(returns, forecast=q_lo, mode="rolling")
print(verdict.regime)       # "signal-preserving" or "replacement"
print(verdict.R)            # replacement ratio
print(verdict.basel_zone)   # "green", "yellow", or "red"

Compare multiple forecasters

from conformal_oracle import compare_forecasters

comp = compare_forecasters(
    returns,
    {"model_A": q_lo_A, "model_B": q_lo_B},
    mode="rolling",
)
print(comp.comparison_table())
print(comp.dm_matrix())

Custom forecaster

Any object implementing fit(returns) and forecast(returns, t) works:

from conformal_oracle._types import SampleDistribution

class MyForecaster:
    def fit(self, returns): pass
    def forecast(self, returns, t):
        hist = returns.iloc[max(0, t-250):t]
        return SampleDistribution(samples=hist.values)

result = audit(returns, MyForecaster(), alpha=0.01)

Worked examples

• Quickstart (S&P 500) -- Static and rolling conformal audits with GJR-GARCH and Lag-Llama.
• Reproduce Table 4 (Full replication) -- 9 forecasters x 24 assets, full master evaluation table with checkpointing.

Documentation

• API Reference
• Methodology
• Conventions (return units, VaR sign, alpha)
• Migration Guide (v0.3)

Requirements

Python 3.10+, numpy, pandas, scipy, statsmodels, matplotlib.

GARCH benchmarks require arch>=6.0 (install with [benchmarks]). TSFM wrappers require PyTorch and model-specific packages (see extras).

License

MIT