Software companion
Projection-Space Calibration and Coherent Lowpass Field Lifting
Overview
Calibration is easy to do and easy to do dishonestly, because the correction can read the very year it is later scored on. The governing decision in this code is therefore protocol rather than method: calibrate_leave_one_year_out is the shared entry point, and every rung — flat variance, quantile remapping, state-conditional width, the blended compromise — is fitted with the evaluation year withheld. A variant that cannot be expressed that way does not go on the ladder.
The second piece is the return journey. Calibrating a one-dimensional regional index is cheap, but a calibrated index that cannot be turned back into a field is not a forecast product. models/coefficient_lifting.py lifts calibrated index members into coherent low-pass fields, so the ladder’s output stays in the same representation as everything else in the series, and the lifted members can be scored as fields rather than only as an index.
Implementation
- Space
- The regional index projection of the ensemble, calibrated there and lifted back to fields
- Protocol
- Leave-one-year-out throughout, so no rung reads the year it is evaluated on
- Rungs
- Band error decomposition, flat lead-smooth variance, quantile remapping of lifted members, an analog trajectory baseline, state-conditional width, and a blended partial-conditioning variant
- Diagnostics
- Lead-wise spread-skill, flow-dependence correlation, and conditional-sigma compression
Components
projection_calibration.py- The calibration ladder: lead-smooth log-variance fitting, quantile remapping, the leave-one-year-out driver, conditional and blended variants, and flow-dependence measurement
models/coefficient_lifting.py- Lifting calibrated index members back into coherent low-pass fields
conditional_variance.py- State-conditional variance estimation and its compression
index_series.py- Regional index extraction from fields and ensembles
scripts/band_error_decomposition.py- The first rung: where error sits across wavelet bands
scripts/conditional_variance_calibration.py- Fitting and scoring the state-conditional width
scripts/lift_calibrated_members.py- Producing lifted field members from a calibrated index ensemble
scripts/analog_trajectory_baseline.py- The analog baseline the ladder is measured against
scripts/phase_g3_calibration.py, phase_g3pp_blended_calibration.py- The recentred and blended calibration variants
Calibration ladder
decomposeAttribute ensemble error across wavelet bands to locate what calibration can reach.fit flatFit a lead-smooth log-variance correction, leave-one-year-out.remapApply quantile remapping so the corrected distribution matches its target shape.liftReturn calibrated index members to coherent low-pass fields.conditionFit a state-conditional width and measure its flow dependence.blendTrade conditioning against dispersion in the partial-conditioning variant.
Reproducibility and validation
- Every rung is fitted leave-one-year-out, so a calibration cannot use the year it is later scored on.
- Flow dependence is measured explicitly rather than assumed from an improvement in average reliability, which is how the report separates what post-processing bought from what it did not.
- The analog trajectory baseline sits on the same ladder, so a calibration rung has to beat a simple reference and not only its own uncalibrated predecessor.
- Lifted members are scored as fields, so an index-space improvement that does not survive the return to field space cannot be reported as a product.
Availability
Not publicly released. The calibration modules are the most portable part of the repository — they operate on saved ensemble index arrays rather than on the model — but they are calibrated against ensembles produced by checkpoints that are not distributed.