An Open-Source, Chart-Conditioned Geospatial Surrogate Framework for Coastal Bathymetry via Multi-Source Data Fusion and Spatial Validation.
BathySurrogate is an open-source, modular Python computational framework designed for coastal bathymetric estimation under severe data sparsity in turbid and complex waters. It implements a chart-conditioned geospatial surrogate paradigm--coupling multi-temporal Sentinel-2 optical composites, GEBCO global bathymetric priors, and sparse in-situ nautical chart soundings--evaluated through a leakage-controlled Spatially Blocked 5-Fold Cross-Validation protocol.
The framework features a 12-feature Enhanced Random Forest surrogate engine as its primary operational predictor, alongside an inverse score-based generative diffusion model (S³GM) with guided Diffusion Posterior Sampling (DPS) for conditional spatio-temporal reconstruction and uncertainty analysis.
- Modular Software Design: Implements Strategy, Factory, and Pipeline architectural design patterns with externalized YAML configuration management.
- Leakage-Controlled Spatial Validation: Enforces Spatially Blocked 5-Fold Cross-Validation (4 × 4 spatial grid) ensuring zero spatial autocorrelation leakage between training and evaluation splits in the Random Forest surrogate benchmark.
- Enhanced Surrogate Modeling: Integrates 12 domain-specific features (spectral bands, band ratios, log transforms, spatial coordinates, GEBCO bathymetric priors, and nearest-neighbor sounding distances/depths) achieving pooled Out-of-Fold (OOF) R² = 0.483, Pearson r = 0.706, RMSE = 9.19 m, MAE = 6.61 m, and a range-normalized nRMSE = 12.61%.
- High-Performance Computation: Low computational complexity (O(S × N × C²)), processing annual decadal mapping workflows in seconds on standard CPUs and minutes on consumer GPUs (NVIDIA RTX 2060, 6GB VRAM).
- FAIR4RS Compliance: Adheres strictly to Findable, Accessible, Interoperable, and Reusable software standards with comprehensive test suites, metadata (
CITATION.cff), and pinned environment definitions (environment.yml).
- GPU: NVIDIA GPU with CUDA support and >=6GB VRAM (tested and benchmarked on NVIDIA GeForce RTX 2060, 6GB VRAM)
- RAM: >=16GB system memory
- Storage: >=50GB for raw imagery, intermediate arrays, and cartographic products
- Operating System: Windows (10/11) or Linux (Ubuntu 20.04+)
- Python: 3.9 (benchmarked on 3.9.21)
- CUDA: 11.8 (PyTorch 2.3.1 with CUDA 11.8)
- Conda: Recommended for reproducible environment management
git clone https://github.com/sxlong2022/BathySurrogate.git
cd BathySurrogateconda env create -f environment.yml
conda activate bathysurrogateThe environment.yml includes all required dependencies:
- PyTorch 2.3.1 (with CUDA 11.8 acceleration)
- scikit-learn 1.6.0
- NumPy 1.24.4, SciPy 1.13.1, pandas 2.0.3
- Google Earth Engine Python API (
earthengine-api>= 1.5.5) - netCDF4 1.7.2, Matplotlib 3.7.5, PyYAML 6.0.2, Pillow 9.5.0, Joblib 1.4.2, tqdm 4.65.2, einops 0.8.0
Run the automated test suite:
python tests/quick_test.pyAll verification checks should report [PASS].
|-- run_bathymetry.py # Main CLI entry point for all execution stages
|-- data_acquisition_preprocessing.py # Sentinel-2 & GEBCO data acquisition (GEE)
|-- miwc.py # Multi-temporal Image Weighted Composition (MIWC)
|-- environment.yml # Conda environment definition
|-- CITATION.cff # Citation metadata format
|-- LICENSE # MIT License
|-- tests/
| \-- quick_test.py # Automated test suite and configuration validator
|-- bathysurrogate/ # Core BathySurrogate Python package
| |-- __init__.py # Package initialization and public API
| |-- main.py # Hybrid system orchestrator (HybridBathymetrySystem)
| |-- classic_models.py # Operational 12-feature Enhanced Random Forest surrogate & baseline models
| |-- preprocessor.py # Min-Max normalization & spatial blocking partitions
| |-- s3gm_wrapper.py # S³GM generative diffusion model wrapper
| |-- s3gm_config.py # S³GM hyperparameter dataclass
| |-- gpu_memory.py # GPU VRAM garbage collection and monitoring
| \-- utils.py # Spatio-temporal array utilities and validation
|-- configs/ # Externalized YAML configuration files
| |-- classic_models.yaml # Random Forest hyperparameters & feature configs
| |-- s3gm_default.yaml # Diffusion SDE, VPSDE, and DPS sampling parameters
| \-- figures.yaml # Figure pipeline paths, styling, and ablation tiers
|-- scripts/ # Reproducible analysis and figure pipeline
| |-- _common.py # Shared paths, metrics, and publication styling
| |-- build_oof_predictions.py # Builds the out-of-fold SSOT prediction table
| |-- build_rf_time_series.py # Annual surrogate raster stack (2018-2023)
| |-- harmonize_ablation_experiment.py # 12-feature ablation ladder
| |-- generate_ablation_data_and_plot.py # Ablation experiment + Figure 3
| |-- compute_block_sensitivity.py # 4x4 vs 6x6 block geometry check (Table S3)
| |-- compute_block_wilcoxon.py # Block-level paired Wilcoxon tests
| |-- compute_strata_metrics.py # Depth and distance stratification tables
| |-- compute_temporal_metrics.py # Year-to-year consistency metrics
| |-- plot_figure3.py # Figure 3 Feature ablation ladder
| |-- plot_figure4.py # Figure 4 Multi-model OOF scatter
| |-- plot_figure5.py # Figure 5 Block-level inference
| |-- plot_figure6.py # Figure 6 Depth and distance strata
| |-- plot_figure7.py # Figure 7 Decadal mapping
| |-- plot_figure_s2.py # Figure S2 S3GM performance dichotomy
| |-- plot_figure_s3.py # Figure S3 Block geometry sensitivity
| \-- plot_all_figures.py # Renders Figures 3-7 and S2-S3
\-- S3GM/Code/ # S3GM neural core (adapted from Li et al., 2024)
|-- models/ # U-Net video architecture with RPE
|-- sampler/ # VP-SDE predictor-corrector with DPS guidance
\-- trainer/ # Score matching loss and dataset loaders
python tests/quick_test.pyThis verifies:
- Core dependency imports (NumPy, PyYAML, PyTorch, scikit-learn,
bathysurrogate) - CUDA GPU availability and memory detection
- Synthetic Random Forest surrogate training and inference
- YAML configuration loading and parameter validation
- S³GM model wrapper configuration initialization
The framework operates via modular CLI stages:
# Stage 1: Data Acquisition & Preprocessing (Sentinel-2 MIWC + GEBCO downsampling)
python run_bathymetry.py --stage 1
# Stage 1.5: Surrogate Model Training (Full & 5-Fold Spatially Blocked CV)
python run_bathymetry.py --stage 1.5
# Stage 1.8: Surrogate Model Out-of-Fold (OOF) Spatial Validation
python run_bathymetry.py --stage 1.8
# Stage 2: S³GM Spatio-Temporal Generative Diffusion Sampling
python run_bathymetry.py --stage 2
# Stage 3: Post-processing, Denormalization, and Spatial Visualization
python run_bathymetry.py --stage 3
# Stage 4: Statistical Significance Analysis (Wilcoxon Signed-Rank Test)
python run_bathymetry.py --stage 4
# Stage 5: Detailed Performance Stratification Across Depth & Slope Zones
python run_bathymetry.py --stage 5Note on Google Earth Engine: Before running Stage 1, ensure you authenticate and initialize your GEE account:
ee.Authenticate() ee.Initialize(project='YOUR_GEE_PROJECT_ID')
The scripts/ directory regenerates every analysis table and figure from
stored artefacts. Derived data (results/, intermediate_results/) is
excluded from version control. Point the pipeline at an existing data tree
with an environment variable:
export BATHYSURROGATE_DATA_ROOT=/path/to/data_tree # Linux/macOS
set BATHYSURROGATE_DATA_ROOT=D:\path\to\data_tree # WindowsWhen the variable is unset, the repository root is used.
python scripts/build_oof_predictions.py # out-of-fold SSOT table
python scripts/build_rf_time_series.py # annual surrogate stack
python scripts/compute_block_sensitivity.py # Table S3 geometry checkpython scripts/compute_block_wilcoxon.py # block-level paired tests
python scripts/compute_strata_metrics.py # depth and distance strata
python scripts/compute_temporal_metrics.py # year-to-year consistencypython scripts/generate_ablation_data_and_plot.py # Figure 3
python scripts/plot_all_figures.py # Figures 3-7 and S2-S3Each figure is written to results/Figures/<name>/ as a 300 dpi PNG and
a vector PDF. Figure 1 (study area) and Figure 2 (validation protocol) are
produced by the cartography stage and a vector editor respectively.
- All metrics derive from out-of-fold predictions in
results/validation/oof_predictions_all_models.csv. - Statistical inference operates on spatial blocks, never on pixels.
- The distance metric is written
IDW (power = 4). The symbolpis reserved for statistical p-values and probability densities.
All model hyperparameters and feature engineering settings are externalized into human-readable YAML files:
rf_params:
model_params:
n_estimators: 500
max_depth: 25
max_features: 'sqrt'
random_state: 42
n_jobs: -1
oob_score: truesde_type: 'vpsde'
beta_min: 0.1
beta_max: 1000 # VPSDE scaling parameter
sampling:
alpha: 0.1 # DPS data fidelity guidance weight
gamma_spatial: 0.1 # Spatial smoothness regularization weight
inner_loop: 1 # Langevin corrector steps
snr: 0.01 # Signal-to-noise ratioIf you use BathySurrogate in your research, please cite:
@article{song2026bathysurrogate,
title={BathySurrogate: An Open-Source, Chart-Conditioned Geospatial Surrogate Framework for Coastal Bathymetry via Multi-Source Data Fusion and Spatial Validation},
author={Song, Xiaolong and Liu, Boliang and Xiao, Zhong and Xu, Haijue and Bai, Yuchuan},
journal={Environmental Modelling \& Software},
year={2026},
note={Under Review}
}This project is licensed under the MIT License - see the LICENSE file for details.
- GitHub Issues: https://github.com/sxlong2022/BathySurrogate/issues
- Maintainer: Xiaolong Song (xlsong@tju.edu.cn), Tianjin University