Self-Supervised Complex-Wavelet Learning and Statistically Governed Transfer

Overview

Implementation

Pretext task

Masked reconstruction of packed DTCWT coefficients, with deterministic block and whole-month temporal corruption

Stores

ERA5 plus the historical reconstructions ERSSTv5, HadISST1 and COBE-SST2, each with source-local per-channel normalization; the ERSSTv5 and HadISST1 stores run to 1980-12 against a 1951–1980 monthly climatology

Boundary

Only the 1981–2010 training slice is materialized, then split deterministically into pretext train and holdout; a timestamp audit runs immediately before coefficient arrays load and rejects any maximum after 2010-12

Statistics

Paired moving-block bootstrap with a fixed block policy, reported as a delta with a 90% interval

Tests

External-store ingestion, pretraining, coefficient-energy and statistics modules each have their own test module

Components

pretraining/masking.py

The deterministic corruption schemes: coefficient blocks and whole months

pretraining/losses.py

Hidden-only coefficient loss plus the reconstruction diagnostics

pretraining/dataset.py

The multistore pretext dataset and its materialization boundary

pretraining/loop.py

The pretext training loop and its held-out selection

pretraining/config.py

Pretext configuration, including store composition and masking policy

data/external_sst.py

The multistore ingestion contract: canonicalization, overlap policy, regridding, per-store normalization, validity masks and manifests

coefficient_energy.py

The energy audit explaining where reconstruction gains land in the pyramid and why they do not transfer

stats.py

The paired moving-block bootstrap and the resolvability standard

decision_reporting.py

Decision records tying each comparison to its bootstrap evidence

scripts/prepare_external_sst_store.py

Store construction from an external product

scripts/compare_evaluations.py

Paired comparison between two existing evaluations

scripts/audit_decision_resolvability.py

Retrospective audit of which past decisions were actually resolvable

Workflow

1. prepare-store Canonicalize, regrid and transform one external product into a packed store with its own normalizer and mask.
2. audit Verify geometry, channel layout, normalization scope and hashes across stores before training.
3. pretrain Run masked-coefficient pretraining over the store mixture with held-out selection.
4. transfer Load the pretext checkpoint into the 14-month forecast model, transferring shape-compatible tensors and reporting geometry differences.
5. compare Score transfer against the unpretrained reference under the paired bootstrap.
6. audit-energy Decompose where the reconstruction gain sits in the coefficient pyramid.

Reproducibility and validation

• The three historical reconstructions share underlying ship and buoy observations, so the repository documents them as distinct reconstruction methods rather than as independent data — the pretraining mixture adds uncertainty profiles, not proportionally more effective sample.
• A timestamp audit runs immediately before coefficient arrays are loaded and rejects any store whose maximum date crosses the declared boundary; additional pretext-only stores are permitted only outside both the validation and the test ranges and carry their own declared boundary.
• Transfer into the forecast model reports which tensors moved and which temporal-geometry buffers intentionally stayed at their own initialization, rather than loading silently.
• Comparisons are paired and bootstrapped under a fixed policy, so an improvement either resolves at the stated interval or is recorded as unresolved.

Availability