L2 Calibration (CQR)
Relevant source files
The following files were used as context for generating this wiki page:
The L2 Calibration layer is a critical component of the ZINC-Fusion-V15 hierarchical ensemble forecasting system. It utilizes Conformalized Quantile Regression (CQR) to provide a mathematically defensible outer risk envelope (p10_cal and p90_cal) for Soybean Oil (ZL) futures price predictions. This layer ensures that the system provides finite-sample coverage and adapts interval widths to market heteroskedasticity, moving beyond "vibes-based" uncertainty estimates to strictly defensible mathematical boundaries.
Sources: README.md:38-41, README.md:88-91, AGENTS.md:28-30
Architecture and Methodology
The L2 Calibration layer sits between the L1 Meta-learner and the L3 Risk Engine. While the L0 Core and L1 Meta models generate native quantiles (p30, p50, p70), the L2 layer is responsible for calibrating the outer bounds to ensure empirical coverage matches theoretical targets.
Conformalized Quantile Regression (CQR)
CQR combines standard quantile regression with conformal prediction. This methodology is chosen to achieve reliable coverage under exchangeability while allowing the model to adapt to changing volatility regimes (heteroskedasticity). The primary goal is to provide a "truthful" outer risk envelope without distorting the central trend band established by the lower layers.
Sources: README.md:144-148, AGENTS.md:28-30
Multi-Horizon Implementation
Calibration is performed independently for each of the four target horizons:
- 5-Day (1 Week)
- 21-Day (1 Month)
- 63-Day (1 Quarter/3 Months)
- 126-Day (6 Months)
Sources: README.md:144, AGENTS.md:35-37
Data Flow and Logic
The calibration process consumes out-of-fold (OOF) predictions and aligns them with realized historical truths to calculate the necessary adjustments for the final published quantiles.
The diagram illustrates the flow of native quantiles through the CQR engine to produce calibrated outer bounds.
Sources: README.md:144-156, README.md:223-228
Monotonic Repair and Quantile Crossing
A strict guardrail system is enforced during calibration to prevent "quantile crossing," where a lower-probability quantile might mathematically exceed a higher one due to noise. The L2 layer enforces the following hierarchy:
p10_cal ≤ p30 ≤ p50 ≤ p70 ≤ p90_cal
Sources: README.md:154-156, cubic.yaml:188-192
Component Specifications
Forecast Geometry
The L2 layer transforms the prediction "geometry" from the three native core quantiles into a five-point probabilistic distribution used for risk assessment and dashboard visualization.
| Quantile | Origin | Role |
|---|---|---|
| p10_cal | L2 CQR | Calibrated Lower Bound (Risk Floor) |
| p30 | L0/L1 Native | Lower Central Band |
| p50 | L0/L1 Native | Median / Point Forecast |
| p70 | L0/L1 Native | Upper Central Band |
| p90_cal | L2 CQR | Calibrated Upper Bound (Risk Ceiling) |
Sources: README.md:150-153, scripts/generate_synthesis.py:91-100
Validation and Empirical Coverage
The success of the L2 Calibration is measured against empirical benchmarks. The system targets:
- ~40% Empirical Coverage for the p30–p70 native central band.
- ~80% Empirical Coverage for the p10_cal–p90_cal calibrated outer envelope.
Sources: README.md:234-237
Integration with Synthesis and Risk
The outputs of the L2 Calibration layer feed directly into the L3 Risk Engine for Monte Carlo simulations and the L5-C Synthesis Engine for natural language generation.
Synthesis Usage
The synthesis engine (scripts/generate_synthesis.py) consumes the calibrated percentiles to describe the "forecast spread" and "forecast floor/ceiling" to stakeholders. It calculates the spread as a percentage of the median to qualify market uncertainty.
Sources: scripts/generate_synthesis.py:276-285
Dashboard Visualization
On the ZINC-Fusion dashboard, the L2 outputs are rendered as two distinct "cones":
- Primary Cone: P30–P70 (Native)
- Outer Cone: P10_cal–P90_cal (Lighter, Calibrated)
Sources: README.md:246-250, Docs/zinc-fusion-v15-preview.html:1052-1055
Summary
L2 Calibration (CQR) serves as the project's "anti-bullshit gate" for uncertainty. By applying Conformalized Quantile Regression, the system ensures that the reported p10 and p90 risk boundaries are mathematically defensible and maintain a consistent 80% empirical coverage across all four forecasting horizons. This rigorous approach to uncertainty allows for stable Monte Carlo simulations in L3 and provides the foundation for the "2+2=22" doctrine of discovering non-linear market interactions.
Sources: README.md:88-93, README.md:144-156, cubic.yaml:188-195