Software companion
Complex-Wavelet Earthformer Forecasting of Tropical-Pacific Sea-Surface Temperature
Overview
This is the externally readable product of the whole programme, so the software here is about assembly and defensibility rather than about a new method. It runs the adopted stack over the full record in the relative-SST frame, produces a 32-member residual-diffusion ensemble, and builds the figure set the paper is made of: lead diagnostics, band decompositions, Hovmöller comparisons, and consolidated event cases.
It is also the one part of the series that is published. The release is scoped to this paper rather than to the whole eleven-document programme: the package, the command-line drivers, the base configurations, the exact configurations behind the paper’s two products, the seed-replication and ablation configurations, the reference scorecards, the figures, and the test suite. The other reports in the series describe development phases that are not part of it.
The gallery is where the care goes. Choosing which cases to show is exactly where a publication can flatter itself, so case selection is a separate audited step — gallery_audit.py and its script check the selection against the declared criteria, and the report labels each figure with the basis on which its case was chosen.
An eleven-script revision suite sits beside the build and answers reviewer-style questions on demand: linear inverse model baselines and an amplitude variant, other statistical baselines, climatological Brier scores, seasonal stratification, block-length sensitivity, bias-corrected calibration, a seed summary, and cross-generation editorial comparisons. It is driven from a runbook, so the revision pass is re-runnable rather than a set of one-off notebooks.
Implementation
- Frame
- The relative-SST anomaly reduction selected by the reference study, applied across the full record
- Product
- A CMIP6-pretrained deterministic forecaster plus a 32-member residual-diffusion ensemble
- Scope
- Characterized on 2021–2025 development validation, and deliberately not ranked against earlier generations
- Revision suite
- Eleven scripts driven from an editorial runbook: LIM and statistical baselines, climatological Brier, seasonal stratification, block-length sensitivity, bias-corrected calibration, seed summary, editorial comparisons
- Figures
- An optional dependency set installs perceptually uniform colour maps for the publication renders
Components
phase_k.py- The publication build: run composition, artifact assembly and the figure set
gallery_audit.py- Case-selection auditing against the declared criteria
event_strata.py- Event stratification used to choose and label cases
viz/maps.py, hovmoller.py, band_hovmoller.py- The map, Hovmöller and per-band renders the figures are built from
scripts/phase_k.py, phase_k_finalize.py- The build entry point and the finalization pass
scripts/phase_k_event_gallery.py, phase_k_gallery_audit.py- Gallery construction and its audit
scripts/revision_lim_baseline.py, revision_lim_amplitude_variant.py- Linear inverse model baselines
scripts/revision_statistical_baselines.py, revision_climatological_brier.py- Statistical and climatological reference scores
scripts/revision_seasonal_stratification.py, revision_block_length_sensitivity.py- Seasonal and bootstrap-block sensitivity
scripts/revision_bias_corrected_calibration.py, revision_seed_summary.py- Bias-corrected calibration and across-seed variation
scripts/revision_editorial_comparisons.py- Cross-generation comparisons prepared for editorial response
Publication build
build dataMaterialize the full-record relative-SST coefficient stores.runProduce deterministic forecasts and the 32-member diffusion ensemble.calibrateApply the adopted projection-space calibration and lift members to fields.gallerySelect event cases, then audit the selection against the declared criteria.reviseRun the baseline and sensitivity suite from the editorial runbook.finalizeAssemble figures, tables and the artifact set the manuscript consumes.
Reproducibility and validation
- Case selection is audited as its own step, because a publication gallery is exactly where favourable examples can be chosen without anyone noticing.
- The published characterization is on development validation and is described as such; the paper does not rank this generation against the earlier ones, because they were selected under different protocols.
- Baselines live in the build rather than in reviewer correspondence: linear inverse models, statistical references and climatological scores are all re-runnable from the runbook.
- Seed variation and bootstrap block length are treated as reportable sensitivities rather than as fixed implementation details.
Availability
Published. The code is on GitHub under the MIT licence, with documents, results and figures under CC-BY-4.0. Two Zenodo deposits carry what a repository should not: the archived software release, and the archived forecast products — validation forecasts, the 32-member ensemble with its seed replications, trained checkpoints, and calibrated prediction fields. Work that builds on this should cite the paper together with both deposits.
What the repository does not carry is the source data and the intermediate stores. ERA5 acquisition still needs Copernicus credentials, and the full-record coefficient stores are rebuilt from the ingestion scripts rather than downloaded.