SWORD-CTRIP Mapping (SCM v1.0): A Confidence-Aware Framework for Mapping Satellite-Derived River Reaches to Gridded Routing Networks

Overview This repository implements a confidence-aware global mapping pipeline that assigns river reaches from SWORD v17b to CTRIP 1/12° routing pixels. Assignments combine geometric and hydrological criteria: reach–pixel intersection distance to pixel centroid upstream area consistency (MERIT vs CTRIP) reach length flow-direction alignment (D8) Each pixel assignment receives a confidence tier: Tier 1 — Single: exactly one intersecting reach (very high confidence) Tier 2 — Scored: multiple candidates, best score passes thresholds (High / Medium / Low) Tier 3 — Fallback: curated/relaxed rules (optional) Tier 4 — Unassigned: no assignment Outputs include per-zone CSV/NetCDF and global aggregates suitable for data assimilation (e.g., CTRIP-HyDAS) and analysis. Pipeline (A → B → C/H → Z → V) Phase A — SWORD–MERIT filtering & zone setup A_01 PHASE_A_01__assign_merit_basins.py Inputs: SWORD shapefile + NetCDF, MERIT Basin cat/riv, zone table Outputs: SWORD-MERIT_pfaf{pfaf}.nc, removed_unmapped_reaches_pfaf{pfaf}.csv, centerlines_collection_pfaf{pfaf}.npy, plots Purpose: Assign MERIT basin/river IDs; remove ghost/unmapped reaches. A_02a PHASE_A_02a__analyze_removed_reaches.py Inputs: removed/unmapped CSV Outputs: analytics CSVs + histogram plot Purpose: Summarize and visualize unmapped/removed characteristics. (Optional A_02b/A_02c/A_03/A_04 visualization & reassignment helpers are included in the repo; see docs/README_SCRIPTS.md for the full A-phase map.) Phase B — CTRIP assignment, scoring, selection, finalization End-to-end assignment and QA: single-pixel matches (Tier 1), multi-reach scoring (Tier 2), selection and merge, NetCDF write & diagnostics, consistency checks (B_02 … B_05e). Outputs: per-zone final CSV & NetCDF + logs/plots. Phase C — Fallback (optional) For any remaining unassigned pixels: generate candidates (C_01), navigate/inspect (C_02), apply curated reassignments (C_03), verify (C_04), summarize (C_05). Auto-skips if Phase B achieved full coverage. Phase H — Under-utilized observable pixels (optional) analyze filtered-out single/multi pixels with SWOT observability, assign best observable candidate to increase usage (H_01–H_02). Phase Z — Global aggregation Z_01 merge per-zone final CSVs → global CSV Z_02 write global assignment grid (NetCDF) Phase V — Visualization (manuscript figures) V_01 global confidence map + score histogram + tier counts V_02 global pixel map colored by final basin hash, with Pfaf L2 overlay See docs/README_SCRIPTS.md and docs/pipeline_overview.md for a complete step-by-step map and manuscript cross-walk. Data & Configuration Zone mapping – pfaf_lvl_2_mapping.csv Contains Pfaf L2 zone extents & metadata (min/max lon/lat, continent, etc.). A ready-to-edit sample is provided: pfaf_lvl_2_mapping.sample.csv → copy to pfaf_lvl_2_mapping.csv and edit. Central config – config/default_config.yaml Controls output_dir, logging level, and optional scoring/fallback thresholds. Core inputs SWORD v17b: zone subset shapefile (attributes: reach_id, type, lakeflag, strm_order/stream_order) and SWORD NetCDF (reaches + centerlines) MERIT Basin cat/riv: polygon & river line shapefiles per Pfaf L2 CTRIP grid: lon/lat and routing fields (via myPyFunc or aligned NetCDFs you provide) myPyFunc (optional): If present, scripts will use helpers like res2lonlat, trip_param, merit_param. Built-in fallbacks are used where feasible; otherwise provide aligned NetCDFs via CLI flags. Key Outputs Per-zone final_sword_ctrip_assignment_pfaf{pfaf}.csv (and full variants) SWORD-CTRIP_pfaf{pfaf}_clean.nc (and _final.nc after fallback) reassignment_log_pfaf{pfaf}.csv, diagnostics CSVs, plots Global final_sword_ctrip_assignment_global_full.csv (or .csv.gz) SWORD-CTRIP_assignment_global.nc Manuscript figures from Phase V (PNG) Reproducibility Zone-wise: independent inputs/outputs per zone; trivially parallelizable. Config-driven: no hard-coded directories; all paths via CLI or YAML. Environment: pinned requirements.txt / environment.yml. Determinism: scoring and thresholds are explicit; re-runs reproduce identical outputs given identical inputs.