Evaluation and Inference¶

DepthDif has two distinct inference surfaces:

The published API runs the legacy single-OSTIA depthdif_v1.ckpt for one ISO week and is documented in Public inference.
Repository exporters load maintained scenario-resolved checkpoints conditioned on SST, SSS, and ADT.

Do not combine a public v1 checkpoint with a current pixel super-config.

Local checkpoint smoke test¶

Set CONFIG_PATH, SCENARIO, and CHECKPOINT_PATH in src/depth_recon/inference/run_single.py, then run:

/work/envs/depth/bin/python -m depth_recon.inference.run_single

This path is intended for a small batch and shape/output inspection. It is not a stitched geospatial export.

One global variable¶

export_global selects the repository snapshot nearest the Wednesday inside the requested ISO week, builds the inference patch grid, reconstructs every selected patch, and stitches overlaps with deterministic weights.

/work/envs/depth/bin/python -m depth_recon.inference.export_global \
  --scenario temperature \
  --year 2016 --iso-week 25 \
  --checkpoint logs/<run>/best.ckpt \
  --device cuda \
  --sampler ddim --ddim-steps 100 \
  --export-ground-truth

The inference super-config defaults to DDPM, patch stride 96, minimum ocean fraction 0.05, batch size 64, and six workers. The exporter can override those values. World exports use periodic dateline blending and final land masking.

Requested products are Surface, 10, 50, 100, 250, 500, 1000, 2000, 2500, and 5000 m. Each raster records the requested depth and the nearest actual GLORYS channel in its metadata. Temperature is exported in °C and salinity in PSU.

With ground truth enabled, the run includes decoded GLORYS, absolute-error rasters, error-analysis.json, and ocean-clipped analysis geometry. Optional ARGO point/profile GeoJSON and graphs are controlled by the sample-count flags.

Paired temperature and salinity¶

The paired wrapper runs separate scenario-compatible checkpoints and packages a shared production bundle:

/work/envs/depth/bin/python -m depth_recon.inference.export_global_variables \
  --year 2016 --iso-week 25 \
  --temperature-checkpoint logs/<temperature-run>/best.ckpt \
  --salinity-checkpoint logs/<salinity-run>/best.ckpt \
  --device cuda \
  --public-base-url https://<host>/inference_production/globe \
  --rclone-remote r2:<bucket>/inference_production/globe \
  --rclone-sync-scope globe

Wavenumber spectra are generated by default. Use --no-export-wavenumber-spectra only for a deliberately reduced run. Add --export-temporal-consistency to generate the temporal dashboard bundle and any extra weekly exports it needs.

Uncertainty¶

Add --export-uncertainty to the single- or paired-variable exporter. The default ensemble has 20 members and remains depth-resolved. Pass --uncertainty-collapse-depth only for the older one-raster representation. Main and uncertainty samplers can be configured independently. See Uncertainty.

Temporal products¶

The paired production wrapper can create a short temporal window. For a dedicated multiweek or full-year run, use:

/work/envs/depth/bin/python -m depth_recon.inference.export_temporal_global_variables \
  --start-year 2016 --start-iso-week 1 --week-count 52 \
  --temperature-checkpoint logs/<temperature-run>/best.ckpt \
  --salinity-checkpoint logs/<salinity-run>/best.ckpt \
  --device cuda

export_temporal_consistency_dashboard packages basin/depth error time series; export_temporal_cesium_globe_assets packages the weekly 10 m animation. The static viewers consume the generated temporal-config.json and temporal globe config rather than reading model outputs directly.

Analysis and Cesium assets¶

Package one completed run for the spatial globe:

/work/envs/depth/bin/python -m depth_recon.inference.export_cesium_globe_assets \
  --run-dir inference/outputs/global_top_band_<YYYYMMDD> \
  --public-base-url https://<host>/inference_production/globe \
  --rclone-remote r2:<bucket>/inference_production/globe \
  --rclone-sync-scope globe

The packager creates tiled WebP layers, manifests, GeoJSON, profile graphs, and dashboard inputs. Raw GeoTIFFs remain in the run directory. Upload is optional and occurs only when an rclone target/scope is supplied.

The repository also provides standalone exporters for spatial error analysis, temporal dashboards, temporal globes, and wavenumber spectra. See the CLI reference for their module names and canonical entry points.

Host the comparison globe¶

The standalone comparison viewer at docs/comparison-globe/index.html compares GLORYS, DepthDif, IDW, climatology, LSTM, CNN, and U-Net layers. It loads the hosted comparison-globe-config.json by default; append ?config=<url> to test another manifest.

Each variable/depth entry can use a layers mapping, matching the spatial globe manifest shape. For compatibility, the viewer also accepts direct glorys_tiles_url/ground_truth_tiles_url, depthdif_tiles_url/prediction_tiles_url, idw_tiles_url, climatology_tiles_url, lstm_tiles_url, cnn_tiles_url, and unet_tiles_url fields. ARGO sample and patch-split GeoJSON URLs may be declared at the manifest root or inside a variable config.

Validation and paper products¶

For one model's pooled validation error by depth:

/work/envs/depth/bin/python -m depth_recon.inference.export_validation_error_summary \
  --scenario temperature \
  --checkpoint logs/<run>/best.ckpt \
  --split val --year 2016 --iso-week 25 --device cuda

export_paper_week runs the model set declared in its models YAML and writes reusable native-depth artifacts. depth-recon-export-paper-metrics evaluates a paper-week bundle, while export_spectral_comparison_bundle repeats compatible paper exports across weeks and aggregates spectral comparisons. These commands require explicit model/checkpoint provenance; generated metrics are not embedded as claims in this documentation.

Sampling choice¶

DDPM follows the full configured reverse process. DDIM permits a shorter explicit step count. The repository does not define a universally sufficient DDIM step count: choose it for a specific checkpoint and report it with the result.